@flowstack-ui/agent-tools 0.1.0-bootstrap.0

package/public/packages/brick/0.1.11/components/segment-group.txt

@@ -0,0 +1,116 @@
+# SegmentGroup
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: segment-group
+
+# 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`
+
+## Machine record
+
+```json
+{
+  "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/public/packages/brick/0.1.11/components/select.txt

@@ -0,0 +1,157 @@
+# Select
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: select
+
+# 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`
+
+## Machine record
+
+```json
+{
+  "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/public/packages/brick/0.1.11/components/show.txt

@@ -0,0 +1,121 @@
+# Show
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: show
+
+# Show agent guide
+
+## Purpose
+
+Show content only at selected Brick breakpoints through CSS, avoiding JavaScript viewport state and hydration flicker.
+
+## Use when
+
+- A complete region should appear only at selected Brick breakpoints.
+
+## Choose something else when
+
+- Content must remain available to assistive technology while visually hidden, or rendering depends on authorization or data. Use VisuallyHidden or application conditional rendering.
+
+## Required composition
+
+- Wrap the smallest complete composition whose responsive presence changes; combine with Hide only for intentional alternate desktop/mobile structures.
+
+## Rules
+
+- **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
+
+- Test boundary pixels, zoom, first paint, hydration, focus order, landmarks, and duplicate IDs.
+- Confirm CSS is loaded.
+
+## Related guidance
+
+- `hide`
+- `visually-hidden`
+- `app-bar`
+- `drawer`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "show",
+  "name": "Show",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Show content only at selected Brick breakpoints through CSS, avoiding JavaScript viewport state and hydration flicker.",
+  "useWhen": [
+    "A complete region should appear only at selected Brick breakpoints."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Content must remain available to assistive technology while visually hidden, or rendering depends on authorization or data.",
+      "useInstead": "VisuallyHidden or application conditional rendering"
+    }
+  ],
+  "composition": [
+    "Wrap the smallest complete composition whose responsive presence changes; combine with Hide only for intentional alternate desktop/mobile structures."
+  ],
+  "rules": [
+    {
+      "id": "show-first-paint",
+      "level": "must",
+      "statement": "Use Show's CSS breakpoint contract rather than client viewport detection for responsive first paint."
+    },
+    {
+      "id": "show-valid-tree",
+      "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",
+      "statement": "Load styles.css or core.css plus show.css."
+    }
+  ],
+  "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."
+    }
+  ],
+  "validation": [
+    "Test boundary pixels, zoom, first paint, hydration, focus order, landmarks, and duplicate IDs.",
+    "Confirm CSS is loaded."
+  ],
+  "related": [
+    "hide",
+    "visually-hidden",
+    "app-bar",
+    "drawer"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/sidebar.txt

@@ -0,0 +1,126 @@
+# Sidebar
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: sidebar
+
+# Sidebar agent guide
+
+## Purpose
+
+Provide a finished application-shell side region with expanded, rail, and offcanvas visual states built on Atom Sidebar.
+
+## Use when
+
+- An application shell has persistent navigation or tools that collapse to a rail or leave the layout offcanvas.
+
+## Choose something else when
+
+- The side panel is a temporary modal mobile menu or a static content aside. Use Drawer or a semantic page region.
+
+## 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, 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`
+- `show`
+- `hide`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "sidebar",
+  "name": "Sidebar",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a finished application-shell side region with expanded, rail, and offcanvas visual states built on Atom Sidebar.",
+  "useWhen": [
+    "An application shell has persistent navigation or tools that collapse to a rail or leave the layout offcanvas."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The side panel is a temporary modal mobile menu or a static content aside.",
+      "useInstead": "Drawer or a semantic page region"
+    }
+  ],
+  "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": [
+    {
+      "id": "sidebar-layout-owner",
+      "level": "must",
+      "statement": "Use Sidebar state and public layout hooks instead of manually translating a generic aside and overlapping its active items."
+    },
+    {
+      "id": "sidebar-main",
+      "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",
+      "statement": "Load styles.css or core.css plus sidebar.css and every composed child stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "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",
+    "show",
+    "hide"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/skeleton.txt

@@ -0,0 +1,127 @@
+# Skeleton
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: skeleton
+
+# 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`
+
+## Machine record
+
+```json
+{
+  "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"
+  ]
+}
+```