@flowstack-ui/brick 0.1.4 → 0.1.6

package/dist/agents/section.json

@@ -0,0 +1,65 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "section",
+  "name": "Section",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Own themeable responsive block rhythm for major semantic page and application regions.",
+  "useWhen": [
+    "A thematic page or application region needs consistent large vertical rhythm beyond local component spacing."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The need is child arrangement, inline measure, visual paint, or a complete content pattern.",
+      "useInstead": "Stack/Grid, Container, Surface, or a qualified Block"
+    }
+  ],
+  "composition": [
+    "Place Container inside Section for measured content; compose Surface with asChild around Section when paint must cover the Section rhythm; use Stack or Grid inside for child relationships."
+  ],
+  "rules": [
+    {
+      "id": "section-rhythm-owner",
+      "level": "must",
+      "statement": "Use Section's named responsive rhythm instead of repeating large page-section padding CSS."
+    },
+    {
+      "id": "section-semantic-host",
+      "level": "must",
+      "statement": "Use the default section host only for a thematic grouping, normally with a heading; select as=div when spacing alone has no sectioning meaning."
+    },
+    {
+      "id": "section-boundaries",
+      "level": "must",
+      "statement": "Keep paint in Surface, inline measure in Container, and child arrangement in Stack or Grid rather than adding those responsibilities to Section."
+    },
+    {
+      "id": "section-customization",
+      "level": "must",
+      "statement": "Choose a named recipe first; customize documented Section variables only when the theme or one deliberate region needs a value the scale cannot express."
+    },
+    {
+      "id": "section-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus section.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Stack gap for page rhythm, Surface inset as section spacing, or Section as a generic div around every group.",
+      "correction": "Assign each responsibility to Section, Surface, Container, Stack, or Grid and use as=div only when Section rhythm is useful without section semantics."
+    }
+  ],
+  "validation": [
+    "Check named and responsive rhythm at constrained and wide widths, zoom, RTL, and vertical writing modes.",
+    "Confirm the section has appropriate document meaning and that Surface asChild composition produces one host when full-width paint is needed."
+  ],
+  "related": [
+    "container",
+    "surface",
+    "stack",
+    "grid",
+    "interface-composition"
+  ]
+}

package/dist/agents/section.md

@@ -0,0 +1,42 @@
+# Section agent guide
+
+## Purpose
+
+Own themeable responsive block rhythm for major semantic page and application regions.
+
+## Use when
+
+- A thematic page or application region needs consistent large vertical rhythm beyond local component spacing.
+
+## Choose something else when
+
+- The need is child arrangement, inline measure, visual paint, or a complete content pattern. Use Stack/Grid, Container, Surface, or a qualified Block.
+
+## Required composition
+
+- Place Container inside Section for measured content; compose Surface with asChild around Section when paint must cover the Section rhythm; use Stack or Grid inside for child relationships.
+
+## Rules
+
+- **MUST:** Use Section's named responsive rhythm instead of repeating large page-section padding CSS.
+- **MUST:** Use the default section host only for a thematic grouping, normally with a heading; select as=div when spacing alone has no sectioning meaning.
+- **MUST:** Keep paint in Surface, inline measure in Container, and child arrangement in Stack or Grid rather than adding those responsibilities to Section.
+- **MUST:** Choose a named recipe first; customize documented Section variables only when the theme or one deliberate region needs a value the scale cannot express.
+- **MUST:** Load styles.css or core.css plus section.css.
+
+## Common mistakes
+
+- **Avoid:** Using Stack gap for page rhythm, Surface inset as section spacing, or Section as a generic div around every group. **Instead:** Assign each responsibility to Section, Surface, Container, Stack, or Grid and use as=div only when Section rhythm is useful without section semantics.
+
+## Validation checklist
+
+- Check named and responsive rhythm at constrained and wide widths, zoom, RTL, and vertical writing modes.
+- Confirm the section has appropriate document meaning and that Surface asChild composition produces one host when full-width paint is needed.
+
+## Related guidance
+
+- `container`
+- `surface`
+- `stack`
+- `grid`
+- `interface-composition`

package/dist/agents/stack.json

@@ -5,7 +5,7 @@
   "package": "@flowstack-ui/brick",
   "layer": "brick",
   "kind": "component",
-  "purpose": "Arrange children in one tokenized row or column with logical spacing, alignment, wrapping, and responsive-friendly public props.",
+  "purpose": "Arrange children on one primary axis with responsive direction, tokenized spacing, alignment, wrapping, and explicit child sizing.",
   "useWhen": [
     "Content needs one-dimensional vertical or horizontal layout."
   ],
@@ -13,10 +13,17 @@
     {
       "condition": "Both rows and columns need explicit track control.",
       "useInstead": "Grid"
+    },
+    {
+      "condition": "Content overlaps in depth.",
+      "useInstead": "ZStack or Surface media anatomy"
     }
   ],
   "composition": [
-    "Choose VStack for vertical flow or HStack for horizontal flow; set gap and alignment from the content relationship."
+    "Choose VStack when the axis is always vertical, HStack when it is always horizontal, and Stack when the same content changes axis at a breakpoint.",
+    "Use Stack.Item when one direct child must remain content-sized, fixed, or consume a proportional share.",
+    "When the parent changes axis, review each Item flex recipe too; a proportional desktop column usually becomes content-sized in a mobile column.",
+    "Keep the Item wrapper when equal outer tracks contain children with different padding or borders; use asChild only when the child's own box should participate in flex allocation."
   ],
   "rules": [
     {
@@ -24,6 +31,16 @@
       "level": "must",
       "statement": "Use Stack for one primary layout axis and allow wrapping only when the resulting order remains clear."
     },
+    {
+      "id": "stack-responsive-arrangement",
+      "level": "must",
+      "statement": "Use responsive Stack values for arrangement changes; use Show/Hide only when the actual interface changes."
+    },
+    {
+      "id": "stack-source-order",
+      "level": "must",
+      "statement": "Preserve reading and focus order; do not simulate reverse direction or visual ordering."
+    },
     {
       "id": "stack-css",
       "level": "must",
@@ -32,16 +49,23 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Adding repeated custom flex utilities for ordinary rows and columns.",
-      "correction": "Use Stack so spacing and logical-direction behavior stay on the Brick contract."
+      "mistake": "Duplicating the same content through Show/Hide only to switch row and column.",
+      "correction": "Use responsive Stack direction."
+    },
+    {
+      "mistake": "Writing grow/shrink CSS for ordinary columns.",
+      "correction": "Use Stack.Item flex recipes."
     }
   ],
   "validation": [
     "Check source and visual order at narrow widths and zoom.",
-    "Check gap, wrapping, alignment, and RTL behavior."
+    "Check every authored breakpoint, logical edge spacing, wrapping, alignment, and RTL behavior."
   ],
   "related": [
     "grid",
+    "z-stack",
+    "show",
+    "hide",
     "surface",
     "card"
   ]

package/dist/agents/stack.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Arrange children in one tokenized row or column with logical spacing, alignment, wrapping, and responsive-friendly public props.
+Arrange children on one primary axis with responsive direction, tokenized spacing, alignment, wrapping, and explicit child sizing.
 
 ## Use when
 
@@ -11,27 +11,37 @@ Arrange children in one tokenized row or column with logical spacing, alignment,
 ## Choose something else when
 
 - Both rows and columns need explicit track control. Use Grid.
+- Content overlaps in depth. Use ZStack or Surface media anatomy.
 
 ## Required composition
 
-- Choose VStack for vertical flow or HStack for horizontal flow; set gap and alignment from the content relationship.
+- Choose VStack when the axis is always vertical, HStack when it is always horizontal, and Stack when the same content changes axis at a breakpoint.
+- Use Stack.Item when one direct child must remain content-sized, fixed, or consume a proportional share.
+- When the parent changes axis, review each Item flex recipe too; a proportional desktop column usually becomes content-sized in a mobile column.
+- Keep the Item wrapper when equal outer tracks contain children with different padding or borders; use asChild only when the child's own box should participate in flex allocation.
 
 ## Rules
 
 - **MUST:** Use Stack for one primary layout axis and allow wrapping only when the resulting order remains clear.
+- **MUST:** Use responsive Stack values for arrangement changes; use Show/Hide only when the actual interface changes.
+- **MUST:** Preserve reading and focus order; do not simulate reverse direction or visual ordering.
 - **MUST:** Load styles.css or core.css plus stack.css.
 
 ## Common mistakes
 
-- **Avoid:** Adding repeated custom flex utilities for ordinary rows and columns. **Instead:** Use Stack so spacing and logical-direction behavior stay on the Brick contract.
+- **Avoid:** Duplicating the same content through Show/Hide only to switch row and column. **Instead:** Use responsive Stack direction.
+- **Avoid:** Writing grow/shrink CSS for ordinary columns. **Instead:** Use Stack.Item flex recipes.
 
 ## Validation checklist
 
 - Check source and visual order at narrow widths and zoom.
-- Check gap, wrapping, alignment, and RTL behavior.
+- Check every authored breakpoint, logical edge spacing, wrapping, alignment, and RTL behavior.
 
 ## Related guidance
 
 - `grid`
+- `z-stack`
+- `show`
+- `hide`
 - `surface`
 - `card`

package/dist/agents/surface.json

@@ -5,9 +5,10 @@
   "package": "@flowstack-ui/brick",
   "layer": "brick",
   "kind": "component",
-  "purpose": "Apply semantic background layers, boundaries, elevation, radius, and inset without implying a specific content object.",
+  "purpose": "Apply semantic background layers, boundaries, elevation, radius, inset, and optional decorative media layering without implying a specific content object.",
   "useWhen": [
-    "A region needs a semantic visual plane but Card, Dialog, or another purposeful component would add the wrong anatomy."
+    "A region needs a semantic visual plane but Card, Dialog, or another purposeful component would add the wrong anatomy.",
+    "Decorative image, video, canvas, or authored artwork needs to sit behind foreground content with an optional contrast scrim."
   ],
   "avoidWhen": [
     {
@@ -16,7 +17,7 @@
     }
   ],
   "composition": [
-    "Choose Surface level and boundary by hierarchy, then compose public layout and content components inside."
+    "Choose Surface level and boundary by hierarchy, then compose public layout and content components inside. Use asChild around Section when paint must cover the Section rhythm without another host. For background media, author Media, optional Scrim, and Content in that order."
   ],
   "rules": [
     {
@@ -24,24 +25,61 @@
       "level": "should",
       "statement": "Choose surface level by information hierarchy, not decoration alone."
     },
+    {
+      "id": "surface-as-child",
+      "level": "must",
+      "statement": "Use asChild only with one existing non-Fragment host that already owns the required semantics or layout; preserve that child's meaning and keep Surface responsible only for paint."
+    },
     {
       "id": "surface-css",
       "level": "must",
       "statement": "Load styles.css or core.css plus surface.css."
+    },
+    {
+      "id": "surface-media-decoration",
+      "level": "must",
+      "statement": "Treat Surface.Media as decorative and noninteractive; keep meaningful media and controls in Content or ordinary document flow."
+    },
+    {
+      "id": "surface-media-image-fill",
+      "level": "must",
+      "statement": "Give Brick Image explicit fill inside Surface.Media so its actual Content and Fallback consume the complete media layer."
+    },
+    {
+      "id": "surface-media-content",
+      "level": "must",
+      "statement": "Put every foreground child inside Surface.Content when Media or Scrim is used."
+    },
+    {
+      "id": "surface-scrim-strength",
+      "level": "should",
+      "statement": "Choose Scrim strength through the public prop and let the theme provide only the semantic scrim color unless one deliberate instance requires an advanced recipe override."
+    },
+    {
+      "id": "surface-media-contrast",
+      "level": "must",
+      "statement": "Verify foreground contrast against every media state; Scrim does not prove contrast by itself."
     }
   ],
   "commonMistakes": [
     {
       "mistake": "Using arbitrary background colors to recreate a surface.",
       "correction": "Use Surface and theme its semantic tokens."
+    },
+    {
+      "mistake": "Adding absolute-positioning and z-index CSS for ordinary background media.",
+      "correction": "Use Surface.Media, Surface.Scrim, and Surface.Content."
     }
   ],
   "validation": [
     "Check foreground contrast against the selected surface in every appearance.",
-    "Confirm nested surfaces communicate hierarchy without excessive borders or elevation."
+    "Confirm nested surfaces communicate hierarchy without excessive borders or elevation.",
+    "Confirm Media and Scrim fill the root, remain hidden from assistive technology and pointer input, and Content stays above both."
   ],
   "related": [
     "card",
+    "section",
+    "container",
     "stack",
     "grid"
   ]

package/dist/agents/surface.md

@@ -2,11 +2,12 @@
 
 ## Purpose
 
-Apply semantic background layers, boundaries, elevation, radius, and inset without implying a specific content object.
+Apply semantic background layers, boundaries, elevation, radius, inset, and optional decorative media layering without implying a specific content object.
 
 ## Use when
 
 - A region needs a semantic visual plane but Card, Dialog, or another purposeful component would add the wrong anatomy.
+- Decorative image, video, canvas, or authored artwork needs to sit behind foreground content with an optional contrast scrim.
 
 ## Choose something else when
 
@@ -14,24 +15,34 @@ Apply semantic background layers, boundaries, elevation, radius, and inset witho
 
 ## Required composition
 
-- Choose Surface level and boundary by hierarchy, then compose public layout and content components inside.
+- Choose Surface level and boundary by hierarchy, then compose public layout and content components inside. Use asChild around Section when paint must cover the Section rhythm without another host. For background media, author Media, optional Scrim, and Content in that order.
 
 ## Rules
 
 - **SHOULD:** Choose surface level by information hierarchy, not decoration alone.
+- **MUST:** Use asChild only with one existing non-Fragment host that already owns the required semantics or layout; preserve that child's meaning and keep Surface responsible only for paint.
 - **MUST:** Load styles.css or core.css plus surface.css.
+- **MUST:** Treat Surface.Media as decorative and noninteractive; keep meaningful media and controls in Content or ordinary document flow.
+- **MUST:** Give Brick Image explicit fill inside Surface.Media so its actual Content and Fallback consume the complete media layer.
+- **MUST:** Put every foreground child inside Surface.Content when Media or Scrim is used.
+- **SHOULD:** Choose Scrim strength through the public prop and let the theme provide only the semantic scrim color unless one deliberate instance requires an advanced recipe override.
+- **MUST:** Verify foreground contrast against every media state; Scrim does not prove contrast by itself.
 
 ## Common mistakes
 
 - **Avoid:** Using arbitrary background colors to recreate a surface. **Instead:** Use Surface and theme its semantic tokens.
+- **Avoid:** Adding absolute-positioning and z-index CSS for ordinary background media. **Instead:** Use Surface.Media, Surface.Scrim, and Surface.Content.
 
 ## Validation checklist
 
 - Check foreground contrast against the selected surface in every appearance.
 - Confirm nested surfaces communicate hierarchy without excessive borders or elevation.
+- Confirm Media and Scrim fill the root, remain hidden from assistive technology and pointer input, and Content stays above both.
 
 ## Related guidance
 
 - `card`
+- `section`
+- `container`
 - `stack`
 - `grid`

package/dist/agents/tabs.json

@@ -16,7 +16,12 @@
     }
   ],
   "composition": [
-    "Compose Trigger and optional Indicator inside List with matching Content values inside Root; lay out panel content with Brick components."
+    "Compose Trigger and optional Indicator inside List with matching Content values inside Root; lay out panel content with Brick components.",
+    "Keep the default panel inset for ordinary copy; use Content inset=none for edge-to-edge media or nested surfaces rather than overriding component CSS.",
+    "When vertical tab semantics stay correct but mobile needs full-width content, use responsive Root layout stacked to side; do not change semantic orientation with CSS.",
+    "When the same vertical selector needs a compact mobile grid, use responsive List columns (for example, initial 2 and lg 1) rather than application selectors; keyboard orientation remains vertical.",
+    "When a solid or soft List is nested inside a clipping parent that owns the outer corners, use List radius=none rather than overriding Tabs selectors; add triggerRadius=default only when individual Trigger surfaces should remain rounded.",
+    "Keep the shipped solid and soft List inset at or above the complete focus-ring reach; do not reduce it inside a clipping Card or Surface."
   ],
   "rules": [
     {
@@ -29,6 +34,16 @@
       "level": "must",
       "statement": "Define a deliberate narrow-width overflow or wrapping policy without clipping triggers or indicator focus."
     },
+    {
+      "id": "tabs-columns-semantics",
+      "level": "must",
+      "statement": "Treat List columns as visual placement only; keep DOM order and the semantic orientation that matches the intended arrow keys."
+    },
+    {
+      "id": "tabs-radius-visual-only",
+      "level": "must",
+      "statement": "Treat List radius and Trigger radius as independent visual geometry only; neither may alter inset, selection, focus, orientation, columns, or keyboard behavior."
+    },
     {
       "id": "tabs-css",
       "level": "must",
@@ -42,7 +57,7 @@
     }
   ],
   "validation": [
-    "Check automatic/manual activation, arrows, Home/End, Enter/Space, disabled, controlled, keep-mounted, overflow, focus rings, themes, zoom, and RTL.",
+    "Check automatic/manual activation, arrows, Home/End, Enter/Space, disabled, controlled, keep-mounted, overflow, complete focus rings at every List edge and inside clipping parents, themes, zoom, and RTL.",
     "Confirm CSS is loaded."
   ],
   "related": [

package/dist/agents/tabs.md

@@ -15,11 +15,18 @@ Style related in-page panel switching while Atom owns tab semantics, selection,
 ## Required composition
 
 - Compose Trigger and optional Indicator inside List with matching Content values inside Root; lay out panel content with Brick components.
+- Keep the default panel inset for ordinary copy; use Content inset=none for edge-to-edge media or nested surfaces rather than overriding component CSS.
+- When vertical tab semantics stay correct but mobile needs full-width content, use responsive Root layout stacked to side; do not change semantic orientation with CSS.
+- When the same vertical selector needs a compact mobile grid, use responsive List columns (for example, initial 2 and lg 1) rather than application selectors; keyboard orientation remains vertical.
+- When a solid or soft List is nested inside a clipping parent that owns the outer corners, use List radius=none rather than overriding Tabs selectors; add triggerRadius=default only when individual Trigger surfaces should remain rounded.
+- Keep the shipped solid and soft List inset at or above the complete focus-ring reach; do not reduce it inside a clipping Card or Surface.
 
 ## Rules
 
 - **MUST:** Use Tabs only for related in-page panels, not to imitate a site navigation underline.
 - **MUST:** Define a deliberate narrow-width overflow or wrapping policy without clipping triggers or indicator focus.
+- **MUST:** Treat List columns as visual placement only; keep DOM order and the semantic orientation that matches the intended arrow keys.
+- **MUST:** Treat List radius and Trigger radius as independent visual geometry only; neither may alter inset, selection, focus, orientation, columns, or keyboard behavior.
 - **MUST:** Load styles.css or core.css plus tabs.css.
 
 ## Common mistakes
@@ -28,7 +35,7 @@ Style related in-page panel switching while Atom owns tab semantics, selection,
 
 ## Validation checklist
 
-- Check automatic/manual activation, arrows, Home/End, Enter/Space, disabled, controlled, keep-mounted, overflow, focus rings, themes, zoom, and RTL.
+- Check automatic/manual activation, arrows, Home/End, Enter/Space, disabled, controlled, keep-mounted, overflow, complete focus rings at every List edge and inside clipping parents, themes, zoom, and RTL.
 - Confirm CSS is loaded.
 
 ## Related guidance

package/dist/agents/text.json

@@ -7,7 +7,7 @@
   "kind": "component",
   "purpose": "Apply Brick typography roles, sizes, tones, weight, alignment, and wrapping while preserving the chosen semantic text element.",
   "useWhen": [
-    "Interface copy needs Brick typography, including headings, paragraphs, labels, captions, metadata, or inline text."
+    "Interface copy needs Brick typography, including headings, paragraphs, short editorial eyebrows, captions, metadata, or inline text."
   ],
   "avoidWhen": [
     {
@@ -34,6 +34,21 @@
       "level": "must",
       "statement": "Preserve readable body sizing, line height, measure, contrast, and user font scaling."
     },
+    {
+      "id": "text-eyebrow",
+      "level": "must",
+      "statement": "Reserve variant=eyebrow for short labels that introduce a nearby heading; do not select it merely to make unrelated copy smaller. Use body text for explanatory sentences and Badge for passive status or category content."
+    },
+    {
+      "id": "text-inherit-parent-foreground",
+      "level": "must",
+      "statement": "Use tone=inherit when Text is intentionally composed inside a parent such as Badge that owns the foreground and contrast relationship."
+    },
+    {
+      "id": "text-inline-peers",
+      "level": "should",
+      "statement": "Give separately meaningful inline peer labels compatible typography metrics and arrange them with HStack gap rather than literal spaces or manual positional offsets."
+    },
     {
       "id": "text-css",
       "level": "must",
@@ -42,13 +57,13 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Using five spans to build brand text, selecting all-caps eyebrow styling for paragraph descriptions, or setting headings from appearance.",
-      "correction": "Use Text with semantic elements and reserve display treatments for their intended short roles."
+      "mistake": "Using five spans to build brand text, selecting all-caps eyebrow styling for paragraph descriptions, allowing nested Text to override a parent's foreground, or aligning peer labels with literal whitespace.",
+      "correction": "Use Text with semantic elements, reserve display treatments for their intended roles, inherit the owning foreground, and use HStack gap for layout between separate nodes."
     }
   ],
   "validation": [
     "Check heading order, semantics, line length, wrapping, truncation, user font scaling, zoom, contrast, themes, and RTL.",
-    "Confirm parent component text parts are not bypassed and CSS is loaded."
+    "Confirm parent component text parts and foreground ownership are not bypassed, peer labels align without positional CSS, and CSS is loaded."
   ],
   "related": [
     "stack",

package/dist/agents/text.md

@@ -6,7 +6,7 @@ Apply Brick typography roles, sizes, tones, weight, alignment, and wrapping whil
 
 ## Use when
 
-- Interface copy needs Brick typography, including headings, paragraphs, labels, captions, metadata, or inline text.
+- Interface copy needs Brick typography, including headings, paragraphs, short editorial eyebrows, captions, metadata, or inline text.
 
 ## Choose something else when
 
@@ -21,16 +21,19 @@ Apply Brick typography roles, sizes, tones, weight, alignment, and wrapping whil
 - **MUST:** Do not choose heading or paragraph semantics solely from the desired font size.
 - **MUST:** Use Text for standalone styled interface copy instead of native spans plus duplicate typography CSS.
 - **MUST:** Preserve readable body sizing, line height, measure, contrast, and user font scaling.
+- **MUST:** Reserve variant=eyebrow for short labels that introduce a nearby heading; do not select it merely to make unrelated copy smaller. Use body text for explanatory sentences and Badge for passive status or category content.
+- **MUST:** Use tone=inherit when Text is intentionally composed inside a parent such as Badge that owns the foreground and contrast relationship.
+- **SHOULD:** Give separately meaningful inline peer labels compatible typography metrics and arrange them with HStack gap rather than literal spaces or manual positional offsets.
 - **MUST:** Load styles.css or core.css plus text.css.
 
 ## Common mistakes
 
-- **Avoid:** Using five spans to build brand text, selecting all-caps eyebrow styling for paragraph descriptions, or setting headings from appearance. **Instead:** Use Text with semantic elements and reserve display treatments for their intended short roles.
+- **Avoid:** Using five spans to build brand text, selecting all-caps eyebrow styling for paragraph descriptions, allowing nested Text to override a parent's foreground, or aligning peer labels with literal whitespace. **Instead:** Use Text with semantic elements, reserve display treatments for their intended roles, inherit the owning foreground, and use HStack gap for layout between separate nodes.
 
 ## Validation checklist
 
 - Check heading order, semantics, line length, wrapping, truncation, user font scaling, zoom, contrast, themes, and RTL.
-- Confirm parent component text parts are not bypassed and CSS is loaded.
+- Confirm parent component text parts and foreground ownership are not bypassed, peer labels align without positional CSS, and CSS is loaded.
 
 ## Related guidance
 

package/dist/agents/z-stack.json

@@ -0,0 +1,66 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "z-stack",
+  "name": "ZStack",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Overlap authored children in one depth-aware layout while preserving source, reading, and focus order.",
+  "useWhen": [
+    "Two or more visual layers intentionally share the same region."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Content follows one row or column.",
+      "useInstead": "Stack"
+    },
+    {
+      "condition": "Content is an ordinary image-backed card or hero.",
+      "useInstead": "Surface.Media, Surface.Scrim, and Surface.Content"
+    }
+  ],
+  "composition": [
+    "Place natural-size layers directly in ZStack.Root and use ZStack.Item only when one layer needs its own nine-position alignment."
+  ],
+  "rules": [
+    {
+      "id": "z-stack-source-order",
+      "level": "must",
+      "statement": "Keep DOM order meaningful because later children paint above earlier children."
+    },
+    {
+      "id": "z-stack-input",
+      "level": "must",
+      "statement": "Keep decorative layers from intercepting input intended for interactive content."
+    },
+    {
+      "id": "z-stack-responsive-placement",
+      "level": "must",
+      "statement": "Use responsive logical alignment only to move the same authored layer; never change source order, depth order, or focus order at a breakpoint."
+    },
+    {
+      "id": "z-stack-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus z-stack.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Replacing ordinary linear layout with overlap.",
+      "correction": "Use Stack or Grid unless layers intentionally share space."
+    },
+    {
+      "mistake": "Rebuilding Surface media anatomy.",
+      "correction": "Prefer Surface for standard media-backed content."
+    }
+  ],
+  "validation": [
+    "Check natural sizing, responsive logical placement, focus order, zoom, RTL, and pointer access."
+  ],
+  "related": [
+    "stack",
+    "grid",
+    "surface",
+    "image"
+  ]
+}

package/dist/agents/z-stack.md

@@ -0,0 +1,41 @@
+# ZStack agent guide
+
+## Purpose
+
+Overlap authored children in one depth-aware layout while preserving source, reading, and focus order.
+
+## Use when
+
+- Two or more visual layers intentionally share the same region.
+
+## Choose something else when
+
+- Content follows one row or column. Use Stack.
+- Content is an ordinary image-backed card or hero. Use Surface.Media, Surface.Scrim, and Surface.Content.
+
+## Required composition
+
+- Place natural-size layers directly in ZStack.Root and use ZStack.Item only when one layer needs its own nine-position alignment.
+
+## Rules
+
+- **MUST:** Keep DOM order meaningful because later children paint above earlier children.
+- **MUST:** Keep decorative layers from intercepting input intended for interactive content.
+- **MUST:** Use responsive logical alignment only to move the same authored layer; never change source order, depth order, or focus order at a breakpoint.
+- **MUST:** Load styles.css or core.css plus z-stack.css.
+
+## Common mistakes
+
+- **Avoid:** Replacing ordinary linear layout with overlap. **Instead:** Use Stack or Grid unless layers intentionally share space.
+- **Avoid:** Rebuilding Surface media anatomy. **Instead:** Prefer Surface for standard media-backed content.
+
+## Validation checklist
+
+- Check natural sizing, responsive logical placement, focus order, zoom, RTL, and pointer access.
+
+## Related guidance
+
+- `stack`
+- `grid`
+- `surface`
+- `image`

package/dist/appearance.d.ts

@@ -0,0 +1,2 @@
+export { Appearance, type AppearanceProps, type AppearanceValue, } from "./components/appearance/index.js";
+//# sourceMappingURL=appearance.d.ts.map

package/dist/appearance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance.d.ts","sourceRoot":"","sources":["../src/appearance.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,kCAAkC,CAAC"}

package/dist/appearance.js

@@ -0,0 +1,2 @@
+export { Appearance, } from "./components/appearance/index.js";
+//# sourceMappingURL=appearance.js.map

package/dist/appearance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance.js","sourceRoot":"","sources":["../src/appearance.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,GAGX,MAAM,kCAAkC,CAAC"}

package/dist/carousel.d.ts

@@ -0,0 +1,3 @@
+export * from "./components/carousel/index.js";
+export { CarouselRoot as Root, CarouselViewport as Viewport, CarouselTrack as Track, CarouselSlide as Slide, CarouselNavigation as Navigation, CarouselPrevious as Previous, CarouselNext as Next, CarouselControls as Controls, CarouselRotationControl as RotationControl, CarouselPicker as Picker, CarouselPickerItem as PickerItem, } from "./components/carousel/Carousel.js";
+//# sourceMappingURL=carousel.d.ts.map

package/dist/carousel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["../src/carousel.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC;AAE/C,OAAO,EACL,YAAY,IAAI,IAAI,EACpB,gBAAgB,IAAI,QAAQ,EAC5B,aAAa,IAAI,KAAK,EACtB,aAAa,IAAI,KAAK,EACtB,kBAAkB,IAAI,UAAU,EAChC,gBAAgB,IAAI,QAAQ,EAC5B,YAAY,IAAI,IAAI,EACpB,gBAAgB,IAAI,QAAQ,EAC5B,uBAAuB,IAAI,eAAe,EAC1C,cAAc,IAAI,MAAM,EACxB,kBAAkB,IAAI,UAAU,GACjC,MAAM,mCAAmC,CAAC"}