@flowstack-ui/brick 0.1.5 → 0.1.6

package/dist/agents/image.json

@@ -16,7 +16,8 @@
     }
   ],
   "composition": [
-    "Compose Image.Content and optional Image.Fallback inside Image.Root; use Brick Stack or layout components around it rather than wrapper spans for alignment."
+    "Compose Image.Content and optional Image.Fallback inside Image.Root; use Brick Stack or layout components around it rather than wrapper spans for alignment.",
+    "In a React Server Component, import ImageRoot, ImageContent, and ImageFallback directly; the compound Image namespace is intended for client module composition."
   ],
   "rules": [
     {
@@ -34,10 +35,25 @@
       "level": "should",
       "statement": "Reserve dimensions or aspect ratio to prevent layout shift."
     },
+    {
+      "id": "image-parent-fill",
+      "level": "must",
+      "statement": "Use explicit fill when Image must consume a parent-established block size, such as Surface.Media; retain fit and position for the intended crop."
+    },
+    {
+      "id": "image-parent-owner",
+      "level": "must",
+      "statement": "Name and preserve the parent sizing box when fill is used; Image propagates into available geometry but does not create that geometry."
+    },
     {
       "id": "image-css",
       "level": "must",
       "statement": "Load styles.css or core.css plus image.css."
+    },
+    {
+      "id": "image-rsc-parts",
+      "level": "must",
+      "statement": "Use direct named Image parts across a React Server Component boundary instead of wrapping the complete consumer in use client."
     }
   ],
   "commonMistakes": [
@@ -47,7 +63,7 @@
     }
   ],
   "validation": [
-    "Check loaded, loading, error, cached, responsive size, crop, layout shift, alt text, contrast of fallback content, and RTL where relevant.",
+    "Check loaded, loading, error, cached, responsive size, parent-fill geometry, crop, layout shift, alt text, contrast of fallback content, and RTL where relevant.",
     "Confirm CSS and any adapter report are complete."
   ],
   "related": [

package/dist/agents/image.md

@@ -15,13 +15,17 @@ Provide styled resilient media with Atom loading/fallback behavior, sizing recip
 ## Required composition
 
 - Compose Image.Content and optional Image.Fallback inside Image.Root; use Brick Stack or layout components around it rather than wrapper spans for alignment.
+- In a React Server Component, import ImageRoot, ImageContent, and ImageFallback directly; the compound Image namespace is intended for client module composition.
 
 ## Rules
 
 - **MUST:** Use Brick Image for ordinary interface media; document any native or framework image fallback and the missing capability.
 - **MUST:** Provide meaningful alt text, or alt="" for a decorative image.
 - **SHOULD:** Reserve dimensions or aspect ratio to prevent layout shift.
+- **MUST:** Use explicit fill when Image must consume a parent-established block size, such as Surface.Media; retain fit and position for the intended crop.
+- **MUST:** Name and preserve the parent sizing box when fill is used; Image propagates into available geometry but does not create that geometry.
 - **MUST:** Load styles.css or core.css plus image.css.
+- **MUST:** Use direct named Image parts across a React Server Component boundary instead of wrapping the complete consumer in use client.
 
 ## Common mistakes
 
@@ -29,7 +33,7 @@ Provide styled resilient media with Atom loading/fallback behavior, sizing recip
 
 ## Validation checklist
 
-- Check loaded, loading, error, cached, responsive size, crop, layout shift, alt text, contrast of fallback content, and RTL where relevant.
+- Check loaded, loading, error, cached, responsive size, parent-fill geometry, crop, layout shift, alt text, contrast of fallback content, and RTL where relevant.
 - Confirm CSS and any adapter report are complete.
 
 ## Related guidance

package/dist/agents/interface-composition.json

@@ -9,7 +9,8 @@
   "decisionOrder": [
     "Map the page into landmarks, bounded regions, layout relationships, content, navigation, actions, media, and responsive changes.",
     "Choose the Brick owner for each relationship and read every selected component guide before implementation.",
-    "Compose from the outside inward: AppBar or page landmark, Container, Grid or Stack, Surface or Card, then content and controls.",
+    "Compose from the outside inward: AppBar or page landmark, Section, Container, Grid or Stack, Surface or Card, then content and controls.",
+    "Decide how each child participates in its parent: content-sized, fixed, automatic, proportional, placed, stretched, or deliberately constrained.",
     "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.",
     "Audit responsive behavior, accessibility, CSS delivery, and native fallbacks before treating the composition as complete."
   ],
@@ -19,10 +20,35 @@
       "use": "Container",
       "note": "Do not reproduce max-width and inline padding on every section."
     },
+    {
+      "intent": "major page-region rhythm",
+      "use": "Section",
+      "note": "Keep paint in Surface, width and gutters in Container, and local child relationships in Stack or Grid."
+    },
     {
       "intent": "row or column relationship",
-      "use": "HStack or VStack",
-      "note": "Use Stack when direction is selected dynamically."
+      "use": "HStack, VStack, or responsive Stack",
+      "note": "Use fixed-axis conveniences when the axis stays fixed and Stack when the same content changes axis at a Brick breakpoint."
+    },
+    {
+      "intent": "child flex allocation",
+      "use": "Stack.Item",
+      "note": "Choose content-sized, fixed, automatic, or proportional growth before writing flex CSS."
+    },
+    {
+      "intent": "child grid participation",
+      "use": "Grid.Item",
+      "note": "Use spans, placement, or self-alignment; keep a real wrapper when it establishes the participation box and use asChild only when the child should be that box."
+    },
+    {
+      "intent": "local logical size constraint",
+      "use": "Frame",
+      "note": "Use only for inline/block size or min/max constraints; keep parent participation on the owning layout Item and overflow in ScrollArea."
+    },
+    {
+      "intent": "overlapping depth relationship",
+      "use": "ZStack",
+      "note": "Prefer Surface media anatomy for ordinary media, scrim, and foreground compositions."
     },
     {
       "intent": "track-based responsive layout",
@@ -34,11 +60,21 @@
       "use": "Surface or Card",
       "note": "Use Card for titled or actionable contained content and Surface for a general visual boundary."
     },
+    {
+      "intent": "local light or dark semantic-token boundary",
+      "use": "Appearance",
+      "note": "Pass exactly one existing host; it may contain any number of descendants, and Appearance adds no paint, layout, or wrapper."
+    },
     {
       "intent": "brand or content image",
       "use": "Image",
       "note": "Keep alt text and fallback behavior intentional."
     },
+    {
+      "intent": "one of several peer campaigns or authored content regions",
+      "use": "Carousel",
+      "note": "Keep invariant evidence outside; let each Slide own a complete Surface when its media and message belong together."
+    },
     {
       "intent": "site navigation",
       "use": "NavigationMenu or NavList",
@@ -47,12 +83,22 @@
     {
       "intent": "responsive desktop and mobile alternatives",
       "use": "Show and Hide",
-      "note": "Keep one CSS-controlled breakpoint contract and avoid hydration-dependent visibility; distinct navigation patterns should consume one application-owned destination model."
+      "note": "Use only when interface or content changes; use responsive Stack when only arrangement changes."
     },
     {
       "intent": "grouped application actions",
       "use": "Toolbar",
       "note": "Do not use AppBar.Toolbar as an ARIA toolbar."
+    },
+    {
+      "intent": "several related disclosure sections",
+      "use": "Accordion",
+      "note": "Preserve Header, Trigger, Content, and ContentInner ownership; use Collapsible for one disclosure."
+    },
+    {
+      "intent": "semantic item or sequence content",
+      "use": "List",
+      "note": "Use structured row parts only when needed and keep Trailing compact on narrow screens."
     }
   ],
   "rules": [
@@ -61,6 +107,46 @@
       "level": "must",
       "statement": "Assign page structure to Brick components before writing element-level CSS."
     },
+    {
+      "id": "interface-section-rhythm",
+      "level": "must",
+      "statement": "Use Section's named responsive rhythm for major page regions; use as=div when spacing is needed without thematic section semantics."
+    },
+    {
+      "id": "interface-painted-section",
+      "level": "must",
+      "statement": "When Surface paint must cover Section rhythm, compose Surface asChild around Section so one host keeps the responsibilities separate."
+    },
+    {
+      "id": "interface-blueprint-first",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "interface-responsive-single-content",
+      "level": "must",
+      "statement": "Keep one copy of content when only its layout changes; use responsive Stack values instead of duplicated Show/Hide trees."
+    },
+    {
+      "id": "interface-responsive-layout-grammar",
+      "level": "must",
+      "statement": "Use responsive Grid tracks, gaps, spans, and alignment or responsive ZStack logical placement when only those relationships change; do not duplicate content or change semantic order."
+    },
+    {
+      "id": "interface-parent-participation",
+      "level": "must",
+      "statement": "Separate component internal geometry from parent participation; configure the finished component for its anatomy and the owning layout or Item part for its relationship to siblings."
+    },
+    {
+      "id": "interface-frame-constraints",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "interface-definite-size-owner",
+      "level": "must",
+      "statement": "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."
+    },
     {
       "id": "interface-correct-owner",
       "level": "must",
@@ -86,6 +172,26 @@
       "level": "should",
       "statement": "Express reusable brand values through semantic Brick tokens and a theme rather than repeating literal application values."
     },
+    {
+      "id": "interface-local-appearance-scope",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "interface-portal-appearance",
+      "level": "must",
+      "statement": "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."
+    },
+    {
+      "id": "interface-depth-layout",
+      "level": "should",
+      "statement": "Use ZStack for reusable nine-position overlap; retain narrow application positioning only for artwork coordinates that ZStack intentionally does not own."
+    },
+    {
+      "id": "interface-ownership-classification",
+      "level": "must",
+      "statement": "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."
+    },
     {
       "id": "interface-document-foundation",
       "level": "must",
@@ -110,6 +216,16 @@
       "id": "interface-extract-evidence",
       "level": "should",
       "statement": "Classify repeated purposeful sections as Block candidates and repeated page arrangements as Blueprint candidates only after real reuse evidence."
+    },
+    {
+      "id": "interface-source-organization",
+      "level": "should",
+      "statement": "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."
+    },
+    {
+      "id": "interface-comment-intent",
+      "level": "must",
+      "statement": "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": {
@@ -157,6 +273,17 @@
       ]
     }
   },
+  "planningRecord": {
+    "purpose": "Record the layout decision before generated implementation so Engine and TemplateFlow preserve ownership.",
+    "fields": [
+      "relationship",
+      "owner",
+      "parentParticipation",
+      "responsiveChange",
+      "constraintSource",
+      "fallbackReport"
+    ]
+  },
   "nativeFallback": {
     "check": "Review the interface map against the manifest and selected component guides, including layout, text, image, visibility, and navigation owners.",
     "use": "Keep native landmarks and product-specific semantic structures where no Brick component adds a useful contract; add only narrow composition classes.",
@@ -165,20 +292,30 @@
   "validation": [
     "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": [
     "layer-selection",
+    "appearance",
     "app-bar",
+    "section",
     "container",
     "stack",
+    "z-stack",
     "grid",
+    "frame",
     "surface",
     "card",
     "navigation-menu",
     "show",
-    "hide"
+    "hide",
+    "accordion",
+    "list"
   ]
 }

package/dist/agents/interface-composition.md

@@ -8,34 +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; distinct navigation patterns should consume one application-owned destination model.
+- **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
 
@@ -75,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`