@flowstack-ui/brick 0.1.4 → 0.1.6

package/dist/agents/carousel.json

@@ -0,0 +1,131 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "carousel",
+  "name": "Carousel",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present one item or campaign at a time with optional navigation, picker dots, touch scrolling, and user-controlled rotation.",
+  "useWhen": [
+    "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."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Every item must be visible for comparison or comprehension.",
+      "useInstead": "Grid, Stack, List, or Tabs"
+    },
+    {
+      "condition": "The content is only decorative image rotation.",
+      "useInstead": "a non-interactive media treatment that respects reduced motion"
+    }
+  ],
+  "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": [
+    {
+      "id": "carousel-optional-controls",
+      "level": "must",
+      "statement": "Treat arrows and picker dots as optional authored controls; dots represent direct slide selection and are not Tabs."
+    },
+    {
+      "id": "carousel-autoplay-control",
+      "level": "must",
+      "statement": "Never enable automatic rotation without a visible RotationControl and direct Previous and Next controls."
+    },
+    {
+      "id": "carousel-control-independence",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "carousel-quiet-rotation-control",
+      "level": "should",
+      "statement": "Use a compact xs ghost RotationControl when the required stop mechanism should remain visually quiet; never remove it while automatic rotation can run."
+    },
+    {
+      "id": "carousel-loop-direction",
+      "level": "must",
+      "statement": "Preserve requested direction at loop boundaries and never clone authored slide content, IDs, controls, or form fields."
+    },
+    {
+      "id": "carousel-initial-motion-gate",
+      "level": "must",
+      "statement": "Keep viewport motion instant until Atom exposes data-initialized; Brick's shipped Carousel CSS already enables smooth motion only after that signal."
+    },
+    {
+      "id": "carousel-stable-geometry",
+      "level": "should",
+      "statement": "Give campaign slides stable responsive geometry so changing the active slide does not move surrounding page content."
+    },
+    {
+      "id": "carousel-fill-ownership",
+      "level": "must",
+      "statement": "Treat fill as internal size propagation, not a viewport-height policy; the application or Block must establish the available parent height."
+    },
+    {
+      "id": "carousel-fill-parent",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "carousel-radius-visual-only",
+      "level": "must",
+      "statement": "Treat radius as Viewport and overlay-focus geometry only; it must not alter selection, scrolling, control placement, or slide anatomy."
+    },
+    {
+      "id": "carousel-overlay-safe-area",
+      "level": "must",
+      "statement": "When controls overlay slides, reserve application-owned content safe areas so arrows, rotation controls, and picker targets never obscure authored text or actions."
+    },
+    {
+      "id": "carousel-media-loading",
+      "level": "should",
+      "statement": "Prioritize only initially visible campaign media and defer non-current media when the image delivery layer supports it."
+    },
+    {
+      "id": "carousel-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus carousel.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Tabs for picker dots or hiding the only way to stop autoplay.",
+      "correction": "Use PickerItem buttons and render RotationControl whenever autoplay can run."
+    },
+    {
+      "mistake": "Putting unrelated proof rails or page sections inside every hero slide.",
+      "correction": "Rotate only the peer campaign content and keep stable page evidence outside the Carousel."
+    },
+    {
+      "mistake": "Rotating campaign copy while leaving campaign-specific artwork behind as one unrelated background.",
+      "correction": "Decide whether media is invariant or part of the campaign; when it communicates that campaign, place the complete Surface inside Slide."
+    },
+    {
+      "mistake": "Repeating block-size rules across Carousel Viewport, Track, and Slide.",
+      "correction": "Establish the parent height once and opt into Root fill; size only the authored content inside each Slide separately."
+    }
+  ],
+  "validation": [
+    "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": [
+    "button",
+    "icon-button",
+    "image",
+    "surface",
+    "stack",
+    "grid",
+    "text",
+    "tabs"
+  ]
+}

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 owning Stack, Toolbar, menu, or surface 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": [
     {
@@ -24,6 +24,11 @@
       "level": "must",
       "statement": "Choose semantic versus decorative behavior independently from color, thickness, and orientation."
     },
+    {
+      "id": "divider-group-owner",
+      "level": "must",
+      "statement": "Place Divider between complete semantic or interactive groups under one consistent layout owner; do not split a trigger from the content it controls."
+    },
     {
       "id": "divider-css",
       "level": "must",
@@ -32,17 +37,18 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Using a bordered div or text glyph for every separator.",
-      "correction": "Use Divider when there is a boundary and Stack gap when there is only spacing."
+      "mistake": "Using a bordered div or text glyph for every separator, or placing a Divider inside only part of a repeated group's anatomy.",
+      "correction": "Use Divider when there is a boundary, Stack gap when there is only spacing, and keep repeated boundaries after complete groups under the same owner."
     }
   ],
   "validation": [
-    "Check orientation, contrast, forced colors, zoom, and semantics.",
+    "Check orientation, adjacent-group ownership, contrast, forced colors, zoom, and semantics.",
     "Confirm it is not focusable and CSS is loaded."
   ],
   "related": [
     "stack",
     "toolbar",
-    "surface"
+    "surface",
+    "nav-list"
   ]
 }

package/dist/agents/divider.md

@@ -14,20 +14,21 @@ Render a finished decorative or semantic content boundary with horizontal or ver
 
 ## Required composition
 
-- Use Divider.Root inside the owning Stack, Toolbar, menu, or surface 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
 
 - **MUST:** Choose semantic versus decorative behavior independently from color, thickness, and orientation.
+- **MUST:** Place Divider between complete semantic or interactive groups under one consistent layout owner; do not split a trigger from the content it controls.
 - **MUST:** Load styles.css or core.css plus divider.css.
 
 ## Common mistakes
 
-- **Avoid:** Using a bordered div or text glyph for every separator. **Instead:** Use Divider when there is a boundary and Stack gap when there is only spacing.
+- **Avoid:** Using a bordered div or text glyph for every separator, or placing a Divider inside only part of a repeated group's anatomy. **Instead:** Use Divider when there is a boundary, Stack gap when there is only spacing, and keep repeated boundaries after complete groups under the same owner.
 
 ## Validation checklist
 
-- Check orientation, contrast, forced colors, zoom, and semantics.
+- Check orientation, adjacent-group ownership, contrast, forced colors, zoom, and semantics.
 - Confirm it is not focusable and CSS is loaded.
 
 ## Related guidance
@@ -35,3 +36,4 @@ Render a finished decorative or semantic content boundary with horizontal or ver
 - `stack`
 - `toolbar`
 - `surface`
+- `nav-list`

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,10 +25,30 @@
       "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",
-      "statement": "Choose size, placement, and full-screen mobile presentation from content needs without duplicating mounted dialog trees."
+      "statement": "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."
+    },
+    {
+      "id": "drawer-content-growth",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "drawer-footer-layout",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "drawer-rsc-import",
+      "level": "must",
+      "statement": "In React Server Components, import the component subpath as import * as Drawer from @flowstack-ui/brick/drawer; use the legacy root-package runtime object only inside a client-owned module."
     },
     {
       "id": "drawer-css",
@@ -39,11 +60,20 @@
     {
       "mistake": "Building a mobile menu as an absolutely positioned div or placing Close outside the labeled content hierarchy.",
       "correction": "Use Drawer anatomy and compose the menu content with Brick navigation and layout components."
+    },
+    {
+      "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": [
-    "Test labeling, initial focus, focus containment/return, Escape, overlay, Close, scroll lock, touch, reduced motion, narrow screens, and nested portals.",
-    "Confirm CSS and every composed child component stylesheet are loaded."
+    "Test labeling, initial focus, focus containment/return, Escape, overlay, Close, scroll lock, content growth and capped Body overflow, touch, reduced motion, narrow screens, and nested portals.",
+    "Confirm CSS and every composed child component stylesheet are loaded.",
+    "In a React Server Component consumer, confirm the module-namespace form passes a production prerender without promoting the page to use client."
   ],
   "related": [
     "sidebar",

package/dist/agents/drawer.md

@@ -15,21 +15,29 @@ 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:** Choose size, placement, and full-screen mobile presentation from content needs without duplicating mounted dialog trees.
+- **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.
+- **MUST:** In React Server Components, import the component subpath as import * as Drawer from @flowstack-ui/brick/drawer; use the legacy root-package runtime object only inside a client-owned module.
 - **MUST:** Load styles.css or core.css plus drawer.css.
 
 ## Common mistakes
 
 - **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
 
-- Test labeling, initial focus, focus containment/return, Escape, overlay, Close, scroll lock, touch, reduced motion, narrow screens, and nested portals.
+- Test labeling, initial focus, focus containment/return, Escape, overlay, Close, scroll lock, content growth and capped Body overflow, touch, reduced motion, narrow screens, and nested portals.
 - Confirm CSS and every composed child component stylesheet are loaded.
+- In a React Server Component consumer, confirm the module-namespace form passes a production prerender without promoting the page to use client.
 
 ## Related guidance
 

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"
+  ]
+}