@flowstack-ui/brick 0.1.4 → 0.1.6

package/dist/agents/interface-composition.md

@@ -8,32 +8,58 @@ Build complete interfaces from Brick's structural, content, navigation, action,
 
 1. Map the page into landmarks, bounded regions, layout relationships, content, navigation, actions, media, and responsive changes.
 2. Choose the Brick owner for each relationship and read every selected component guide before implementation.
-3. Compose from the outside inward: AppBar or page landmark, Container, Grid or Stack, Surface or Card, then content and controls.
-4. Follow the customization order completely: component owner, supported props, semantic theme tokens, component tokens, public parts, and only then a narrow stable-hook escape hatch.
-5. Audit responsive behavior, accessibility, CSS delivery, and native fallbacks before treating the composition as complete.
+3. Compose from the outside inward: AppBar or page landmark, Section, Container, Grid or Stack, Surface or Card, then content and controls.
+4. Decide how each child participates in its parent: content-sized, fixed, automatic, proportional, placed, stretched, or deliberately constrained.
+5. Follow the customization order completely: component owner, supported props, semantic theme tokens, component tokens, public parts, and only then a narrow stable-hook escape hatch.
+6. Audit responsive behavior, accessibility, CSS delivery, and native fallbacks before treating the composition as complete.
 
 ## Selection map
 
 - **page width and gutters:** use Container. Do not reproduce max-width and inline padding on every section.
-- **row or column relationship:** use HStack or VStack. Use Stack when direction is selected dynamically.
+- **major page-region rhythm:** use Section. Keep paint in Surface, width and gutters in Container, and local child relationships in Stack or Grid.
+- **row or column relationship:** use HStack, VStack, or responsive Stack. Use fixed-axis conveniences when the axis stays fixed and Stack when the same content changes axis at a Brick breakpoint.
+- **child flex allocation:** use Stack.Item. Choose content-sized, fixed, automatic, or proportional growth before writing flex CSS.
+- **child grid participation:** use Grid.Item. 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.
+- **local logical size constraint:** use Frame. Use only for inline/block size or min/max constraints; keep parent participation on the owning layout Item and overflow in ScrollArea.
+- **overlapping depth relationship:** use ZStack. Prefer Surface media anatomy for ordinary media, scrim, and foreground compositions.
 - **track-based responsive layout:** use Grid. Use Stack when only one axis matters.
 - **visual region:** use Surface or Card. Use Card for titled or actionable contained content and Surface for a general visual boundary.
+- **local light or dark semantic-token boundary:** use Appearance. Pass exactly one existing host; it may contain any number of descendants, and Appearance adds no paint, layout, or wrapper.
 - **brand or content image:** use Image. Keep alt text and fallback behavior intentional.
+- **one of several peer campaigns or authored content regions:** use Carousel. Keep invariant evidence outside; let each Slide own a complete Surface when its media and message belong together.
 - **site navigation:** use NavigationMenu or NavList. Use NavigationMenu for disclosure navigation and NavList for persistent route lists.
-- **responsive desktop and mobile alternatives:** use Show and Hide. Keep one CSS-controlled breakpoint contract and avoid hydration-dependent visibility.
+- **responsive desktop and mobile alternatives:** use Show and Hide. Use only when interface or content changes; use responsive Stack when only arrangement changes.
 - **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.
 
 ## Rules
 
 - **MUST:** Assign page structure to Brick components before writing element-level CSS.
+- **MUST:** Use Section's named responsive rhythm for major page regions; use as=div when spacing is needed without thematic section semantics.
+- **MUST:** When Surface paint must cover Section rhythm, compose Surface asChild around Section so one host keeps the responsibilities separate.
+- **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:** 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:** 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:** 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.
+- **MUST:** For a locally dark or light region, pass the existing region owner as the one direct child of Appearance and provide complete appearance-dependent color and shadow values for explicit light and dark re-entry; keep typography, density, geometry, and motion on the shared Theme root, and do not recolor descendants independently or add a Surface only to carry appearance.
+- **MUST:** When a portal leaves a local appearance scope, either target a portal container inside that scope or apply Appearance to every portalled visual root; never assume the trigger's CSS ancestry crosses the portal.
+- **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:** 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.
 - **SHOULD:** Classify repeated purposeful sections as Block candidates and repeated page arrangements as Blueprint candidates only after real reuse evidence.
+- **SHOULD:** Split long product compositions by stable responsibility—authored content, repeated item, invariant supporting region, and outer assembly—without pretending those local modules are reusable Brick components.
+- **MUST:** Comment non-obvious ownership, accessibility order, breakpoint, sizing, and browser-lifecycle constraints; do not add comments that only translate a component name or prop into prose.
 
 ## Customization order
 
@@ -73,19 +99,29 @@ Emit this record for every native/framework fallback or direct stable-hook decla
 
 - Inspect the rendered DOM, accessible names, heading order, landmarks, focus order, keyboard operation, touch targets, contrast, zoom, and RTL behavior.
 - Test every adopted breakpoint without JavaScript-dependent first-paint flicker.
-- Confirm layout primitives own ordinary gap, alignment, wrapping, width, and visibility before accepting custom CSS.
+- Confirm layout primitives own ordinary gap, alignment, wrapping, width, and visibility before accepting custom CSS; verify separately meaningful inline nodes use layout gap rather than literal spaces or offsets.
+- Confirm every ScrollArea, Carousel fill, and Image fill composition can name the ancestor that establishes its definite size; use Frame when that ancestor needs an explicit logical size constraint, and never expect the child to invent it.
+- 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 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.
 
 ## Related guidance
 
 - `layer-selection`
+- `appearance`
 - `app-bar`
+- `section`
 - `container`
 - `stack`
+- `z-stack`
 - `grid`
+- `frame`
 - `surface`
 - `card`
 - `navigation-menu`
 - `show`
 - `hide`
+- `accordion`
+- `list`

package/dist/agents/layer-selection.json

@@ -48,6 +48,16 @@
       "intent": "navigation destination",
       "use": "Link or Button with href",
       "note": "Use Link for ordinary navigation and Button only for an emphasized destination."
+    },
+    {
+      "intent": "grouped disclosure sections",
+      "use": "Accordion",
+      "note": "Choose Collapsible for one independent disclosure and Tabs for one shared switching panel."
+    },
+    {
+      "intent": "ordered or unordered content",
+      "use": "List",
+      "note": "Choose NavList, an interactive collection, Table, or DataGrid when rows navigate, select, activate, or expose data relationships."
     }
   ],
   "rules": [
@@ -102,6 +112,8 @@
     "text",
     "image",
     "show",
-    "hide"
+    "hide",
+    "accordion",
+    "list"
   ]
 }

package/dist/agents/layer-selection.md

@@ -21,6 +21,8 @@ Choose the correct FLOWSTACK layer and require Brick-first composition when buil
 - **responsive presence:** use Show or Hide. Use CSS media visibility rather than rendering two JavaScript-controlled trees.
 - **image with resilient loading:** use Image. Use an adapter only when a framework image optimizer provides a measured capability Brick lacks.
 - **navigation destination:** use Link or Button with href. Use Link for ordinary navigation and Button only for an emphasized destination.
+- **grouped disclosure sections:** use Accordion. Choose Collapsible for one independent disclosure and Tabs for one shared switching panel.
+- **ordered or unordered content:** use List. Choose NavList, an interactive collection, Table, or DataGrid when rows navigate, select, activate, or expose data relationships.
 
 ## Rules
 
@@ -55,3 +57,5 @@ Choose the correct FLOWSTACK layer and require Brick-first composition when buil
 - `image`
 - `show`
 - `hide`
+- `accordion`
+- `list`

package/dist/agents/list.json

@@ -0,0 +1,80 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "list",
+  "name": "List",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Render finished ordered or unordered content with native list semantics, optional structured rows, markers, density, and boundaries.",
+  "useWhen": [
+    "Content is naturally a set of peer items or a sequence and needs Brick's finished list presentation."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Rows are persistent route destinations or need current-route state.",
+      "useInstead": "NavList"
+    },
+    {
+      "condition": "Rows form a keyboard-operated choice, action collection, data table, or two-dimensional grid.",
+      "useInstead": "Listbox, Menu, Table, or DataGrid according to the interaction"
+    },
+    {
+      "condition": "Content only needs visual spacing and has no list relationship.",
+      "useInstead": "Stack or Grid"
+    }
+  ],
+  "composition": [
+    "Compose Root > Item; for structured rows use Leading, Content with Title and Description, then Trailing in that order.",
+    "Use ordered only when sequence changes meaning and preserve native list hosts when composing with asChild or render.",
+    "Keep Trailing for compact metadata or controls; when a long action would narrow supporting copy, place the action with the title inside Content using Brick layout instead."
+  ],
+  "rules": [
+    {
+      "id": "list-native-relationship",
+      "level": "must",
+      "statement": "Use List only for a real item or sequence relationship and preserve native list semantics."
+    },
+    {
+      "id": "list-structured-order",
+      "level": "must",
+      "statement": "Keep structured row parts in Leading, Content, Trailing order and use one Content and one Trailing maximum per Item."
+    },
+    {
+      "id": "list-trailing-width",
+      "level": "must",
+      "statement": "Keep Trailing compact; move long actions into a Content-owned layout when a fixed trailing column would damage narrow-screen reading."
+    },
+    {
+      "id": "list-no-interaction",
+      "level": "must",
+      "statement": "Do not add row selection, activation, focus movement, or navigation behavior to List; choose the component that owns that interaction."
+    },
+    {
+      "id": "list-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus list.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using List as a generic row layout, making an Item itself clickable, or placing a long action in Trailing until supporting text becomes a narrow column.",
+      "correction": "Use Stack or Grid for non-list layout, NavList or another interaction owner for clickable rows, and move long actions into Content's own layout."
+    },
+    {
+      "mistake": "Assuming an Item's disabled presentation disables controls inside it.",
+      "correction": "Apply the proper disabled contract to every interactive descendant; List's disabled state is descriptive and visual only."
+    }
+  ],
+  "validation": [
+    "Inspect ul or ol and li output, ordered meaning, marker behavior, structured-part order, nesting, roles, and CSS delivery.",
+    "Test long titles and descriptions, compact and comfortable density, all variants and markers, 320 CSS px, 200 and 400 percent zoom, RTL, and forced colors.",
+    "Confirm Trailing content does not squeeze Content, controls have names and touch targets, disabled descendants are handled explicitly, and List adds no keyboard model."
+  ],
+  "related": [
+    "nav-list",
+    "stack",
+    "grid",
+    "text",
+    "divider"
+  ]
+}

package/dist/agents/list.md

@@ -0,0 +1,48 @@
+# List agent guide
+
+## Purpose
+
+Render finished ordered or unordered content with native list semantics, optional structured rows, markers, density, and boundaries.
+
+## Use when
+
+- Content is naturally a set of peer items or a sequence and needs Brick's finished list presentation.
+
+## Choose something else when
+
+- Rows are persistent route destinations or need current-route state. Use NavList.
+- Rows form a keyboard-operated choice, action collection, data table, or two-dimensional grid. Use Listbox, Menu, Table, or DataGrid according to the interaction.
+- Content only needs visual spacing and has no list relationship. Use Stack or Grid.
+
+## Required composition
+
+- Compose Root > Item; for structured rows use Leading, Content with Title and Description, then Trailing in that order.
+- Use ordered only when sequence changes meaning and preserve native list hosts when composing with asChild or render.
+- Keep Trailing for compact metadata or controls; when a long action would narrow supporting copy, place the action with the title inside Content using Brick layout instead.
+
+## Rules
+
+- **MUST:** Use List only for a real item or sequence relationship and preserve native list semantics.
+- **MUST:** Keep structured row parts in Leading, Content, Trailing order and use one Content and one Trailing maximum per Item.
+- **MUST:** Keep Trailing compact; move long actions into a Content-owned layout when a fixed trailing column would damage narrow-screen reading.
+- **MUST:** Do not add row selection, activation, focus movement, or navigation behavior to List; choose the component that owns that interaction.
+- **MUST:** Load styles.css or core.css plus list.css.
+
+## Common mistakes
+
+- **Avoid:** Using List as a generic row layout, making an Item itself clickable, or placing a long action in Trailing until supporting text becomes a narrow column. **Instead:** Use Stack or Grid for non-list layout, NavList or another interaction owner for clickable rows, and move long actions into Content's own layout.
+- **Avoid:** Assuming an Item's disabled presentation disables controls inside it. **Instead:** Apply the proper disabled contract to every interactive descendant; List's disabled state is descriptive and visual only.
+
+## Validation checklist
+
+- Inspect ul or ol and li output, ordered meaning, marker behavior, structured-part order, nesting, roles, and CSS delivery.
+- Test long titles and descriptions, compact and comfortable density, all variants and markers, 320 CSS px, 200 and 400 percent zoom, RTL, and forced colors.
+- Confirm Trailing content does not squeeze Content, controls have names and touch targets, disabled descendants are handled explicitly, and List adds no keyboard model.
+
+## Related guidance
+
+- `nav-list`
+- `stack`
+- `grid`
+- `text`
+- `divider`

package/dist/agents/manifest.json

@@ -1,14 +1,32 @@
 {
   "schema": "flowstack.agent-manifest.v1",
   "package": "@flowstack-ui/brick",
-  "packageVersion": "0.1.4",
+  "packageVersion": "0.1.6",
   "components": [
+    {
+      "id": "accordion",
+      "name": "Accordion",
+      "json": "./accordion.json",
+      "markdown": "./accordion.md"
+    },
     {
       "id": "app-bar",
       "name": "AppBar",
       "json": "./app-bar.json",
       "markdown": "./app-bar.md"
     },
+    {
+      "id": "appearance",
+      "name": "Appearance",
+      "json": "./appearance.json",
+      "markdown": "./appearance.md"
+    },
+    {
+      "id": "badge",
+      "name": "Badge",
+      "json": "./badge.json",
+      "markdown": "./badge.md"
+    },
     {
       "id": "bottom-navigation",
       "name": "BottomNavigation",
@@ -33,12 +51,24 @@
       "json": "./card.json",
       "markdown": "./card.md"
     },
+    {
+      "id": "carousel",
+      "name": "Carousel",
+      "json": "./carousel.json",
+      "markdown": "./carousel.md"
+    },
     {
       "id": "checkbox",
       "name": "Checkbox",
       "json": "./checkbox.json",
       "markdown": "./checkbox.md"
     },
+    {
+      "id": "collapsible",
+      "name": "Collapsible",
+      "json": "./collapsible.json",
+      "markdown": "./collapsible.md"
+    },
     {
       "id": "container",
       "name": "Container",
@@ -75,6 +105,12 @@
       "json": "./form.json",
       "markdown": "./form.md"
     },
+    {
+      "id": "frame",
+      "name": "Frame",
+      "json": "./frame.json",
+      "markdown": "./frame.md"
+    },
     {
       "id": "grid",
       "name": "Grid",
@@ -93,6 +129,12 @@
       "json": "./icon-button.json",
       "markdown": "./icon-button.md"
     },
+    {
+      "id": "icon",
+      "name": "Icon",
+      "json": "./icon.json",
+      "markdown": "./icon.md"
+    },
     {
       "id": "image",
       "name": "Image",
@@ -111,6 +153,12 @@
       "json": "./link.json",
       "markdown": "./link.md"
     },
+    {
+      "id": "list",
+      "name": "List",
+      "json": "./list.json",
+      "markdown": "./list.md"
+    },
     {
       "id": "nav-list",
       "name": "NavList",
@@ -135,6 +183,12 @@
       "json": "./scroll-area.json",
       "markdown": "./scroll-area.md"
     },
+    {
+      "id": "section",
+      "name": "Section",
+      "json": "./section.json",
+      "markdown": "./section.md"
+    },
     {
       "id": "show",
       "name": "Show",
@@ -188,6 +242,12 @@
       "name": "Toolbar",
       "json": "./toolbar.json",
       "markdown": "./toolbar.md"
+    },
+    {
+      "id": "z-stack",
+      "name": "ZStack",
+      "json": "./z-stack.json",
+      "markdown": "./z-stack.md"
     }
   ],
   "guides": [

package/dist/agents/nav-list.json

@@ -16,7 +16,7 @@
     }
   ],
   "composition": [
-    "Compose Root > List > Item > Link; use SectionLabel for static groups and add SectionTrigger plus SectionContent only for real collapsible groups."
+    "Compose Root > List > Item > Link; use SectionLabel for static groups and add SectionTrigger plus SectionContent only for real collapsible groups. When repeated rows need Dividers, each Item owns its complete row or collapsible Section before the following boundary."
   ],
   "rules": [
     {
@@ -29,6 +29,16 @@
       "level": "must",
       "statement": "Use NavList's section and item anatomy rather than rebuilding rows, badges, icons, and collapse behavior with arbitrary divs."
     },
+    {
+      "id": "nav-list-group-boundary",
+      "level": "must",
+      "statement": "Place a Divider after the complete navigation item or collapsible section it separates; never place it between a SectionTrigger and the SectionContent that trigger controls, and keep repeated boundaries under one consistent layout owner."
+    },
+    {
+      "id": "nav-list-shell-alignment",
+      "level": "must",
+      "statement": "Use the logical row-padding tokens when labels and trailing artwork need independent alignment with a surrounding shell; do not shift indicators with margins or transforms."
+    },
     {
       "id": "nav-list-css",
       "level": "must",
@@ -37,18 +47,19 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Using buttons for routes or adding a collapsible trigger that controls no content.",
-      "correction": "Use Link for destinations and SectionLabel alone for static groups."
+      "mistake": "Using buttons for routes, adding a collapsible trigger that controls no content, placing a Divider between a trigger and its controlled destinations, or moving disclosure indicators with positional CSS.",
+      "correction": "Use Link for destinations, SectionLabel alone for static groups, keep a collapsible Section intact before its boundary, and use the logical row-padding tokens for shell alignment."
     }
   ],
   "validation": [
-    "Check current, hover, focus, collapsed, expanded, long labels, icons, counts, zoom, narrow widths, and RTL.",
+    "Check current, hover, focus, collapsed, expanded, complete-group divider placement, long labels, icons, counts, zoom, narrow widths, and RTL.",
     "Confirm links and section relationships remain semantic and CSS is loaded."
   ],
   "related": [
     "sidebar",
     "drawer",
     "navigation-menu",
-    "link"
+    "link",
+    "divider"
   ]
 }

package/dist/agents/nav-list.md

@@ -14,21 +14,23 @@ Style persistent route navigation with current state, optional section labels, a
 
 ## Required composition
 
-- Compose Root > List > Item > Link; use SectionLabel for static groups and add SectionTrigger plus SectionContent only for real collapsible groups.
+- Compose Root > List > Item > Link; use SectionLabel for static groups and add SectionTrigger plus SectionContent only for real collapsible groups. When repeated rows need Dividers, each Item owns its complete row or collapsible Section before the following boundary.
 
 ## Rules
 
 - **MUST:** Set current destination state from the route and keep route items as links.
 - **MUST:** Use NavList's section and item anatomy rather than rebuilding rows, badges, icons, and collapse behavior with arbitrary divs.
+- **MUST:** Place a Divider after the complete navigation item or collapsible section it separates; never place it between a SectionTrigger and the SectionContent that trigger controls, and keep repeated boundaries under one consistent layout owner.
+- **MUST:** Use the logical row-padding tokens when labels and trailing artwork need independent alignment with a surrounding shell; do not shift indicators with margins or transforms.
 - **MUST:** Load styles.css or core.css plus nav-list.css.
 
 ## Common mistakes
 
-- **Avoid:** Using buttons for routes or adding a collapsible trigger that controls no content. **Instead:** Use Link for destinations and SectionLabel alone for static groups.
+- **Avoid:** Using buttons for routes, adding a collapsible trigger that controls no content, placing a Divider between a trigger and its controlled destinations, or moving disclosure indicators with positional CSS. **Instead:** Use Link for destinations, SectionLabel alone for static groups, keep a collapsible Section intact before its boundary, and use the logical row-padding tokens for shell alignment.
 
 ## Validation checklist
 
-- Check current, hover, focus, collapsed, expanded, long labels, icons, counts, zoom, narrow widths, and RTL.
+- Check current, hover, focus, collapsed, expanded, complete-group divider placement, long labels, icons, counts, zoom, narrow widths, and RTL.
 - Confirm links and section relationships remain semantic and CSS is loaded.
 
 ## Related guidance
@@ -37,3 +39,4 @@ Style persistent route navigation with current state, optional section labels, a
 - `drawer`
 - `navigation-menu`
 - `link`
+- `divider`

package/dist/agents/navigation-menu.json

@@ -39,6 +39,16 @@
       "level": "must",
       "statement": "Keep contents focused on navigation destinations rather than commands or unrelated marketing panels."
     },
+    {
+      "id": "navigation-menu-panel-link",
+      "level": "must",
+      "statement": "Use Link variant=panel with one direct Surface child when one rich destination should own the complete clickable area; let Surface own inset, radius, border, elevation, and background, and keep all composed children non-interactive and concise."
+    },
+    {
+      "id": "navigation-menu-panel-focus",
+      "level": "must",
+      "statement": "Preserve the panel Link's focus fallback; with a direct Surface the ring follows that Surface, and without one the Link itself must remain visibly focused."
+    },
     {
       "id": "navigation-menu-rsc-import",
       "level": "must",
@@ -58,11 +68,15 @@
     {
       "mistake": "Adding use client to an entire Next page only to dereference the legacy NavigationMenu runtime object.",
       "correction": "Use the RSC-safe module-namespace subpath so only the interactive Navigation Menu parts remain client-owned."
+    },
+    {
+      "mistake": "Placing a small link inside a separately clickable-looking Surface, styling NavigationMenu.Link as a duplicate Surface, or nesting a Link or Button inside NavigationMenu.Link.",
+      "correction": "Wrap one direct Surface child with the panel Link so the anchor owns interaction and Surface owns container paint and geometry."
     }
   ],
   "validation": [
     "Test hover, click, focus, arrow keys, Escape, outside interaction, links, viewport transitions, active-trigger centering, boundary collision, arrow alignment, zoom, narrow widths, and RTL.",
-    "Confirm destination semantics, Root-relative geometry, documented customization hooks, and CSS delivery.",
+    "Confirm destination semantics, Root-relative geometry, panel focus fallback, documented customization hooks, and CSS delivery.",
     "In a React Server Component consumer, confirm the module-namespace form passes a production prerender without promoting the page to use client."
   ],
   "related": [

package/dist/agents/navigation-menu.md

@@ -22,6 +22,8 @@ Present polished disclosure navigation while Atom owns trigger geometry, viewpor
 - **MUST:** Let the horizontal Viewport use Atom's active-trigger-centered, collision-aware position; do not re-center it on the full Navigation Menu list or page header.
 - **MUST:** Do not invent overlay props such as side, align, sideOffset, or alignOffset; NavigationMenu does not expose the floating-overlay positioning API.
 - **MUST:** Keep contents focused on navigation destinations rather than commands or unrelated marketing panels.
+- **MUST:** Use Link variant=panel with one direct Surface child when one rich destination should own the complete clickable area; let Surface own inset, radius, border, elevation, and background, and keep all composed children non-interactive and concise.
+- **MUST:** Preserve the panel Link's focus fallback; with a direct Surface the ring follows that Surface, and without one the Link itself must remain visibly focused.
 - **MUST:** In React Server Components, import the component subpath as import * as NavigationMenu from @flowstack-ui/brick/navigation-menu; use the legacy root-package runtime object only inside a client-owned module.
 - **MUST:** Load styles.css or core.css plus navigation-menu.css and every child component stylesheet.
 
@@ -29,11 +31,12 @@ Present polished disclosure navigation while Atom owns trigger geometry, viewpor
 
 - **Avoid:** Anchoring the panel or arrow to the logo/page, adding custom hover state that fights Atom, or applying Popover-style offset props that NavigationMenu does not own. **Instead:** Keep Viewport and Indicator under Root, let NavigationMenu own geometry and open state, then customize documented recipes, tokens, and public parts.
 - **Avoid:** Adding use client to an entire Next page only to dereference the legacy NavigationMenu runtime object. **Instead:** Use the RSC-safe module-namespace subpath so only the interactive Navigation Menu parts remain client-owned.
+- **Avoid:** Placing a small link inside a separately clickable-looking Surface, styling NavigationMenu.Link as a duplicate Surface, or nesting a Link or Button inside NavigationMenu.Link. **Instead:** Wrap one direct Surface child with the panel Link so the anchor owns interaction and Surface owns container paint and geometry.
 
 ## Validation checklist
 
 - Test hover, click, focus, arrow keys, Escape, outside interaction, links, viewport transitions, active-trigger centering, boundary collision, arrow alignment, zoom, narrow widths, and RTL.
-- Confirm destination semantics, Root-relative geometry, documented customization hooks, and CSS delivery.
+- Confirm destination semantics, Root-relative geometry, panel focus fallback, documented customization hooks, and CSS delivery.
 - 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/scroll-area.json

@@ -5,7 +5,7 @@
   "package": "@flowstack-ui/brick",
   "layer": "brick",
   "kind": "component",
-  "purpose": "Style a bounded scroll viewport and scrollbar anatomy while preserving Atom and native input behavior.",
+  "purpose": "Style a bounded scroll viewport and native scrollbar presentation while preserving Atom and native input behavior.",
   "useWhen": [
     "A rail, code region, table wrapper, or bounded panel needs Brick scrollbar presentation and owned overflow behavior."
   ],
@@ -16,7 +16,7 @@
     }
   ],
   "composition": [
-    "Compose Viewport and the needed Scrollbar/Thumb parts inside Root, adding Corner for two-axis presentation; give the wrapper a real size constraint."
+    "Compose Viewport inside Root and give Root a real size constraint from its parent layout; Brick's current native scrollbar presentation needs no authored Scrollbar or Thumb parts."
   ],
   "rules": [
     {
@@ -24,6 +24,11 @@
       "level": "must",
       "statement": "Provide a bounded size; ScrollArea cannot create meaningful scrolling without a constrained viewport."
     },
+    {
+      "id": "scroll-area-parent-owner",
+      "level": "must",
+      "statement": "Identify the parent that owns the maximum or fixed block size before styling Viewport; do not apply a random height directly to the scrolling part."
+    },
     {
       "id": "scroll-area-native",
       "level": "must",
@@ -43,7 +48,7 @@
   ],
   "validation": [
     "Test both axes, mouse, trackpad, touch, keyboard, focus ring, nested scrolling, mobile tables, zoom, and RTL.",
-    "Confirm the viewport constraint and CSS are loaded."
+    "Confirm the parent constraint, viewport geometry, and CSS are loaded."
   ],
   "related": [
     "table",

package/dist/agents/scroll-area.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Style a bounded scroll viewport and scrollbar anatomy while preserving Atom and native input behavior.
+Style a bounded scroll viewport and native scrollbar presentation while preserving Atom and native input behavior.
 
 ## Use when
 
@@ -14,11 +14,12 @@ Style a bounded scroll viewport and scrollbar anatomy while preserving Atom and
 
 ## Required composition
 
-- Compose Viewport and the needed Scrollbar/Thumb parts inside Root, adding Corner for two-axis presentation; give the wrapper a real size constraint.
+- Compose Viewport inside Root and give Root a real size constraint from its parent layout; Brick's current native scrollbar presentation needs no authored Scrollbar or Thumb parts.
 
 ## Rules
 
 - **MUST:** Provide a bounded size; ScrollArea cannot create meaningful scrolling without a constrained viewport.
+- **MUST:** Identify the parent that owns the maximum or fixed block size before styling Viewport; do not apply a random height directly to the scrolling part.
 - **MUST:** Preserve wheel, trackpad, touch, keyboard, focus, and nested page scrolling.
 - **MUST:** Load styles.css or core.css plus scroll-area.css.
 
@@ -29,7 +30,7 @@ Style a bounded scroll viewport and scrollbar anatomy while preserving Atom and
 ## Validation checklist
 
 - Test both axes, mouse, trackpad, touch, keyboard, focus ring, nested scrolling, mobile tables, zoom, and RTL.
-- Confirm the viewport constraint and CSS are loaded.
+- Confirm the parent constraint, viewport geometry, and CSS are loaded.
 
 ## Related guidance