@flowstack-ui/brick 0.1.9 → 0.1.12

package/dist/agents/reorderable-list.json

@@ -0,0 +1,74 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "reorderable-list",
+  "name": "Reorderable List",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a finished list for deliberate manual ordering while Atom owns drag, touch, keyboard, focus, announcements, cancellation, and reorder state behavior.",
+  "useWhen": [
+    "A person needs to arrange a small linear collection into a meaningful saved order."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The application is sorting data automatically or changing a table sort key.",
+      "useInstead": "DataGrid or an application-owned sort control"
+    },
+    {
+      "condition": "Items move between columns, tree parents, freeform coordinates, or external applications.",
+      "useInstead": "A dedicated Kanban, tree, spatial, or file-transfer composition over Atom DragDrop"
+    },
+    {
+      "condition": "The content is static and has no manual ordering job.",
+      "useInstead": "List"
+    }
+  ],
+  "composition": [
+    "Compose Root > Item > Handle + Content + optional Actions containing direct Move controls + DropIndicator.",
+    "Keep application data keyed by each Item value and update that data from Root onItemsChange; persistence, Undo, conflicts, and validation remain application-owned.",
+    "Let Brick move direct Actions below Content when a vertical list's own container is narrow; do not add viewport logic or duplicate the item tree for this relationship."
+  ],
+  "rules": [
+    {
+      "id": "reorderable-list-stable-identity",
+      "level": "must",
+      "statement": "Use stable unique values for Root items and matching Item values; never use visual indexes as identity."
+    },
+    {
+      "id": "reorderable-list-labels",
+      "level": "must",
+      "statement": "Provide getItemLabel plus localized aria-label values for every Handle and direct Move control."
+    },
+    {
+      "id": "reorderable-list-alternative",
+      "level": "must",
+      "statement": "Provide direct movement controls when drag precision, switch access, voice access, or discoverability requires a visible non-drag path."
+    },
+    {
+      "id": "reorderable-list-ownership",
+      "level": "must",
+      "statement": "Keep persistence, Undo, optimistic updates, server conflicts, validation, and automatic sorting outside ReorderableList."
+    },
+    {
+      "id": "reorderable-list-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus reorderable-list.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using ReorderableList as a sortable table, persisting inside the component, omitting accessible movement names, or making drag the only usable path.",
+      "correction": "Choose the component by user job, keep workflow state in the application, label every control, and expose direct movement where needed."
+    }
+  ],
+  "validation": [
+    "Check direct movement, keyboard lift/move/drop/cancel, mouse and touch movement, focus preservation, disabled and read-only states, and announcement copy.",
+    "Check that narrow vertical lists preserve a useful content measure by moving direct Actions below Content, then check horizontal overflow, RTL, zoom, reduced motion, forced colors, light and dark appearance, focus-ring containment, and insertion feedback."
+  ],
+  "related": [
+    "list",
+    "data-grid",
+    "tree",
+    "swipeable-item"
+  ]
+}

package/dist/agents/reorderable-list.md

@@ -0,0 +1,45 @@
+# Reorderable List agent guide
+
+## Purpose
+
+Provide a finished list for deliberate manual ordering while Atom owns drag, touch, keyboard, focus, announcements, cancellation, and reorder state behavior.
+
+## Use when
+
+- A person needs to arrange a small linear collection into a meaningful saved order.
+
+## Choose something else when
+
+- The application is sorting data automatically or changing a table sort key. Use DataGrid or an application-owned sort control.
+- Items move between columns, tree parents, freeform coordinates, or external applications. Use A dedicated Kanban, tree, spatial, or file-transfer composition over Atom DragDrop.
+- The content is static and has no manual ordering job. Use List.
+
+## Required composition
+
+- Compose Root > Item > Handle + Content + optional Actions containing direct Move controls + DropIndicator.
+- Keep application data keyed by each Item value and update that data from Root onItemsChange; persistence, Undo, conflicts, and validation remain application-owned.
+- Let Brick move direct Actions below Content when a vertical list's own container is narrow; do not add viewport logic or duplicate the item tree for this relationship.
+
+## Rules
+
+- **MUST:** Use stable unique values for Root items and matching Item values; never use visual indexes as identity.
+- **MUST:** Provide getItemLabel plus localized aria-label values for every Handle and direct Move control.
+- **MUST:** Provide direct movement controls when drag precision, switch access, voice access, or discoverability requires a visible non-drag path.
+- **MUST:** Keep persistence, Undo, optimistic updates, server conflicts, validation, and automatic sorting outside ReorderableList.
+- **MUST:** Load styles.css or core.css plus reorderable-list.css.
+
+## Common mistakes
+
+- **Avoid:** Using ReorderableList as a sortable table, persisting inside the component, omitting accessible movement names, or making drag the only usable path. **Instead:** Choose the component by user job, keep workflow state in the application, label every control, and expose direct movement where needed.
+
+## Validation checklist
+
+- Check direct movement, keyboard lift/move/drop/cancel, mouse and touch movement, focus preservation, disabled and read-only states, and announcement copy.
+- Check that narrow vertical lists preserve a useful content measure by moving direct Actions below Content, then check horizontal overflow, RTL, zoom, reduced motion, forced colors, light and dark appearance, focus-ring containment, and insertion feedback.
+
+## Related guidance
+
+- `list`
+- `data-grid`
+- `tree`
+- `swipeable-item`

package/dist/agents/segment-group.json

@@ -0,0 +1,62 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "segment-group",
+  "name": "SegmentGroup",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present one mutually exclusive immediate mode in a compact segmented surface with radio semantics and a moving visual indicator.",
+  "useWhen": [
+    "A small visible set such as list/grid, density, or appearance must keep exactly one immediate mode selected."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Commands may be independently pressed, the choices select paired panels, or an ordinary form choice is needed.",
+      "useInstead": "ToggleGroup, Tabs, or RadioGroup according to the interaction"
+    }
+  ],
+  "composition": [
+    "Compose Root with one Indicator and directly owned Items; give Root a complete accessible name and every icon-only Item its own complete name.",
+    "Choose one shared size on Root so adjacent Button, Select, and other named-size controls align through Brick's control contract."
+  ],
+  "rules": [
+    {
+      "id": "segment-group-single-choice",
+      "level": "must",
+      "statement": "Use SegmentGroup only for one mutually exclusive value and preserve Atom Radio Group semantics and keyboard behavior."
+    },
+    {
+      "id": "segment-group-indicator",
+      "level": "must",
+      "statement": "Render one decorative Indicator for the canonical moving-selection recipe; selection and naming must remain on Items."
+    },
+    {
+      "id": "segment-group-not-tabs",
+      "level": "must",
+      "statement": "Do not use SegmentGroup for paired content panels or route navigation; use Tabs or navigation destinations."
+    },
+    {
+      "id": "segment-group-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus segment-group.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using ToggleGroup single mode for a required one-of-many mode or using SegmentGroup as visual tabs.",
+      "correction": "Choose SegmentGroup for one compact radio-semantic mode and Tabs only when panels are paired."
+    }
+  ],
+  "validation": [
+    "Check click, Space, arrows, Home/End, looping, controlled state, disabled/read-only state, and complete accessible naming.",
+    "Check indicator movement after selection and resize, exact shared outer sizes, inset Root boundary, shallow selected elevation, focus containment, light/dark themes, reduced motion, forced colors, zoom, and RTL."
+  ],
+  "related": [
+    "radio-group",
+    "toggle-group",
+    "tabs",
+    "button",
+    "select",
+    "toolbar"
+  ]
+}

package/dist/agents/segment-group.md

@@ -0,0 +1,43 @@
+# SegmentGroup agent guide
+
+## Purpose
+
+Present one mutually exclusive immediate mode in a compact segmented surface with radio semantics and a moving visual indicator.
+
+## Use when
+
+- A small visible set such as list/grid, density, or appearance must keep exactly one immediate mode selected.
+
+## Choose something else when
+
+- Commands may be independently pressed, the choices select paired panels, or an ordinary form choice is needed. Use ToggleGroup, Tabs, or RadioGroup according to the interaction.
+
+## Required composition
+
+- Compose Root with one Indicator and directly owned Items; give Root a complete accessible name and every icon-only Item its own complete name.
+- Choose one shared size on Root so adjacent Button, Select, and other named-size controls align through Brick's control contract.
+
+## Rules
+
+- **MUST:** Use SegmentGroup only for one mutually exclusive value and preserve Atom Radio Group semantics and keyboard behavior.
+- **MUST:** Render one decorative Indicator for the canonical moving-selection recipe; selection and naming must remain on Items.
+- **MUST:** Do not use SegmentGroup for paired content panels or route navigation; use Tabs or navigation destinations.
+- **MUST:** Load styles.css or core.css plus segment-group.css.
+
+## Common mistakes
+
+- **Avoid:** Using ToggleGroup single mode for a required one-of-many mode or using SegmentGroup as visual tabs. **Instead:** Choose SegmentGroup for one compact radio-semantic mode and Tabs only when panels are paired.
+
+## Validation checklist
+
+- Check click, Space, arrows, Home/End, looping, controlled state, disabled/read-only state, and complete accessible naming.
+- Check indicator movement after selection and resize, exact shared outer sizes, inset Root boundary, shallow selected elevation, focus containment, light/dark themes, reduced motion, forced colors, zoom, and RTL.
+
+## Related guidance
+
+- `radio-group`
+- `toggle-group`
+- `tabs`
+- `button`
+- `select`
+- `toolbar`

package/dist/agents/select.json

@@ -0,0 +1,95 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "select",
+  "name": "Select",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present one compact finished choice from a predefined list while Atom owns selection, trigger and listbox semantics, keyboard behavior, positioning, dismissal, validation, and native select form behavior.",
+  "useWhen": [
+    "A person chooses exactly one value from a predefined list whose options should stay collapsed until opened."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A short set should remain visible, several values may be selected, editable filtering or free-form entry is required, or rows are commands or destinations.",
+      "useInstead": "RadioGroup, MultiSelect, Combobox, DropdownMenu, or Link"
+    }
+  ],
+  "composition": [
+    "Compose Select.Root with a named Select.Trigger containing Select.Value and optional Select.Icon, then exactly one Select.Content or Select.Listbox. Place stable uniquely valued Items with ItemText inside optional Viewport and Group with Label; add indicators, separators, scroll buttons, Portal, and a direct popup Arrow only when required.",
+    "Use the same sm, md, or lg size as adjacent button-like controls. Keep locale loading, routing, persistence, analytics, and every other effect in onValueChange at the application boundary."
+  ],
+  "rules": [
+    {
+      "id": "select-single-value",
+      "level": "must",
+      "statement": "Use Select only for one predefined value and keep controlled value and open state aligned with their matching callbacks."
+    },
+    {
+      "id": "select-trigger-name",
+      "level": "must",
+      "statement": "Give Trigger a visible Field label or equivalent accessible name; placeholder and selected value are not the control name, and Trigger must retain combobox, expanded, controls, active-descendant, required, read-only, invalid, and disabled relationships."
+    },
+    {
+      "id": "select-item-text",
+      "level": "must",
+      "statement": "Give every Item a stable unique value and ItemText or label, keep interactive descendants out, and preserve that text for closed display, option naming, typeahead, and the hidden native select."
+    },
+    {
+      "id": "select-keyboard-form",
+      "level": "must",
+      "statement": "Preserve Trigger-owned opening, Arrow/Home/End, typeahead, Enter/Space selection, Tab, Escape, disabled skipping, focus restoration, native select options and submission, required validity, external form association, and reset."
+    },
+    {
+      "id": "select-popup-anatomy",
+      "level": "must",
+      "statement": "Render Content or Listbox once, keep Arrow directly inside it, and keep scroll buttons outside the registered Viewport so Atom owns positioning, collision, dismissal, and overflow state."
+    },
+    {
+      "id": "select-application-effect",
+      "level": "must",
+      "statement": "Keep translation loading, locale detection, persistence, navigation, analytics, and other effects in the application callback rather than inside Select."
+    },
+    {
+      "id": "select-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus select.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using placeholder or a selected code as the only name, omitting ItemText, rendering both popup owners, or rebuilding options as clickable rows.",
+      "correction": "Name Trigger separately and preserve one Atom-owned popup with registered stable Items and ItemText."
+    },
+    {
+      "mistake": "Using Select for multiple or editable choice, commands, navigation rows, or hidden application state and effects.",
+      "correction": "Choose MultiSelect, Combobox, DropdownMenu, or Link and connect legitimate value effects through onValueChange."
+    }
+  ],
+  "validation": [
+    "Verify Trigger naming and Field relationships, controlled and uncontrolled value and open state, placeholder and closed selected label, pointer/touch and keyboard opening, active descendant, Home/End, typeahead, selection, disabled Items, Tab, Escape, outside activation, and focus return.",
+    "Verify hidden native options and submission, required inline/native validity, external form, reset, groups and labels, Viewport and scroll buttons, Portal and non-Portal paths, Arrow placement, direction, collision handling, and nested modal ownership.",
+    "Verify all sizes, long localized labels, narrow widths, zoom, RTL, touch targets, light and dark appearance, forced colors, and alignment with adjacent button-like controls."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "select",
+      "versionPolicy": "installed-exact"
+    },
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "listbox",
+      "versionPolicy": "installed-exact"
+    },
+    "field",
+    "form",
+    "radio-group",
+    "combobox",
+    "multi-select",
+    "dropdown-menu",
+    "link"
+  ]
+}

package/dist/agents/select.md

@@ -0,0 +1,51 @@
+# Select agent guide
+
+## Purpose
+
+Present one compact finished choice from a predefined list while Atom owns selection, trigger and listbox semantics, keyboard behavior, positioning, dismissal, validation, and native select form behavior.
+
+## Use when
+
+- A person chooses exactly one value from a predefined list whose options should stay collapsed until opened.
+
+## Choose something else when
+
+- A short set should remain visible, several values may be selected, editable filtering or free-form entry is required, or rows are commands or destinations. Use RadioGroup, MultiSelect, Combobox, DropdownMenu, or Link.
+
+## Required composition
+
+- Compose Select.Root with a named Select.Trigger containing Select.Value and optional Select.Icon, then exactly one Select.Content or Select.Listbox. Place stable uniquely valued Items with ItemText inside optional Viewport and Group with Label; add indicators, separators, scroll buttons, Portal, and a direct popup Arrow only when required.
+- Use the same sm, md, or lg size as adjacent button-like controls. Keep locale loading, routing, persistence, analytics, and every other effect in onValueChange at the application boundary.
+
+## Rules
+
+- **MUST:** Use Select only for one predefined value and keep controlled value and open state aligned with their matching callbacks.
+- **MUST:** Give Trigger a visible Field label or equivalent accessible name; placeholder and selected value are not the control name, and Trigger must retain combobox, expanded, controls, active-descendant, required, read-only, invalid, and disabled relationships.
+- **MUST:** Give every Item a stable unique value and ItemText or label, keep interactive descendants out, and preserve that text for closed display, option naming, typeahead, and the hidden native select.
+- **MUST:** Preserve Trigger-owned opening, Arrow/Home/End, typeahead, Enter/Space selection, Tab, Escape, disabled skipping, focus restoration, native select options and submission, required validity, external form association, and reset.
+- **MUST:** Render Content or Listbox once, keep Arrow directly inside it, and keep scroll buttons outside the registered Viewport so Atom owns positioning, collision, dismissal, and overflow state.
+- **MUST:** Keep translation loading, locale detection, persistence, navigation, analytics, and other effects in the application callback rather than inside Select.
+- **MUST:** Load styles.css or core.css plus select.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Using placeholder or a selected code as the only name, omitting ItemText, rendering both popup owners, or rebuilding options as clickable rows. **Instead:** Name Trigger separately and preserve one Atom-owned popup with registered stable Items and ItemText.
+- **Avoid:** Using Select for multiple or editable choice, commands, navigation rows, or hidden application state and effects. **Instead:** Choose MultiSelect, Combobox, DropdownMenu, or Link and connect legitimate value effects through onValueChange.
+
+## Validation checklist
+
+- Verify Trigger naming and Field relationships, controlled and uncontrolled value and open state, placeholder and closed selected label, pointer/touch and keyboard opening, active descendant, Home/End, typeahead, selection, disabled Items, Tab, Escape, outside activation, and focus return.
+- Verify hidden native options and submission, required inline/native validity, external form, reset, groups and labels, Viewport and scroll buttons, Portal and non-Portal paths, Arrow placement, direction, collision handling, and nested modal ownership.
+- Verify all sizes, long localized labels, narrow widths, zoom, RTL, touch targets, light and dark appearance, forced colors, and alignment with adjacent button-like controls.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/select`
+- `@flowstack-ui/atom/agents/listbox`
+- `field`
+- `form`
+- `radio-group`
+- `combobox`
+- `multi-select`
+- `dropdown-menu`
+- `link`

package/dist/agents/show.json

@@ -29,6 +29,16 @@
       "level": "must",
       "statement": "Keep IDs, landmarks, form relationships, and focus order valid in every visible alternative."
     },
+    {
+      "id": "show-transparent-layout",
+      "level": "must",
+      "statement": "Rely on Show's layout-transparent visible state inside parent layouts and put paint or geometry on a child layout component."
+    },
+    {
+      "id": "show-default-props",
+      "level": "must",
+      "statement": "Omit default-valued props such as as=div; use as only for deliberate HTML semantics or valid document structure."
+    },
     {
       "id": "show-css",
       "level": "must",
@@ -36,6 +46,10 @@
     }
   ],
   "commonMistakes": [
+    {
+      "mistake": "Adding application CSS to repair Show spacing or writing as=div even though div is the default.",
+      "correction": "Rely on Show's layout-transparent default and specify as only when semantics require another host."
+    },
     {
       "mistake": "Forgetting show.css or rendering duplicate visible navigation because Show and Hide use the wrong thresholds.",
       "correction": "Load the modular CSS and verify exact breakpoint boundaries."

package/dist/agents/show.md

@@ -20,10 +20,13 @@ Show content only at selected Brick breakpoints through CSS, avoiding JavaScript
 
 - **MUST:** Use Show's CSS breakpoint contract rather than client viewport detection for responsive first paint.
 - **MUST:** Keep IDs, landmarks, form relationships, and focus order valid in every visible alternative.
+- **MUST:** Rely on Show's layout-transparent visible state inside parent layouts and put paint or geometry on a child layout component.
+- **MUST:** Omit default-valued props such as as=div; use as only for deliberate HTML semantics or valid document structure.
 - **MUST:** Load styles.css or core.css plus show.css.
 
 ## Common mistakes
 
+- **Avoid:** Adding application CSS to repair Show spacing or writing as=div even though div is the default. **Instead:** Rely on Show's layout-transparent default and specify as only when semantics require another host.
 - **Avoid:** Forgetting show.css or rendering duplicate visible navigation because Show and Hide use the wrong thresholds. **Instead:** Load the modular CSS and verify exact breakpoint boundaries.
 
 ## Validation checklist

package/dist/agents/sidebar.json

@@ -16,7 +16,8 @@
     }
   ],
   "composition": [
-    "Compose Root with Trigger, Panel, and Main; place NavList and other Brick content inside Panel and keep one page-level main landmark."
+    "Compose Root with Trigger, Panel, and Main; place NavList and other Brick content inside Panel and keep one page-level main landmark.",
+    "When Panel content can exceed its constrained block size, place ScrollArea.Root and ScrollArea.Viewport inside Sidebar.Content; Sidebar.Content is a flexible region, not a scroll owner."
   ],
   "rules": [
     {
@@ -29,6 +30,16 @@
       "level": "must",
       "statement": "Avoid duplicate main landmarks when composing Sidebar.Main into an existing shell."
     },
+    {
+      "id": "sidebar-surface",
+      "level": "must",
+      "statement": "Choose panel paint with surface; use transparent when an ancestor Surface owns the shell background instead of overriding Sidebar background selectors."
+    },
+    {
+      "id": "sidebar-scroll-ownership",
+      "level": "must",
+      "statement": "Keep Sidebar.Content flexible and compose a bounded ScrollArea when long panel content must remain reachable; do not clip or assign ad hoc overflow to navigation children."
+    },
     {
       "id": "sidebar-css",
       "level": "must",
@@ -37,16 +48,18 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Using Sidebar as a modal drawer or letting highlighted rail items overflow into Main.",
-      "correction": "Use Drawer for modal use and validate Sidebar's expanded, rail, and offcanvas geometry."
+      "mistake": "Using Sidebar as a modal drawer, overriding panel background selectors, letting highlighted rail items overflow into Main, or assuming Sidebar.Content scrolls automatically.",
+      "correction": "Use Drawer for modal use, choose the public surface recipe, compose ScrollArea for bounded long content, and validate Sidebar's expanded, rail, and offcanvas geometry."
     }
   ],
   "validation": [
     "Check every state, both sides, current navigation item, long labels, icons, counts, trigger, focus, inert offcanvas state, zoom, narrow widths, and RTL.",
+    "When content can overflow, verify the composed ScrollArea reaches the first and last panel destinations without moving Sidebar.Main.",
     "Confirm landmark names and CSS delivery."
   ],
   "related": [
     "nav-list",
+    "scroll-area",
     "drawer",
     "app-bar",
     "container",

package/dist/agents/sidebar.md

@@ -15,25 +15,30 @@ Provide a finished application-shell side region with expanded, rail, and offcan
 ## Required composition
 
 - Compose Root with Trigger, Panel, and Main; place NavList and other Brick content inside Panel and keep one page-level main landmark.
+- When Panel content can exceed its constrained block size, place ScrollArea.Root and ScrollArea.Viewport inside Sidebar.Content; Sidebar.Content is a flexible region, not a scroll owner.
 
 ## Rules
 
 - **MUST:** Use Sidebar state and public layout hooks instead of manually translating a generic aside and overlapping its active items.
 - **MUST:** Avoid duplicate main landmarks when composing Sidebar.Main into an existing shell.
+- **MUST:** Choose panel paint with surface; use transparent when an ancestor Surface owns the shell background instead of overriding Sidebar background selectors.
+- **MUST:** Keep Sidebar.Content flexible and compose a bounded ScrollArea when long panel content must remain reachable; do not clip or assign ad hoc overflow to navigation children.
 - **MUST:** Load styles.css or core.css plus sidebar.css and every composed child stylesheet.
 
 ## Common mistakes
 
-- **Avoid:** Using Sidebar as a modal drawer or letting highlighted rail items overflow into Main. **Instead:** Use Drawer for modal use and validate Sidebar's expanded, rail, and offcanvas geometry.
+- **Avoid:** Using Sidebar as a modal drawer, overriding panel background selectors, letting highlighted rail items overflow into Main, or assuming Sidebar.Content scrolls automatically. **Instead:** Use Drawer for modal use, choose the public surface recipe, compose ScrollArea for bounded long content, and validate Sidebar's expanded, rail, and offcanvas geometry.
 
 ## Validation checklist
 
 - Check every state, both sides, current navigation item, long labels, icons, counts, trigger, focus, inert offcanvas state, zoom, narrow widths, and RTL.
+- When content can overflow, verify the composed ScrollArea reaches the first and last panel destinations without moving Sidebar.Main.
 - Confirm landmark names and CSS delivery.
 
 ## Related guidance
 
 - `nav-list`
+- `scroll-area`
 - `drawer`
 - `app-bar`
 - `container`

package/dist/agents/skeleton.json

@@ -0,0 +1,73 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "skeleton",
+  "name": "Skeleton",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Preserve expected content geometry during a short application-owned load without exposing placeholder content as meaningful UI.",
+  "useWhen": [
+    "The final geometry is known and a short loading operation would otherwise cause disruptive layout shift."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Progress duration is known, the operation failed, or the layout is not yet predictable.",
+      "useInstead": "Progress, an error recovery state, or a stable generic loading message according to the state"
+    }
+  ],
+  "composition": [
+    "Match each Skeleton shape and dimension to the expected final content, mark the owning region busy, and keep any required application status copy outside the aria-hidden placeholder."
+  ],
+  "rules": [
+    {
+      "id": "skeleton-geometry",
+      "level": "must",
+      "statement": "Use supported shape, line, width, and height inputs to preserve the expected final geometry rather than decorating an arbitrary empty region."
+    },
+    {
+      "id": "skeleton-busy-owner",
+      "level": "must",
+      "statement": "Mark the owning region aria-busy while loading; Skeleton is aria-hidden and is not a status or live region."
+    },
+    {
+      "id": "skeleton-no-fake-content",
+      "level": "must",
+      "statement": "Do not place fake names, notifications, controls, or other meaningful placeholder content in the accessibility tree."
+    },
+    {
+      "id": "skeleton-appearance",
+      "level": "must",
+      "statement": "Keep the contextual default paint or another semantic Theme role visibly distinct from the actual containing surface in light and dark appearance."
+    },
+    {
+      "id": "skeleton-motion",
+      "level": "must",
+      "statement": "Preserve reduced-motion and forced-colors behavior and avoid application animation overrides."
+    },
+    {
+      "id": "skeleton-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus skeleton.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Skeleton as generic decoration or relying on its animation as the only loading announcement.",
+      "correction": "Use Skeleton only for known geometry, mark the owning region busy, and provide application-owned status text only when an announcement is actually required."
+    },
+    {
+      "mistake": "Selecting a semantic surface token that resolves to the same paint as the containing overlay in one appearance.",
+      "correction": "Keep the contextual primary-text tint or verify any semantic override against every containing surface in both appearances."
+    }
+  ],
+  "validation": [
+    "Check stable geometry before and after load, aria-hidden placeholder output, owning-region busy state, and absence of focusable fake content.",
+    "Check placeholder visibility on base, raised, and overlay surfaces across light/dark appearance, narrow widths, zoom, increased text size, reduced motion, and forced colors."
+  ],
+  "related": [
+    "progress",
+    "frame",
+    "stack",
+    "feed"
+  ]
+}

package/dist/agents/skeleton.md

@@ -0,0 +1,43 @@
+# Skeleton agent guide
+
+## Purpose
+
+Preserve expected content geometry during a short application-owned load without exposing placeholder content as meaningful UI.
+
+## Use when
+
+- The final geometry is known and a short loading operation would otherwise cause disruptive layout shift.
+
+## Choose something else when
+
+- Progress duration is known, the operation failed, or the layout is not yet predictable. Use Progress, an error recovery state, or a stable generic loading message according to the state.
+
+## Required composition
+
+- Match each Skeleton shape and dimension to the expected final content, mark the owning region busy, and keep any required application status copy outside the aria-hidden placeholder.
+
+## Rules
+
+- **MUST:** Use supported shape, line, width, and height inputs to preserve the expected final geometry rather than decorating an arbitrary empty region.
+- **MUST:** Mark the owning region aria-busy while loading; Skeleton is aria-hidden and is not a status or live region.
+- **MUST:** Do not place fake names, notifications, controls, or other meaningful placeholder content in the accessibility tree.
+- **MUST:** Keep the contextual default paint or another semantic Theme role visibly distinct from the actual containing surface in light and dark appearance.
+- **MUST:** Preserve reduced-motion and forced-colors behavior and avoid application animation overrides.
+- **MUST:** Load styles.css or core.css plus skeleton.css.
+
+## Common mistakes
+
+- **Avoid:** Using Skeleton as generic decoration or relying on its animation as the only loading announcement. **Instead:** Use Skeleton only for known geometry, mark the owning region busy, and provide application-owned status text only when an announcement is actually required.
+- **Avoid:** Selecting a semantic surface token that resolves to the same paint as the containing overlay in one appearance. **Instead:** Keep the contextual primary-text tint or verify any semantic override against every containing surface in both appearances.
+
+## Validation checklist
+
+- Check stable geometry before and after load, aria-hidden placeholder output, owning-region busy state, and absence of focusable fake content.
+- Check placeholder visibility on base, raised, and overlay surfaces across light/dark appearance, narrow widths, zoom, increased text size, reduced motion, and forced colors.
+
+## Related guidance
+
+- `progress`
+- `frame`
+- `stack`
+- `feed`