@flowstack-ui/brick 0.1.5 → 0.1.9

package/dist/agents/carousel.md

@@ -0,0 +1,64 @@
+# Carousel agent guide
+
+## Purpose
+
+Present one item or campaign at a time with optional navigation, picker dots, touch scrolling, and user-controlled rotation.
+
+## Use when
+
+- Several peer items benefit from sharing one bounded visual region.
+- A campaign hero needs multiple authored messages without placing them all in the initial viewport.
+
+## Choose something else when
+
+- Every item must be visible for comparison or comprehension. Use Grid, Stack, List, or Tabs.
+- The content is only decorative image rotation. Use a non-interactive media treatment that respects reduced motion.
+
+## Required composition
+
+- Compose Root, Viewport, Track, and one Slide per unique value; add Navigation, Controls, Previous, Next, Picker, PickerItem, and RotationControl only when the product needs them.
+- In a React Server Component, import the subpath as a module namespace with import * as Carousel from '@flowstack-ui/brick/carousel'; use the frozen Carousel runtime object only inside client components.
+- When automatic rotation is enabled, always render RotationControl, Previous, and Next so people can stop and navigate the sequence; place RotationControl before Viewport in DOM order.
+- Build campaign-specific slide content from Brick layout, typography, action, and media components; Carousel does not own hero messaging or proof content.
+- When artwork, scrim, and copy form one peer campaign, compose a complete Surface with Media, Scrim, and Content inside each Slide; keep genuinely invariant evidence or navigation outside the rotating sequence.
+- When a parent already owns a stable block size, use Root fill to propagate it through Carousel's Viewport, Track, and Slides; continue sizing authored Surface, Content, and layout components explicitly.
+- Match Root radius to the visible containing geometry; use radius=none when an edge-to-edge square Surface owns the campaign boundary.
+
+## Rules
+
+- **MUST:** Treat arrows and picker dots as optional authored controls; dots represent direct slide selection and are not Tabs.
+- **MUST:** Never enable automatic rotation without a visible RotationControl and direct Previous and Next controls.
+- **MUST:** Keep picker treatment independent from arrow visibility; use Picker variant bare for dots without a capsule and Navigation visibility interaction only when arrows remain discoverable through focus, pointer, and touch.
+- **SHOULD:** Use a compact xs ghost RotationControl when the required stop mechanism should remain visually quiet; never remove it while automatic rotation can run.
+- **MUST:** Preserve requested direction at loop boundaries and never clone authored slide content, IDs, controls, or form fields.
+- **MUST:** Keep viewport motion instant until Atom exposes data-initialized; Brick's shipped Carousel CSS already enables smooth motion only after that signal.
+- **SHOULD:** Give campaign slides stable responsive geometry so changing the active slide does not move surrounding page content.
+- **MUST:** Treat fill as internal size propagation, not a viewport-height policy; the application or Block must establish the available parent height.
+- **MUST:** Name the parent layout or section that establishes the definite block size before enabling fill; retain a real wrapper when that wrapper is the sizing box.
+- **MUST:** Treat radius as Viewport and overlay-focus geometry only; it must not alter selection, scrolling, control placement, or slide anatomy.
+- **MUST:** When controls overlay slides, reserve application-owned content safe areas so arrows, rotation controls, and picker targets never obscure authored text or actions.
+- **SHOULD:** Prioritize only initially visible campaign media and defer non-current media when the image delivery layer supports it.
+- **MUST:** Load styles.css or core.css plus carousel.css.
+
+## Common mistakes
+
+- **Avoid:** Using Tabs for picker dots or hiding the only way to stop autoplay. **Instead:** Use PickerItem buttons and render RotationControl whenever autoplay can run.
+- **Avoid:** Putting unrelated proof rails or page sections inside every hero slide. **Instead:** Rotate only the peer campaign content and keep stable page evidence outside the Carousel.
+- **Avoid:** Rotating campaign copy while leaving campaign-specific artwork behind as one unrelated background. **Instead:** Decide whether media is invariant or part of the campaign; when it communicates that campaign, place the complete Surface inside Slide.
+- **Avoid:** Repeating block-size rules across Carousel Viewport, Track, and Slide. **Instead:** Establish the parent height once and opt into Root fill; size only the authored content inside each Slide separately.
+
+## Validation checklist
+
+- Check optional-control compositions, first and last boundaries in both directions, interaction-only arrow discovery, independent picker treatment, native horizontal touch scrolling, focus pause, hover pause, reduced motion, RTL, and screen-reader naming.
+- Confirm inactive slides are unavailable to focus and assistive technology, the overlay-safe Viewport focus indicator remains visible above slide media, control focus rings remain complete at rounded edges, overlay controls do not cover content, complete campaign media changes with its copy, and slide changes do not cause page-level layout shift.
+
+## Related guidance
+
+- `button`
+- `icon-button`
+- `image`
+- `surface`
+- `stack`
+- `grid`
+- `text`
+- `tabs`

package/dist/agents/collapsible.json

@@ -0,0 +1,81 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "collapsible",
+  "name": "Collapsible",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Reveal one independent in-flow region while Atom owns disclosure state, relationships, keyboard behavior, and measured mount lifecycle.",
+  "useWhen": [
+    "One control should progressively reveal one related region without creating an overlay or modal interaction."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Several named peer sections form one coordinated set.",
+      "useInstead": "Accordion"
+    },
+    {
+      "condition": "The temporary content must layer, dismiss outside, lock scroll, or contain focus.",
+      "useInstead": "Dialog, Drawer, Popover, or Menu according to the interaction"
+    }
+  ],
+  "composition": [
+    "Compose Root with one Trigger and one Content; put ContentInner inside Content so visible padding does not corrupt measured animation geometry.",
+    "Use Indicator inside Trigger for the canonical decorative state cue; normal Brick layout and content components belong inside ContentInner."
+  ],
+  "rules": [
+    {
+      "id": "collapsible-anatomy",
+      "level": "must",
+      "statement": "Use Root, Trigger, Content, and ContentInner rather than rebuilding disclosure state, ARIA relationships, measurement, or animation lifecycle."
+    },
+    {
+      "id": "collapsible-single-owner-trigger",
+      "level": "must",
+      "statement": "Let Collapsible Trigger own its finished control recipe; do not compose Button or Icon Button into Trigger because competing visual recipes would own one element."
+    },
+    {
+      "id": "collapsible-content-padding",
+      "level": "must",
+      "statement": "Keep visible padding in ContentInner rather than Content so Atom can measure and animate the region accurately."
+    },
+    {
+      "id": "collapsible-layout-role",
+      "level": "must",
+      "statement": "Use Collapsible for in-flow disclosure, not as a substitute for modal Drawer behavior or responsive Show/Hide policy."
+    },
+    {
+      "id": "collapsible-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus collapsible.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Collapsible Trigger asChild around a finished Button or Icon Button.",
+      "correction": "Use Trigger as the only visual control owner and author its label, icon, and optional Indicator directly."
+    },
+    {
+      "mistake": "Putting padding on Content or animating an application wrapper independently.",
+      "correction": "Keep Content as the measured motion boundary and put visible spacing in ContentInner."
+    },
+    {
+      "mistake": "Choosing Collapsible when the page must be inert behind the open panel.",
+      "correction": "Use Drawer or Dialog so Atom can own modal isolation, focus, dismissal, and scroll locking."
+    }
+  ],
+  "validation": [
+    "Test the accessible Trigger name, aria-expanded/aria-controls relationship, Enter and Space, controlled and uncontrolled state, disabled behavior, and focus retention.",
+    "Test open/close measurement, dynamic content, reduced motion, long labels, narrow widths, RTL, and horizontal overflow.",
+    "When adapting Collapsible inside another surface, report any Root geometry override instead of silently treating plain as a behavior-only recipe."
+  ],
+  "related": [
+    "accordion",
+    "drawer",
+    "app-bar",
+    "nav-list",
+    "show",
+    "hide",
+    "stack"
+  ]
+}

package/dist/agents/collapsible.md

@@ -0,0 +1,49 @@
+# Collapsible agent guide
+
+## Purpose
+
+Reveal one independent in-flow region while Atom owns disclosure state, relationships, keyboard behavior, and measured mount lifecycle.
+
+## Use when
+
+- One control should progressively reveal one related region without creating an overlay or modal interaction.
+
+## Choose something else when
+
+- Several named peer sections form one coordinated set. Use Accordion.
+- The temporary content must layer, dismiss outside, lock scroll, or contain focus. Use Dialog, Drawer, Popover, or Menu according to the interaction.
+
+## Required composition
+
+- Compose Root with one Trigger and one Content; put ContentInner inside Content so visible padding does not corrupt measured animation geometry.
+- Use Indicator inside Trigger for the canonical decorative state cue; normal Brick layout and content components belong inside ContentInner.
+
+## Rules
+
+- **MUST:** Use Root, Trigger, Content, and ContentInner rather than rebuilding disclosure state, ARIA relationships, measurement, or animation lifecycle.
+- **MUST:** Let Collapsible Trigger own its finished control recipe; do not compose Button or Icon Button into Trigger because competing visual recipes would own one element.
+- **MUST:** Keep visible padding in ContentInner rather than Content so Atom can measure and animate the region accurately.
+- **MUST:** Use Collapsible for in-flow disclosure, not as a substitute for modal Drawer behavior or responsive Show/Hide policy.
+- **MUST:** Load styles.css or core.css plus collapsible.css.
+
+## Common mistakes
+
+- **Avoid:** Using Collapsible Trigger asChild around a finished Button or Icon Button. **Instead:** Use Trigger as the only visual control owner and author its label, icon, and optional Indicator directly.
+- **Avoid:** Putting padding on Content or animating an application wrapper independently. **Instead:** Keep Content as the measured motion boundary and put visible spacing in ContentInner.
+- **Avoid:** Choosing Collapsible when the page must be inert behind the open panel. **Instead:** Use Drawer or Dialog so Atom can own modal isolation, focus, dismissal, and scroll locking.
+
+## Validation checklist
+
+- Test the accessible Trigger name, aria-expanded/aria-controls relationship, Enter and Space, controlled and uncontrolled state, disabled behavior, and focus retention.
+- Test open/close measurement, dynamic content, reduced motion, long labels, narrow widths, RTL, and horizontal overflow.
+- When adapting Collapsible inside another surface, report any Root geometry override instead of silently treating plain as a behavior-only recipe.
+
+## Related guidance
+
+- `accordion`
+- `drawer`
+- `app-bar`
+- `nav-list`
+- `show`
+- `hide`
+- `stack`

package/dist/agents/container.json

@@ -24,6 +24,11 @@
       "level": "must",
       "statement": "Use Container rather than repeating application max-width, auto-margin, and gutter CSS across sections."
     },
+    {
+      "id": "container-shared-geometry",
+      "level": "must",
+      "statement": "Give adjacent shell regions that must share alignment lines, such as an App Bar, hero content, and attached proof rail, the same Container measure and gutter recipe."
+    },
     {
       "id": "container-not-surface",
       "level": "must",
@@ -37,18 +42,19 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Applying a separate max-width class to every page section or nesting Containers without a width reason.",
-      "correction": "Use one deliberate Container boundary per aligned content region."
+      "mistake": "Applying a separate max-width class to every page section, giving visually connected shell regions different measures or gutters, or nesting Containers without a width reason.",
+      "correction": "Use one deliberate Container boundary per aligned content region and repeat the same named measure and gutter where separate regions must share a grid line."
     }
   ],
   "validation": [
-    "Check gutters and max width at all adopted breakpoints, zoom levels, and RTL.",
+    "Check gutters, max width, and shared alignment lines at all adopted breakpoints, zoom levels, and RTL.",
     "Confirm full-bleed and contained regions align intentionally and CSS is loaded."
   ],
   "related": [
     "stack",
     "grid",
     "surface",
-    "card"
+    "card",
+    "app-bar"
   ]
 }

package/dist/agents/container.md

@@ -19,16 +19,17 @@ Own consistent centered content width, logical page gutters, and size variants f
 ## Rules
 
 - **MUST:** Use Container rather than repeating application max-width, auto-margin, and gutter CSS across sections.
+- **MUST:** Give adjacent shell regions that must share alignment lines, such as an App Bar, hero content, and attached proof rail, the same Container measure and gutter recipe.
 - **MUST:** Do not use Container as a visual card or background owner.
 - **MUST:** Load styles.css or core.css plus container.css.
 
 ## Common mistakes
 
-- **Avoid:** Applying a separate max-width class to every page section or nesting Containers without a width reason. **Instead:** Use one deliberate Container boundary per aligned content region.
+- **Avoid:** Applying a separate max-width class to every page section, giving visually connected shell regions different measures or gutters, or nesting Containers without a width reason. **Instead:** Use one deliberate Container boundary per aligned content region and repeat the same named measure and gutter where separate regions must share a grid line.
 
 ## Validation checklist
 
-- Check gutters and max width at all adopted breakpoints, zoom levels, and RTL.
+- Check gutters, max width, and shared alignment lines at all adopted breakpoints, zoom levels, and RTL.
 - Confirm full-bleed and contained regions align intentionally and CSS is loaded.
 
 ## Related guidance
@@ -37,3 +38,4 @@ Own consistent centered content width, logical page gutters, and size variants f
 - `grid`
 - `surface`
 - `card`
+- `app-bar`

package/dist/agents/divider.json

@@ -16,7 +16,7 @@
     }
   ],
   "composition": [
-    "Use Divider.Root inside the layout owner shared by the adjacent complete groups and choose decorative=false only when the separation has meaning."
+    "Use Divider inside the layout owner shared by the adjacent complete groups and choose decorative=false only when the separation has meaning."
   ],
   "rules": [
     {

package/dist/agents/divider.md

@@ -14,7 +14,7 @@ Render a finished decorative or semantic content boundary with horizontal or ver
 
 ## Required composition
 
-- Use Divider.Root inside the layout owner shared by the adjacent complete groups and choose decorative=false only when the separation has meaning.
+- Use Divider inside the layout owner shared by the adjacent complete groups and choose decorative=false only when the separation has meaning.
 
 ## Rules
 

package/dist/agents/drawer.json

@@ -16,7 +16,8 @@
     }
   ],
   "composition": [
-    "Compose Trigger and Portal with Overlay and Content; put a header containing Title, Description when useful, and Close inside Content, then use Stack/NavList for its body."
+    "Compose Trigger and Portal with Overlay and Content; put a header containing Title, Description when useful, and Close inside Content, then use Stack/NavList for its body.",
+    "Title is a native heading rather than a polymorphic layout host. Use its as prop to choose the heading level; do not pass a multi-element brand or layout through asChild. When the surface intentionally has no visible heading, give Content an explicit accessible name such as aria-label=\"Mobile navigation\"."
   ],
   "rules": [
     {
@@ -24,6 +25,11 @@
       "level": "must",
       "statement": "Use Drawer parts rather than hand-building overlay, focus trap, Escape, outside interaction, or portal behavior."
     },
+    {
+      "id": "drawer-accessible-name",
+      "level": "must",
+      "statement": "Give Content an accessible name with a concise Title or, when no visible heading is appropriate, an explicit aria-label or aria-labelledby on Content."
+    },
     {
       "id": "drawer-responsive",
       "level": "must",
@@ -58,6 +64,10 @@
     {
       "mistake": "Adding use client to an entire Next page only to dereference the legacy Drawer runtime object.",
       "correction": "Use the RSC-safe module-namespace subpath so only Drawer remains client-owned."
+    },
+    {
+      "mistake": "Using asChild on Title or treating a brand lockup as a heading.",
+      "correction": "Keep branding in the visual header and name Content explicitly when there is no concise visible title."
     }
   ],
   "validation": [

package/dist/agents/drawer.md

@@ -15,10 +15,12 @@ Present a finished modal side sheet while Atom owns focus, dismissal, portal, sc
 ## Required composition
 
 - Compose Trigger and Portal with Overlay and Content; put a header containing Title, Description when useful, and Close inside Content, then use Stack/NavList for its body.
+- Title is a native heading rather than a polymorphic layout host. Use its as prop to choose the heading level; do not pass a multi-element brand or layout through asChild. When the surface intentionally has no visible heading, give Content an explicit accessible name such as aria-label="Mobile navigation".
 
 ## Rules
 
 - **MUST:** Use Drawer parts rather than hand-building overlay, focus trap, Escape, outside interaction, or portal behavior.
+- **MUST:** Give Content an accessible name with a concise Title or, when no visible heading is appropriate, an explicit aria-label or aria-labelledby on Content.
 - **MUST:** Choose size and placement from content needs: use xl when content may need the viewport but should shrink when short, and full only when the surface must always fill it.
 - **MUST:** Let top and bottom Drawers grow naturally to their selected size cap; keep long overflow in Drawer.Body instead of forcing a fixed application height.
 - **MUST:** Use Footer justify for simple action distribution, a Brick layout component inside Footer for complex grouping, and Button fullWidth only when the action itself should fill the row.
@@ -29,6 +31,7 @@ Present a finished modal side sheet while Atom owns focus, dismissal, portal, sc
 
 - **Avoid:** Building a mobile menu as an absolutely positioned div or placing Close outside the labeled content hierarchy. **Instead:** Use Drawer anatomy and compose the menu content with Brick navigation and layout components.
 - **Avoid:** Adding use client to an entire Next page only to dereference the legacy Drawer runtime object. **Instead:** Use the RSC-safe module-namespace subpath so only Drawer remains client-owned.
+- **Avoid:** Using asChild on Title or treating a brand lockup as a heading. **Instead:** Keep branding in the visual header and name Content explicitly when there is no concise visible title.
 
 ## Validation checklist
 

package/dist/agents/frame.json

@@ -0,0 +1,74 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "frame",
+  "name": "Frame",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Own responsive logical size constraints for one local element without taking over layout, paint, spacing, or overflow.",
+  "useWhen": [
+    "A rail, copy region, media canvas, or scroll boundary needs an explicit inline or block size constraint."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The need is shared page measure, child arrangement, paint, aspect ratio, or scrolling.",
+      "useInstead": "Container, Stack/Grid, Surface, AspectRatio, or ScrollArea"
+    }
+  ],
+  "composition": [
+    "Use Frame inside a layout Item, or let Stack.Item/Grid.Item compose asChild around Frame when one host must own both parent participation and internal constraints.",
+    "For bounded long content, put ScrollArea inside a maxBlockSize Frame; Frame constrains and ScrollArea scrolls."
+  ],
+  "rules": [
+    {
+      "id": "frame-constraint-owner",
+      "level": "must",
+      "statement": "Use Frame only for inlineSize, minInlineSize, maxInlineSize, blockSize, minBlockSize, or maxBlockSize."
+    },
+    {
+      "id": "frame-logical",
+      "level": "must",
+      "statement": "Prefer logical size constraints and responsive values rather than physical width/height application classes."
+    },
+    {
+      "id": "frame-parent-participation",
+      "level": "must",
+      "statement": "Keep flex/grid participation on Stack.Item or Grid.Item; Frame owns the constrained element's internal geometry."
+    },
+    {
+      "id": "frame-nesting",
+      "level": "must",
+      "statement": "Use nested Frames when separate ancestors need separate constraints; each Frame keeps its base and responsive values locally scoped."
+    },
+    {
+      "id": "frame-overflow",
+      "level": "must",
+      "statement": "Do not treat maxBlockSize as scrolling; compose ScrollArea when overflow must remain reachable."
+    },
+    {
+      "id": "frame-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus frame.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Turning Frame into a universal Box with paint, spacing, position, overflow, and typography props.",
+      "correction": "Keep Frame to six logical constraints and compose the existing Brick owner for every other responsibility."
+    }
+  ],
+  "validation": [
+    "Check responsive carry-forward, zoom/reflow, long content, RTL, vertical writing, and focus visibility.",
+    "Confirm every constrained node has one clear job and that ScrollArea owns any required overflow."
+  ],
+  "related": [
+    "stack",
+    "grid",
+    "container",
+    "section",
+    "surface",
+    "aspect-ratio",
+    "scroll-area",
+    "interface-composition"
+  ]
+}

package/dist/agents/frame.md

@@ -0,0 +1,47 @@
+# Frame agent guide
+
+## Purpose
+
+Own responsive logical size constraints for one local element without taking over layout, paint, spacing, or overflow.
+
+## Use when
+
+- A rail, copy region, media canvas, or scroll boundary needs an explicit inline or block size constraint.
+
+## Choose something else when
+
+- The need is shared page measure, child arrangement, paint, aspect ratio, or scrolling. Use Container, Stack/Grid, Surface, AspectRatio, or ScrollArea.
+
+## Required composition
+
+- Use Frame inside a layout Item, or let Stack.Item/Grid.Item compose asChild around Frame when one host must own both parent participation and internal constraints.
+- For bounded long content, put ScrollArea inside a maxBlockSize Frame; Frame constrains and ScrollArea scrolls.
+
+## Rules
+
+- **MUST:** Use Frame only for inlineSize, minInlineSize, maxInlineSize, blockSize, minBlockSize, or maxBlockSize.
+- **MUST:** Prefer logical size constraints and responsive values rather than physical width/height application classes.
+- **MUST:** Keep flex/grid participation on Stack.Item or Grid.Item; Frame owns the constrained element's internal geometry.
+- **MUST:** Use nested Frames when separate ancestors need separate constraints; each Frame keeps its base and responsive values locally scoped.
+- **MUST:** Do not treat maxBlockSize as scrolling; compose ScrollArea when overflow must remain reachable.
+- **MUST:** Load styles.css or core.css plus frame.css.
+
+## Common mistakes
+
+- **Avoid:** Turning Frame into a universal Box with paint, spacing, position, overflow, and typography props. **Instead:** Keep Frame to six logical constraints and compose the existing Brick owner for every other responsibility.
+
+## Validation checklist
+
+- Check responsive carry-forward, zoom/reflow, long content, RTL, vertical writing, and focus visibility.
+- Confirm every constrained node has one clear job and that ScrollArea owns any required overflow.
+
+## Related guidance
+
+- `stack`
+- `grid`
+- `container`
+- `section`
+- `surface`
+- `aspect-ratio`
+- `scroll-area`
+- `interface-composition`

package/dist/agents/grid.json

@@ -24,6 +24,11 @@
       "level": "must",
       "statement": "Keep DOM order meaningful; visual placement must not create a confusing keyboard or reading sequence."
     },
+    {
+      "id": "grid-responsive-relationships",
+      "level": "must",
+      "statement": "Use responsive columns, gaps, unanchored spans, and alignment when the same authored Grid changes at Brick breakpoints; keep explicit line starts and ends static."
+    },
     {
       "id": "grid-item-as-child",
       "level": "must",
@@ -40,6 +45,10 @@
       "mistake": "Keeping too many columns until cards become unreadably narrow.",
       "correction": "Reduce columns at the content's real minimum width, not at a device-name breakpoint."
     },
+    {
+      "mistake": "Combining a responsive Item span with explicit line placement.",
+      "correction": "Let the responsive item auto-place, or keep one deliberate static line placement."
+    },
     {
       "mistake": "Adding a Grid.Item wrapper and height CSS around an element that should itself stretch as the grid item.",
       "correction": "Compose that one element with Grid.Item asChild."

package/dist/agents/grid.md

@@ -19,12 +19,14 @@ Arrange content on tokenized two-dimensional tracks with public column, row, gap
 ## Rules
 
 - **MUST:** Keep DOM order meaningful; visual placement must not create a confusing keyboard or reading sequence.
+- **MUST:** Use responsive columns, gaps, unanchored spans, and alignment when the same authored Grid changes at Brick breakpoints; keep explicit line starts and ends static.
 - **MUST:** Use Grid.Item asChild when an existing link, Surface, or component should itself receive placement; provide exactly one element and preserve its native semantics.
 - **MUST:** Load styles.css or core.css plus grid.css.
 
 ## Common mistakes
 
 - **Avoid:** Keeping too many columns until cards become unreadably narrow. **Instead:** Reduce columns at the content's real minimum width, not at a device-name breakpoint.
+- **Avoid:** Combining a responsive Item span with explicit line placement. **Instead:** Let the responsive item auto-place, or keep one deliberate static line placement.
 - **Avoid:** Adding a Grid.Item wrapper and height CSS around an element that should itself stretch as the grid item. **Instead:** Compose that one element with Grid.Item asChild.
 
 ## Validation checklist

package/dist/agents/icon.json

@@ -0,0 +1,98 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "icon",
+  "name": "Icon",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Normalize one consumer-authored SVG with Brick sizing, semantic foreground, alignment, direction, and decorative-or-informative accessibility semantics.",
+  "useWhen": [
+    "An authored SVG needs Brick size, currentColor-based tone, alignment, or opt-in directional RTL mirroring."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The graphic performs an action or needs its own touch target.",
+      "useInstead": "Button, IconButton, Toggle, or the owning interactive component"
+    },
+    {
+      "condition": "The content is a photo, raster asset, responsive media object, fallback, or loading state.",
+      "useInstead": "Image"
+    },
+    {
+      "condition": "The graphic is a logo, illustration, chart, or multiregion visual with independent semantics.",
+      "useInstead": "an application-owned SVG or media composition with explicit semantics"
+    }
+  ],
+  "composition": [
+    "Pass exactly one consumer-authored SVG element; prefer the default span wrapper and use asChild only when the direct root must remain that SVG.",
+    "When visible nearby text already provides the meaning, keep Icon decorative; when a standalone icon conveys information, provide label or aria-labelledby.",
+    "Inside an icon-only control, label the control and leave its nested Icon decorative."
+  ],
+  "rules": [
+    {
+      "id": "icon-not-control",
+      "level": "must",
+      "statement": "Use Icon only for visual content; never use it as an interactive host or touch target."
+    },
+    {
+      "id": "icon-accessibility-mode",
+      "level": "must",
+      "statement": "Keep the decorative default when meaning is redundant, or provide exactly one nonempty label or aria-labelledby reference when the standalone graphic is informative."
+    },
+    {
+      "id": "icon-control-name",
+      "level": "must",
+      "statement": "Give an icon-only Button, IconButton, Toggle, or other control its accessible name on the control, not on its nested Icon."
+    },
+    {
+      "id": "icon-current-color",
+      "level": "should",
+      "statement": "Use currentColor for single-color SVG fills or strokes so Brick tone and inherited control state can apply."
+    },
+    {
+      "id": "icon-directional",
+      "level": "must",
+      "statement": "Enable directional only for glyphs whose meaning reverses in RTL, such as arrows and forward/back controls."
+    },
+    {
+      "id": "icon-as-child",
+      "level": "must",
+      "statement": "Use asChild only with one direct non-interactive SVG; never compose Icon onto a button, anchor, input, or other interactive host."
+    },
+    {
+      "id": "icon-layout",
+      "level": "must",
+      "statement": "Use Brick Stack, layout components, or an owning component icon slot for sibling alignment instead of wrapper spans or application offsets."
+    },
+    {
+      "id": "icon-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus icon.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using a raw SVG with ad hoc width, color, alignment, or ARIA inside ordinary Brick composition.",
+      "correction": "Wrap the authored SVG in Icon, choose the semantic size/tone recipe, and let the owning Stack or control align it."
+    },
+    {
+      "mistake": "Giving both the control and its nested Icon the same accessible label.",
+      "correction": "Label the control and keep the nested Icon decorative to prevent duplicate announcements."
+    },
+    {
+      "mistake": "Using directional on logos, status symbols, checks, clocks, or other glyphs that do not reverse meaning in RTL.",
+      "correction": "Leave directional false unless the glyph itself communicates direction."
+    }
+  ],
+  "validation": [
+    "Check decorative and informative accessibility trees, icon-only control naming, all sizes and tones, currentColor adoption, flex shrinking, and RTL directional mirroring.",
+    "Confirm asChild targets only one SVG and that CSS is present."
+  ],
+  "related": [
+    "icon-button",
+    "image",
+    "button",
+    "stack",
+    "text"
+  ]
+}

package/dist/agents/icon.md

@@ -0,0 +1,51 @@
+# Icon agent guide
+
+## Purpose
+
+Normalize one consumer-authored SVG with Brick sizing, semantic foreground, alignment, direction, and decorative-or-informative accessibility semantics.
+
+## Use when
+
+- An authored SVG needs Brick size, currentColor-based tone, alignment, or opt-in directional RTL mirroring.
+
+## Choose something else when
+
+- The graphic performs an action or needs its own touch target. Use Button, IconButton, Toggle, or the owning interactive component.
+- The content is a photo, raster asset, responsive media object, fallback, or loading state. Use Image.
+- The graphic is a logo, illustration, chart, or multiregion visual with independent semantics. Use an application-owned SVG or media composition with explicit semantics.
+
+## Required composition
+
+- Pass exactly one consumer-authored SVG element; prefer the default span wrapper and use asChild only when the direct root must remain that SVG.
+- When visible nearby text already provides the meaning, keep Icon decorative; when a standalone icon conveys information, provide label or aria-labelledby.
+- Inside an icon-only control, label the control and leave its nested Icon decorative.
+
+## Rules
+
+- **MUST:** Use Icon only for visual content; never use it as an interactive host or touch target.
+- **MUST:** Keep the decorative default when meaning is redundant, or provide exactly one nonempty label or aria-labelledby reference when the standalone graphic is informative.
+- **MUST:** Give an icon-only Button, IconButton, Toggle, or other control its accessible name on the control, not on its nested Icon.
+- **SHOULD:** Use currentColor for single-color SVG fills or strokes so Brick tone and inherited control state can apply.
+- **MUST:** Enable directional only for glyphs whose meaning reverses in RTL, such as arrows and forward/back controls.
+- **MUST:** Use asChild only with one direct non-interactive SVG; never compose Icon onto a button, anchor, input, or other interactive host.
+- **MUST:** Use Brick Stack, layout components, or an owning component icon slot for sibling alignment instead of wrapper spans or application offsets.
+- **MUST:** Load styles.css or core.css plus icon.css.
+
+## Common mistakes
+
+- **Avoid:** Using a raw SVG with ad hoc width, color, alignment, or ARIA inside ordinary Brick composition. **Instead:** Wrap the authored SVG in Icon, choose the semantic size/tone recipe, and let the owning Stack or control align it.
+- **Avoid:** Giving both the control and its nested Icon the same accessible label. **Instead:** Label the control and keep the nested Icon decorative to prevent duplicate announcements.
+- **Avoid:** Using directional on logos, status symbols, checks, clocks, or other glyphs that do not reverse meaning in RTL. **Instead:** Leave directional false unless the glyph itself communicates direction.
+
+## Validation checklist
+
+- Check decorative and informative accessibility trees, icon-only control naming, all sizes and tones, currentColor adoption, flex shrinking, and RTL directional mirroring.
+- Confirm asChild targets only one SVG and that CSS is present.
+
+## Related guidance
+
+- `icon-button`
+- `image`
+- `button`
+- `stack`
+- `text`