@flowstack-ui/brick 0.1.9 → 0.1.12

package/dist/agents/interface-composition.json

@@ -18,87 +18,260 @@
     {
       "intent": "page width and gutters",
       "use": "Container",
-      "note": "Do not reproduce max-width and inline padding on every section."
+      "note": "Do not reproduce max-width and inline padding on every section.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "container"
+        }
+      ]
     },
     {
       "intent": "major page-region rhythm",
       "use": "Section",
-      "note": "Keep paint in Surface, width and gutters in Container, and local child relationships in Stack or Grid."
+      "note": "Keep paint in Surface, width and gutters in Container, and local child relationships in Stack or Grid.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "section"
+        },
+        {
+          "kind": "component",
+          "id": "surface"
+        },
+        {
+          "kind": "component",
+          "id": "container"
+        },
+        {
+          "kind": "component",
+          "id": "stack"
+        },
+        {
+          "kind": "component",
+          "id": "grid"
+        }
+      ]
     },
     {
       "intent": "row or column relationship",
       "use": "HStack, VStack, or responsive Stack",
-      "note": "Use fixed-axis conveniences when the axis stays fixed and Stack when the same content changes axis at a Brick breakpoint."
+      "note": "Use fixed-axis conveniences when the axis stays fixed and Stack when the same content changes axis at a Brick breakpoint.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "stack"
+        }
+      ]
     },
     {
       "intent": "child flex allocation",
       "use": "Stack.Item",
-      "note": "Choose content-sized, fixed, automatic, or proportional growth before writing flex CSS."
+      "note": "Choose content-sized, fixed, automatic, or proportional growth before writing flex CSS.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "stack"
+        }
+      ]
     },
     {
       "intent": "child grid participation",
       "use": "Grid.Item",
-      "note": "Use spans, placement, or self-alignment; keep a real wrapper when it establishes the participation box and use asChild only when the child should be that box."
+      "note": "Use spans, placement, or self-alignment; keep a real wrapper when it establishes the participation box and use asChild only when the child should be that box.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "grid"
+        }
+      ]
     },
     {
       "intent": "local logical size constraint",
       "use": "Frame",
-      "note": "Use only for inline/block size or min/max constraints; keep parent participation on the owning layout Item and overflow in ScrollArea."
+      "note": "Use only for inline/block size or min/max constraints; keep parent participation on the owning layout Item and overflow in ScrollArea.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "frame"
+        },
+        {
+          "kind": "component",
+          "id": "scroll-area"
+        }
+      ]
     },
     {
       "intent": "overlapping depth relationship",
       "use": "ZStack",
-      "note": "Prefer Surface media anatomy for ordinary media, scrim, and foreground compositions."
+      "note": "Prefer Surface media anatomy for ordinary media, scrim, and foreground compositions.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "z-stack"
+        },
+        {
+          "kind": "component",
+          "id": "surface"
+        }
+      ]
     },
     {
       "intent": "track-based responsive layout",
       "use": "Grid",
-      "note": "Use Stack when only one axis matters."
+      "note": "Use Stack when only one axis matters.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "grid"
+        },
+        {
+          "kind": "component",
+          "id": "stack"
+        }
+      ]
     },
     {
       "intent": "visual region",
       "use": "Surface or Card",
-      "note": "Use Card for titled or actionable contained content and Surface for a general visual boundary."
+      "note": "Use Card for titled or actionable contained content and Surface for a general visual boundary.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "surface"
+        },
+        {
+          "kind": "component",
+          "id": "card"
+        }
+      ]
     },
     {
       "intent": "local light or dark semantic-token boundary",
       "use": "Appearance",
-      "note": "Pass exactly one existing host; it may contain any number of descendants, and Appearance adds no paint, layout, or wrapper."
+      "note": "Pass exactly one existing host; it may contain any number of descendants, and Appearance adds no paint, layout, or wrapper.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "appearance"
+        }
+      ]
     },
     {
       "intent": "brand or content image",
       "use": "Image",
-      "note": "Keep alt text and fallback behavior intentional."
+      "note": "Keep alt text and fallback behavior intentional.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "image"
+        }
+      ]
     },
     {
       "intent": "one of several peer campaigns or authored content regions",
       "use": "Carousel",
-      "note": "Keep invariant evidence outside; let each Slide own a complete Surface when its media and message belong together."
+      "note": "Keep invariant evidence outside; let each Slide own a complete Surface when its media and message belong together.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "carousel"
+        },
+        {
+          "kind": "component",
+          "id": "surface"
+        }
+      ]
     },
     {
       "intent": "site navigation",
       "use": "NavigationMenu or NavList",
-      "note": "Use NavigationMenu for disclosure navigation and NavList for persistent route lists."
+      "note": "Use NavigationMenu for disclosure navigation and NavList for persistent route lists.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "navigation-menu"
+        },
+        {
+          "kind": "component",
+          "id": "nav-list"
+        }
+      ]
     },
     {
       "intent": "responsive desktop and mobile alternatives",
       "use": "Show and Hide",
-      "note": "Use only when interface or content changes; use responsive Stack when only arrangement changes."
+      "note": "Use only when interface or content changes; use responsive Stack when only arrangement changes.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "show"
+        },
+        {
+          "kind": "component",
+          "id": "hide"
+        },
+        {
+          "kind": "component",
+          "id": "stack"
+        }
+      ]
     },
     {
       "intent": "grouped application actions",
       "use": "Toolbar",
-      "note": "Do not use AppBar.Toolbar as an ARIA toolbar."
+      "note": "Do not use AppBar.Toolbar as an ARIA toolbar.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "toolbar"
+        },
+        {
+          "kind": "component",
+          "id": "app-bar"
+        }
+      ]
     },
     {
       "intent": "several related disclosure sections",
       "use": "Accordion",
-      "note": "Preserve Header, Trigger, Content, and ContentInner ownership; use Collapsible for one disclosure."
+      "note": "Preserve Header, Trigger, Content, and ContentInner ownership; use Collapsible for one disclosure.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "accordion"
+        },
+        {
+          "kind": "component",
+          "id": "collapsible"
+        }
+      ]
     },
     {
       "intent": "semantic item or sequence content",
       "use": "List",
-      "note": "Use structured row parts only when needed and keep Trailing compact on narrow screens."
+      "note": "Use structured row parts only when needed and keep Trailing compact on narrow screens.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "list"
+        }
+      ]
+    },
+    {
+      "intent": "extended quotation and attribution",
+      "use": "Blockquote",
+      "note": "Keep Content and Caption as siblings in Root, put the source URL on Content, and use Cite only for a referenced work or source.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "blockquote"
+        },
+        {
+          "kind": "component",
+          "id": "text"
+        }
+      ]
     }
   ],
   "rules": [
@@ -132,11 +305,21 @@
       "level": "must",
       "statement": "Use responsive Grid tracks, gaps, spans, and alignment or responsive ZStack logical placement when only those relationships change; do not duplicate content or change semantic order."
     },
+    {
+      "id": "interface-layout-spacing",
+      "level": "must",
+      "statement": "Use numeric Stack and Grid spacing factors for ordinary rhythm, including responsive values; use explicit CSS spacing only for a measured exception or application token instead of adding layout CSS merely because a value is outside the legacy token scale."
+    },
     {
       "id": "interface-parent-participation",
       "level": "must",
       "statement": "Separate component internal geometry from parent participation; configure the finished component for its anatomy and the owning layout or Item part for its relationship to siblings."
     },
+    {
+      "id": "interface-control-size-alignment",
+      "level": "must",
+      "statement": "Give controls that share a row the same named size so button-like peers share height, control typography, icon scale, and radius; keep editable Input, Textarea, and Combobox text at least 16px while preserving the same outer geometry, and never repair mismatches with per-component heights, transforms, margins, or literal radii."
+    },
     {
       "id": "interface-frame-constraints",
       "level": "must",
@@ -157,6 +340,16 @@
       "level": "must",
       "statement": "Preserve document landmarks and semantic elements when Brick does not provide an owner; Brick-first is not permission to erase HTML meaning."
     },
+    {
+      "id": "interface-blockquote",
+      "level": "must",
+      "statement": "For an extended quotation, use Blockquote and preserve its figure Root, blockquote Content, sibling figcaption Caption, source URL, and cited-work semantics."
+    },
+    {
+      "id": "interface-prose-trust",
+      "level": "must",
+      "statement": "Use Prose only after external content has been sanitized and parsed into trusted React children; keep heading hierarchy, landmarks, link destinations, media alternatives, table semantics, and trust policy application-owned."
+    },
     {
       "id": "interface-responsive-navigation-data",
       "level": "must",
@@ -197,6 +390,16 @@
       "level": "must",
       "statement": "When styles.css or styles/core.css is loaded, change the document canvas, foreground, and body typography through semantic Brick tokens instead of repeating the body bindings that Brick's foundation already owns."
     },
+    {
+      "id": "interface-browser-baseline",
+      "level": "must",
+      "statement": "Keep required HTML, CSS, and Web API behavior within the package or application's declared browser floor; place newer visual and platform features behind a usable baseline rather than assuming parsing, prefixes, emulation, or one engine proves interoperability."
+    },
+    {
+      "id": "interface-browser-transformation",
+      "level": "must",
+      "statement": "Author standards-based CSS and let the declared build target generate historical vendor syntax when supported; use a documented feature-specific fallback or bounded workaround for behavior a transformer cannot supply, and never add prefixes by visual guess."
+    },
     {
       "id": "interface-customization-order",
       "level": "must",
@@ -297,6 +500,7 @@
     "Confirm light to dark to light and dark to light to dark scopes restore the theme's complete semantic foreground, background, boundary, action, focus, status, scrim, shadow, and interaction-state pairs without child-by-child recoloring.",
     "Confirm every portalled visual root either remains inside the intended theme/appearance container or receives an explicit Appearance scope.",
     "Confirm repeated CSS values are theme tokens, component-specific values use documented component tokens, and every remaining direct stable-hook declaration has a complete customization gap report.",
+    "Confirm required syntax matches the declared browser floor, permission-sensitive APIs include a useful rejection path, optional features retain a usable baseline, and portable behavior has representative Chromium, Firefox, and WebKit evidence; treat Playwright WebKit and device emulation as engine evidence rather than physical-platform proof.",
     "Confirm source order follows rendered ownership, static content is separate from interaction assembly when it obscures the component tree, and comments explain why a constraint exists rather than what an obvious line does.",
     "Run the package's CSS-delivery check and the application's accessibility, browser, and performance checks."
   ],
@@ -316,6 +520,8 @@
     "show",
     "hide",
     "accordion",
-    "list"
+    "list",
+    "blockquote",
+    "highlight"
   ]
 }

package/dist/agents/interface-composition.md

@@ -32,6 +32,7 @@ Build complete interfaces from Brick's structural, content, navigation, action,
 - **grouped application actions:** use Toolbar. Do not use AppBar.Toolbar as an ARIA toolbar.
 - **several related disclosure sections:** use Accordion. Preserve Header, Trigger, Content, and ContentInner ownership; use Collapsible for one disclosure.
 - **semantic item or sequence content:** use List. Use structured row parts only when needed and keep Trailing compact on narrow screens.
+- **extended quotation and attribution:** use Blockquote. Keep Content and Caption as siblings in Root, put the source URL on Content, and use Cite only for a referenced work or source.
 
 ## Rules
 
@@ -41,11 +42,15 @@ Build complete interfaces from Brick's structural, content, navigation, action,
 - **MUST:** Build from a blueprint, select the owning Brick components, render their defaults, choose supported props, then apply Theme, Block, or application customization in that order.
 - **MUST:** Keep one copy of content when only its layout changes; use responsive Stack values instead of duplicated Show/Hide trees.
 - **MUST:** Use responsive Grid tracks, gaps, spans, and alignment or responsive ZStack logical placement when only those relationships change; do not duplicate content or change semantic order.
+- **MUST:** Use numeric Stack and Grid spacing factors for ordinary rhythm, including responsive values; use explicit CSS spacing only for a measured exception or application token instead of adding layout CSS merely because a value is outside the legacy token scale.
 - **MUST:** Separate component internal geometry from parent participation; configure the finished component for its anatomy and the owning layout or Item part for its relationship to siblings.
+- **MUST:** Give controls that share a row the same named size so button-like peers share height, control typography, icon scale, and radius; keep editable Input, Textarea, and Combobox text at least 16px while preserving the same outer geometry, and never repair mismatches with per-component heights, transforms, margins, or literal radii.
 - **MUST:** Use Frame for a qualified local logical size constraint instead of repeating width/height CSS or adding size props to a finished component; do not use Frame when Container measure, layout participation, AspectRatio, or ScrollArea owns the actual job.
 - **MUST:** Keep a real layout-item wrapper when it establishes flex or grid participation or the definite parent size required by ScrollArea, Carousel fill, or Image fill; asChild is not a wrapper-removal goal by itself.
 - **MUST:** Do not use Stack, Surface, Button, or another convenient component when a more specific Brick navigation, media, content, or interaction component owns the job.
 - **MUST:** Preserve document landmarks and semantic elements when Brick does not provide an owner; Brick-first is not permission to erase HTML meaning.
+- **MUST:** For an extended quotation, use Blockquote and preserve its figure Root, blockquote Content, sibling figcaption Caption, source URL, and cited-work semantics.
+- **MUST:** Use Prose only after external content has been sanitized and parsed into trusted React children; keep heading hierarchy, landmarks, link destinations, media alternatives, table semantics, and trust policy application-owned.
 - **MUST:** When desktop and mobile require distinct navigation components, share application-owned destination labels, hrefs, values, and ordering while preserving each pattern's correct Brick anatomy; do not duplicate navigation content or force one interaction tree across breakpoints.
 - **MUST:** Use Show and Hide for first-paint visibility; when a controlled interactive overlay may remain open across a breakpoint, synchronize its application state at that boundary so a hidden modal cannot retain focus, scroll lock, or isolation.
 - **SHOULD:** Express reusable brand values through semantic Brick tokens and a theme rather than repeating literal application values.
@@ -54,6 +59,8 @@ Build complete interfaces from Brick's structural, content, navigation, action,
 - **SHOULD:** Use ZStack for reusable nine-position overlap; retain narrow application positioning only for artwork coordinates that ZStack intentionally does not own.
 - **MUST:** Classify findings before changing a package: behavior and accessibility belong to Atom, finished reusable component paint belongs to Brick, brand values belong to Theme, repeated responsive section composition may belong to Block or Blueprint, and one-page art direction remains application-owned.
 - **MUST:** When styles.css or styles/core.css is loaded, change the document canvas, foreground, and body typography through semantic Brick tokens instead of repeating the body bindings that Brick's foundation already owns.
+- **MUST:** Keep required HTML, CSS, and Web API behavior within the package or application's declared browser floor; place newer visual and platform features behind a usable baseline rather than assuming parsing, prefixes, emulation, or one engine proves interoperability.
+- **MUST:** Author standards-based CSS and let the declared build target generate historical vendor syntax when supported; use a documented feature-specific fallback or bounded workaround for behavior a transformer cannot supply, and never add prefixes by visual guess.
 - **MUST:** Do not write a direct declaration against a Brick part until the correct component, supported props, semantic tokens, component tokens, and public compound parts have been checked in order.
 - **MUST:** Target only documented Brick tokens, public compound parts, stable brick-* base classes, documented slots, and documented state attributes; inspected internal wrappers or implementation selectors are not APIs.
 - **MUST:** When a direct stable-hook override remains because no public prop or token expresses the requirement, emit the required customization gap report and classify its owner before treating the interface as complete.
@@ -104,6 +111,7 @@ Emit this record for every native/framework fallback or direct stable-hook decla
 - Confirm light to dark to light and dark to light to dark scopes restore the theme's complete semantic foreground, background, boundary, action, focus, status, scrim, shadow, and interaction-state pairs without child-by-child recoloring.
 - Confirm every portalled visual root either remains inside the intended theme/appearance container or receives an explicit Appearance scope.
 - Confirm repeated CSS values are theme tokens, component-specific values use documented component tokens, and every remaining direct stable-hook declaration has a complete customization gap report.
+- Confirm required syntax matches the declared browser floor, permission-sensitive APIs include a useful rejection path, optional features retain a usable baseline, and portable behavior has representative Chromium, Firefox, and WebKit evidence; treat Playwright WebKit and device emulation as engine evidence rather than physical-platform proof.
 - Confirm source order follows rendered ownership, static content is separate from interaction assembly when it obscures the component tree, and comments explain why a constraint exists rather than what an obvious line does.
 - Run the package's CSS-delivery check and the application's accessibility, browser, and performance checks.
 
@@ -125,3 +133,5 @@ Emit this record for every native/framework fallback or direct stable-hook decla
 - `hide`
 - `accordion`
 - `list`
+- `blockquote`
+- `highlight`

package/dist/agents/kbd.json

@@ -0,0 +1,62 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "kbd",
+  "name": "Kbd",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Render native keyboard-input notation with finished Brick sizing and visual recipes.",
+  "useWhen": [
+    "Copy needs to name a physical or virtual keyboard key or show a compact authored key sequence."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The application must register or execute a shortcut.",
+      "useInstead": "application-owned keyboard behavior"
+    },
+    {
+      "condition": "The content is a technical literal rather than keyboard input.",
+      "useInstead": "Code"
+    }
+  ],
+  "composition": [
+    "Keep Kbd inside meaningful surrounding copy or repeat Kbd for each authored key in a sequence with visible separators outside the key hosts."
+  ],
+  "rules": [
+    {
+      "id": "kbd-native",
+      "level": "must",
+      "statement": "Preserve the one native kbd host and use it only for keyboard-input notation."
+    },
+    {
+      "id": "kbd-passive",
+      "level": "must",
+      "statement": "Do not register shortcuts, listen for keys, translate platform labels, or add interaction inside Kbd."
+    },
+    {
+      "id": "kbd-recipes",
+      "level": "must",
+      "statement": "Select only the documented raised, outline, subtle, or plain variant and sm, md, or lg size."
+    },
+    {
+      "id": "kbd-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus kbd.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Putting an entire shortcut such as Ctrl+Shift+P inside one Kbd host without authored separation.",
+      "correction": "Use one Kbd per key and keep visible separators in the surrounding content owner."
+    }
+  ],
+  "validation": [
+    "Confirm native kbd semantics, closed recipes, readable key sequences, selection and copy, forced colors, zoom, localization, RTL, and CSS delivery.",
+    "Confirm Kbd adds no tab stop, role, shortcut listener, or platform detection."
+  ],
+  "related": [
+    "code",
+    "text",
+    "interface-composition"
+  ]
+}

package/dist/agents/kbd.md

@@ -0,0 +1,40 @@
+# Kbd agent guide
+
+## Purpose
+
+Render native keyboard-input notation with finished Brick sizing and visual recipes.
+
+## Use when
+
+- Copy needs to name a physical or virtual keyboard key or show a compact authored key sequence.
+
+## Choose something else when
+
+- The application must register or execute a shortcut. Use application-owned keyboard behavior.
+- The content is a technical literal rather than keyboard input. Use Code.
+
+## Required composition
+
+- Keep Kbd inside meaningful surrounding copy or repeat Kbd for each authored key in a sequence with visible separators outside the key hosts.
+
+## Rules
+
+- **MUST:** Preserve the one native kbd host and use it only for keyboard-input notation.
+- **MUST:** Do not register shortcuts, listen for keys, translate platform labels, or add interaction inside Kbd.
+- **MUST:** Select only the documented raised, outline, subtle, or plain variant and sm, md, or lg size.
+- **MUST:** Load styles.css or core.css plus kbd.css.
+
+## Common mistakes
+
+- **Avoid:** Putting an entire shortcut such as Ctrl+Shift+P inside one Kbd host without authored separation. **Instead:** Use one Kbd per key and keep visible separators in the surrounding content owner.
+
+## Validation checklist
+
+- Confirm native kbd semantics, closed recipes, readable key sequences, selection and copy, forced colors, zoom, localization, RTL, and CSS delivery.
+- Confirm Kbd adds no tab stop, role, shortcut listener, or platform detection.
+
+## Related guidance
+
+- `code`
+- `text`
+- `interface-composition`