@flowstack-ui/brick 0.1.3 → 0.1.4

package/docs/guides/agent-knowledge.md

@@ -0,0 +1,44 @@
+# Agent Knowledge
+
+Brick ships public component and cross-component guidance for coding agents
+alongside its runtime and CSS artifacts. Component guidance explains local
+selection, composition, CSS delivery, recurring mistakes, and validation.
+Package guides first explain layer selection and complete-interface
+composition. Neither artifact adds a runtime dependency.
+
+Use `@flowstack-ui/brick/agents/manifest.json` to discover guidance. Its
+separate `guides` and `components` collections point to machine-readable JSON
+and human-readable Markdown. Read `layer-selection` and
+`interface-composition` before choosing individual components, for example:
+
+```text
+@flowstack-ui/brick/agents/field.json
+@flowstack-ui/brick/agents/field.md
+@flowstack-ui/brick/agents/layer-selection.json
+@flowstack-ui/brick/agents/interface-composition.md
+```
+
+The source pair lives beside the component it describes. `agent.json` is the
+structured authority and `agent.md` is generated from it. Brick guidance adds
+finished visual and CSS decisions while referring behavioral ownership to
+Atom. Source, types, public component docs, and tests remain authoritative when
+a guide is incomplete.
+
+Package-level guide sources live under `agents/guides/`. They use
+`flowstack.agent-guide.v1`; component sources continue to use
+`flowstack.agent-component.v1`. Manifest `guides` is additive, so consumers
+that already read only `components` remain compatible.
+
+For a finished Brick interface, search Brick before writing native layout,
+typography, media, navigation, visibility, or control replacements. Ordinary
+Brick applications do not import Atom directly. When no Brick component owns
+the job, record the native or framework fallback and its missing capability.
+
+After selecting a component, read `interface-composition` and follow its
+customization order: supported props, semantic theme tokens, documented
+component tokens, public compound parts, and only then a narrow `className` or
+stable-hook escape hatch. The JSON artifact defines a structured gap report
+for every fallback or direct Brick declaration that remains after this search.
+
+Agent Knowledge is public usage guidance. It does not contain private prompts,
+ranking policy, customer information, or application workflows.

package/docs/guides/appearance-and-tokens.md

@@ -17,6 +17,12 @@ Set an appearance on the document or any subtree:
 
 Remove the attribute to return to the system preference.
 
+The complete stylesheet and modular `core.css` apply the active semantic
+canvas, primary text color, body family, body size, and body line height to the
+document body through a low-specificity foundation rule. Themes normally
+change those semantic values rather than adding another body rule. Consumer
+CSS in a later layer can deliberately replace the document treatment.
+
 ## Custom themes
 
 Override public semantic variables through ordinary CSS:

package/docs/guides/installation.md

@@ -17,7 +17,10 @@ import "@flowstack-ui/brick/styles.css";
 ```
 
 This stylesheet contains default tokens, foundations, released component CSS,
-and required keyframes. Importing JavaScript does not import CSS automatically.
+and required keyframes. Its low-specificity document foundation applies the
+canvas, primary foreground, body family, body size, and body line height from
+Brick's semantic tokens. A theme changes those tokens instead of repeating a
+separate `body` rule. Importing JavaScript does not import CSS automatically.
 
 ## Optional reset
 
@@ -28,8 +31,9 @@ import "@flowstack-ui/brick/reset.css";
 import "@flowstack-ui/brick/styles.css";
 ```
 
-The reset is never included by `styles.css`. Existing applications can omit it
-and keep their own reset or browser defaults.
+The reset is never included by `styles.css`. It owns neutral normalization such
+as page sizing and margin removal; it does not paint the document. Existing
+applications can omit it and keep their own reset or browser defaults.
 
 ## Tokens without components
 
@@ -54,9 +58,10 @@ import "@flowstack-ui/brick/styles/button.css";
 import "@flowstack-ui/brick/styles/card.css";
 ```
 
-`core.css` contains Brick's layer order, default tokens, and component-scoped
-foundations. Import it before component styles. Each component stylesheet owns
-that component's rules and every shared visual recipe it renders internally;
+`core.css` contains Brick's layer order, default tokens, and foundations,
+including the same token-driven document canvas and body typography as the
+complete stylesheet. Import it before component styles. Each component
+stylesheet owns that component's rules and every shared visual recipe it renders internally;
 for example, `checkbox-group.css` already includes the Checkbox artwork and
 `toggle-group.css` already includes the Toggle item recipe. Component styles do
 not repeat tokens or foundations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowstack-ui/brick",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Opinionated styled React components built on @flowstack-ui/atom.",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,9 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./agents/manifest.json": "./dist/agents/manifest.json",
+    "./agents/*.json": "./dist/agents/*.json",
+    "./agents/*.md": "./dist/agents/*.md",
     "./button": {
       "types": "./dist/button.d.ts",
       "default": "./dist/button.js"
@@ -335,11 +338,14 @@
   "files": [
     "dist",
     "docs/guides/installation.md",
-    "docs/guides/appearance-and-tokens.md"
+    "docs/guides/appearance-and-tokens.md",
+    "docs/guides/agent-knowledge.md"
   ],
   "scripts": {
     "clean": "node scripts/clean.mjs",
-    "build": "npm run clean && npm run build:js && npm run build:css",
+    "build": "npm run clean && npm run build:js && npm run build:css && npm run agents:build",
+    "agents:build": "node scripts/build-agent-knowledge.mjs",
+    "agents:check": "node scripts/build-agent-knowledge.mjs --check",
     "build:js": "tsc -p tsconfig.build.json",
     "build:css": "node scripts/build-styles.mjs --mode production",
     "build:css:dev": "node scripts/build-styles.mjs --mode development",
@@ -407,7 +413,7 @@
     "verify:playground-composition": "node scripts/verify-playground-composition.mjs",
     "check": "npm run check:repository",
     "check:focused": "npm run test:component",
-    "check:repository": "npm run verify:repository-contract && npm run test:ownership && npm run docs:component && npm run docs:component:semantic && npm run verify:typography && npm run verify:playground-primitives && npm run verify:playground-stack && npm run verify:playground-grid && npm run verify:playground-container && npm run verify:playground-surface && npm run verify:playground-divider && npm run verify:playground-scroll-area && npm run verify:playground-code && npm run verify:playground-nav-list && npm run verify:playground-sidebar && npm run verify:playground-icon && npm run verify:playground-image && npm run verify:playground-list && npm run verify:playground-composition && npm run build && npm run typecheck:built && npm run test:node:built && npm run test:components && npm run test:css && npm run build:playground:built && npm run build:consumer:built && npm run pack:check && npm run verify:consumers:built",
+    "check:repository": "npm run verify:repository-contract && npm run agents:check && npm run test:ownership && npm run docs:component && npm run docs:component:semantic && npm run verify:typography && npm run verify:playground-primitives && npm run verify:playground-stack && npm run verify:playground-grid && npm run verify:playground-container && npm run verify:playground-surface && npm run verify:playground-divider && npm run verify:playground-scroll-area && npm run verify:playground-code && npm run verify:playground-nav-list && npm run verify:playground-sidebar && npm run verify:playground-icon && npm run verify:playground-image && npm run verify:playground-list && npm run verify:playground-composition && npm run build && npm run typecheck:built && npm run test:node:built && npm run test:components && npm run test:css && npm run build:playground:built && npm run build:consumer:built && npm run pack:check && npm run verify:consumers:built",
     "check:release": "npm run check:repository && npm run test:browser:release:built && npm run verify:consumer:built && npm run size:css",
     "prepublishOnly": "npm run build"
   },
@@ -424,7 +430,7 @@
     "react-dom": ">=18"
   },
   "dependencies": {
-    "@flowstack-ui/atom": "0.20.11"
+    "@flowstack-ui/atom": "0.21.0"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.12.1",