@flowstack-ui/brick 0.1.9 → 0.1.11

package/dist/agents/status.json

@@ -0,0 +1,59 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "status",
+  "name": "Status",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a compact passive state with a semantic indicator and readable label, or a decorative indicator beside text that already carries the state.",
+  "useWhen": [
+    "A process, entity, availability, health, or review state needs a dot-plus-label presentation."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content is a category, accolade, count, progress value, consequential message, or avatar-only presence ring.",
+      "useInstead": "Badge, NotificationBadge, Progress, Alert, or Avatar status"
+    }
+  ],
+  "composition": [
+    "Compose Root with one decorative Indicator and one visible Label by default. Omit Label only when adjacent visible or visually hidden text already carries the complete state and the indicator-only Root is aria-hidden."
+  ],
+  "rules": [
+    {
+      "id": "status-visible-label",
+      "level": "must",
+      "statement": "Always provide state text. Render it through Label by default; indicator-only composition is allowed only when adjacent visible or visually hidden text already carries the complete meaning and the Root is decorative."
+    },
+    {
+      "id": "status-semantic-tone",
+      "level": "must",
+      "statement": "Choose success, warning, danger, info, accent, or neutral from the state meaning, not from decorative preference."
+    },
+    {
+      "id": "status-live-region",
+      "level": "must",
+      "statement": "Do not assume Status announces changes; author role=status or live-region attributes only when the application owns and validates that announcement policy."
+    },
+    {
+      "id": "status-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus status.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using success for a Call button, warning for a gold accolade, or Badge merely to draw a status dot.",
+      "correction": "Use action hierarchy for operations, accent/neutral Badge for accolades, and Status for actual dot-plus-label state."
+    }
+  ],
+  "validation": [
+    "Check visible state text, semantic tone, decorative indicator, primary label color, light/dark, forced colors, zoom, RTL, and deliberate live-region ownership."
+  ],
+  "related": [
+    "badge",
+    "notification-badge",
+    "avatar",
+    "progress",
+    "toast"
+  ]
+}

package/dist/agents/status.md

@@ -0,0 +1,40 @@
+# Status agent guide
+
+## Purpose
+
+Present a compact passive state with a semantic indicator and readable label, or a decorative indicator beside text that already carries the state.
+
+## Use when
+
+- A process, entity, availability, health, or review state needs a dot-plus-label presentation.
+
+## Choose something else when
+
+- The content is a category, accolade, count, progress value, consequential message, or avatar-only presence ring. Use Badge, NotificationBadge, Progress, Alert, or Avatar status.
+
+## Required composition
+
+- Compose Root with one decorative Indicator and one visible Label by default. Omit Label only when adjacent visible or visually hidden text already carries the complete state and the indicator-only Root is aria-hidden.
+
+## Rules
+
+- **MUST:** Always provide state text. Render it through Label by default; indicator-only composition is allowed only when adjacent visible or visually hidden text already carries the complete meaning and the Root is decorative.
+- **MUST:** Choose success, warning, danger, info, accent, or neutral from the state meaning, not from decorative preference.
+- **MUST:** Do not assume Status announces changes; author role=status or live-region attributes only when the application owns and validates that announcement policy.
+- **MUST:** Load styles.css or core.css plus status.css.
+
+## Common mistakes
+
+- **Avoid:** Using success for a Call button, warning for a gold accolade, or Badge merely to draw a status dot. **Instead:** Use action hierarchy for operations, accent/neutral Badge for accolades, and Status for actual dot-plus-label state.
+
+## Validation checklist
+
+- Check visible state text, semantic tone, decorative indicator, primary label color, light/dark, forced colors, zoom, RTL, and deliberate live-region ownership.
+
+## Related guidance
+
+- `badge`
+- `notification-badge`
+- `avatar`
+- `progress`
+- `toast`

package/dist/agents/surface.json

@@ -5,7 +5,7 @@
   "package": "@flowstack-ui/brick",
   "layer": "brick",
   "kind": "component",
-  "purpose": "Apply semantic background layers, boundaries, elevation, radius, inset, and optional decorative media layering without implying a specific content object.",
+  "purpose": "Apply semantic background tones and 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.",
     "Decorative image, video, canvas, or authored artwork needs to sit behind foreground content with an optional contrast scrim."
@@ -17,7 +17,7 @@
     }
   ],
   "composition": [
-    "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. When layered foreground content needs four-sided breathing room, set inset on the Surface root; Content owns foreground layering, not padding."
+    "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. When layered foreground content needs four-sided breathing room, set inset on the Surface root; Content owns foreground layering, not padding. Use xl and 2xl for page-sized panels or heroes, and the responsive value shape when that inset should grow with the viewport."
   ],
   "rules": [
     {
@@ -25,6 +25,11 @@
       "level": "should",
       "statement": "Choose surface level by information hierarchy, not decoration alone."
     },
+    {
+      "id": "surface-accent-tone",
+      "level": "should",
+      "statement": "Use accent tone only for a branded or conversion plane, never as a generic status surface."
+    },
     {
       "id": "surface-as-child",
       "level": "must",
@@ -40,6 +45,21 @@
       "level": "must",
       "statement": "Use the Surface inset recipe for four-sided internal spacing; Surface.Content provides z-order only, and Stack startSpacing/endSpacing remain axis-specific."
     },
+    {
+      "id": "surface-inset-scale",
+      "level": "should",
+      "statement": "Use sm through lg for local panels and reserve xl or 2xl for page-sized panels, heroes, and split layouts."
+    },
+    {
+      "id": "surface-responsive-inset",
+      "level": "must",
+      "statement": "Write responsive inset mobile first with a required initial value and only the breakpoint overrides that change; omit a scalar inset none because none is already the default."
+    },
+    {
+      "id": "surface-inset-measure",
+      "level": "must",
+      "statement": "Change a centered child's Frame or Container measure when the visible issue is line length or available width; Surface inset moves every child edge and does not replace content measure."
+    },
     {
       "id": "surface-media-decoration",
       "level": "must",
@@ -78,13 +98,22 @@
     {
       "mistake": "Expecting Surface.Content or Stack edge spacing to create padding on every foreground edge.",
       "correction": "Set inset on the Surface root, then use Stack only for child arrangement and primary-axis spacing."
+    },
+    {
+      "mistake": "Repeating page-panel padding in Block CSS.",
+      "correction": "Use a larger or responsive Surface inset; use the public padding token only for one deliberate asymmetric relationship that the closed recipe cannot express."
+    },
+    {
+      "mistake": "Increasing inset to make a narrow centered child look wider.",
+      "correction": "Adjust the child's Frame or Container measure independently."
     }
   ],
   "validation": [
     "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.",
-    "Check that layered foreground content has intentional spacing on all four logical edges at narrow and wide sizes."
+    "Check that layered foreground content has intentional spacing on all four logical edges at narrow and wide sizes.",
+    "Check that responsive inset changes at the intended shared breakpoint while media and scrim remain edge-to-edge."
   ],
   "related": [
     "card",

package/dist/agents/surface.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Apply semantic background layers, boundaries, elevation, radius, inset, and optional decorative media layering without implying a specific content object.
+Apply semantic background tones and layers, boundaries, elevation, radius, inset, and optional decorative media layering without implying a specific content object.
 
 ## Use when
 
@@ -15,14 +15,18 @@ Apply semantic background layers, boundaries, elevation, radius, inset, and opti
 
 ## Required composition
 
-- 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. When layered foreground content needs four-sided breathing room, set inset on the Surface root; Content owns foreground layering, not padding.
+- 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. When layered foreground content needs four-sided breathing room, set inset on the Surface root; Content owns foreground layering, not padding. Use xl and 2xl for page-sized panels or heroes, and the responsive value shape when that inset should grow with the viewport.
 
 ## Rules
 
 - **SHOULD:** Choose surface level by information hierarchy, not decoration alone.
+- **SHOULD:** Use accent tone only for a branded or conversion plane, never as a generic status surface.
 - **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:** Use the Surface inset recipe for four-sided internal spacing; Surface.Content provides z-order only, and Stack startSpacing/endSpacing remain axis-specific.
+- **SHOULD:** Use sm through lg for local panels and reserve xl or 2xl for page-sized panels, heroes, and split layouts.
+- **MUST:** Write responsive inset mobile first with a required initial value and only the breakpoint overrides that change; omit a scalar inset none because none is already the default.
+- **MUST:** Change a centered child's Frame or Container measure when the visible issue is line length or available width; Surface inset moves every child edge and does not replace content measure.
 - **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.
@@ -34,6 +38,8 @@ Apply semantic background layers, boundaries, elevation, radius, inset, and opti
 - **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.
 - **Avoid:** Expecting Surface.Content or Stack edge spacing to create padding on every foreground edge. **Instead:** Set inset on the Surface root, then use Stack only for child arrangement and primary-axis spacing.
+- **Avoid:** Repeating page-panel padding in Block CSS. **Instead:** Use a larger or responsive Surface inset; use the public padding token only for one deliberate asymmetric relationship that the closed recipe cannot express.
+- **Avoid:** Increasing inset to make a narrow centered child look wider. **Instead:** Adjust the child's Frame or Container measure independently.
 
 ## Validation checklist
 
@@ -41,6 +47,7 @@ Apply semantic background layers, boundaries, elevation, radius, inset, and opti
 - 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.
 - Check that layered foreground content has intentional spacing on all four logical edges at narrow and wide sizes.
+- Check that responsive inset changes at the intended shared breakpoint while media and scrim remain edge-to-edge.
 
 ## Related guidance
 

package/dist/agents/swipeable-item.json

@@ -0,0 +1,93 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "swipeable-item",
+  "name": "SwipeableItem",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Enhance a finished list-like row with logical start or end quick-action panels revealed by horizontal drag or keyboard while Atom owns state, measurement, gesture intent, scrolling preservation, and keyboard behavior.",
+  "useWhen": [
+    "A row has one or two frequent commands that benefit from touch reveal and every important command also remains available through an obvious tap or click route."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "There are many commands, discovery is critical, the row navigates or selects, or swipe would be surprising or the only pointer path.",
+      "useInstead": "DropdownMenu, visible Button or IconButton controls, Link, or the appropriate selection component"
+    }
+  ],
+  "composition": [
+    "Compose Root with one focusable Content surface and a labelled Actions group for each supported logical start or end side. Put real named Button or Link controls inside Actions and keep an obvious non-swipe route, normally a visible overflow trigger, inside Content.",
+    "Choose plain inside an existing row boundary or outline for a standalone boundary. Preserve surrounding List or Feed semantics and keep confirmation, undo, persistence, and coordination between rows in the application."
+  ],
+  "rules": [
+    {
+      "id": "swipeable-enhancement",
+      "level": "must",
+      "statement": "Treat swipe and keyboard reveal as enhancements; neither replaces the required obvious tap or click route to every important action."
+    },
+    {
+      "id": "swipeable-actions",
+      "level": "must",
+      "statement": "Give every Actions panel a localized accessible group name and every child complete native semantics; keep closed panels inert and accessibility-hidden."
+    },
+    {
+      "id": "swipeable-scroll-gesture",
+      "level": "must",
+      "statement": "Preserve pan-y vertical scrolling, horizontal intent detection, pointer capture, cancellation rollback, measured logical-side widths, threshold settlement, and one owned pointer interaction."
+    },
+    {
+      "id": "swipeable-keyboard",
+      "level": "must",
+      "statement": "Keep Content focusable and preserve direction-aware Arrow reveal, opposite-Arrow close, and Escape close only when Content owns the key; nested controls retain their own keyboard behavior."
+    },
+    {
+      "id": "swipeable-no-full-swipe",
+      "level": "must",
+      "statement": "Do not implement gesture execution around Brick SwipeableItem: Brick intentionally omits Atom's onFullSwipe and fullSwipeThreshold props so destructive or consequential commands require an explicit control."
+    },
+    {
+      "id": "swipeable-state",
+      "level": "must",
+      "statement": "Use openSide with onOpenSideChange or defaultOpenSide, preserve disabled versus focusable read-only behavior, and treat start and end as logical sides that follow LTR and RTL."
+    },
+    {
+      "id": "swipeable-responsive",
+      "level": "must",
+      "statement": "Keep authored Content wrapping, visible alternatives reachable, actions measured, and the shared clipped radius intact at narrow widths, zoom, RTL, forced colors, and reduced motion."
+    },
+    {
+      "id": "swipeable-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus swipeable-item.css and the CSS for every composed action or row component."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Making swipe the only route to Delete, blocking vertical scroll, firing a destructive threshold gesture, or letting Arrow keys from nested controls reveal actions.",
+      "correction": "Provide an obvious explicit control, preserve pan-y and gesture intent, use Brick's no-full-swipe API, and retain keyboard target isolation."
+    },
+    {
+      "mistake": "Using SwipeableItem as List, Feed, navigation, selection, confirmation, or multi-row coordination ownership.",
+      "correction": "Keep semantic row ownership and application effects outside the three-part enhancement boundary."
+    }
+  ],
+  "validation": [
+    "Verify controlled/uncontrolled start/end/null state, LTR and RTL mapping, measured widths and offsets, pointer down/move/up settlement, threshold boundaries, cancellation, capture, vertical pan, disabled/read-only state, and action closeOnClick.",
+    "Verify Content focus, Arrow reveal/close, Escape, descendant keyboard isolation, inert hidden panels, group and control names, obvious pointer fallback, absence of full-swipe execution, native props, refs, and real-browser mouse/touch scrolling.",
+    "Verify plain and outline boundaries, long content, narrow widths, zoom, RTL, shared radii, focus, light/dark appearance, forced colors, reduced motion, and surrounding List or Feed semantics."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "swipeable-item",
+      "versionPolicy": "installed-exact"
+    },
+    "dropdown-menu",
+    "button",
+    "icon-button",
+    "link",
+    "list",
+    "feed"
+  ]
+}

package/dist/agents/swipeable-item.md

@@ -0,0 +1,50 @@
+# SwipeableItem agent guide
+
+## Purpose
+
+Enhance a finished list-like row with logical start or end quick-action panels revealed by horizontal drag or keyboard while Atom owns state, measurement, gesture intent, scrolling preservation, and keyboard behavior.
+
+## Use when
+
+- A row has one or two frequent commands that benefit from touch reveal and every important command also remains available through an obvious tap or click route.
+
+## Choose something else when
+
+- There are many commands, discovery is critical, the row navigates or selects, or swipe would be surprising or the only pointer path. Use DropdownMenu, visible Button or IconButton controls, Link, or the appropriate selection component.
+
+## Required composition
+
+- Compose Root with one focusable Content surface and a labelled Actions group for each supported logical start or end side. Put real named Button or Link controls inside Actions and keep an obvious non-swipe route, normally a visible overflow trigger, inside Content.
+- Choose plain inside an existing row boundary or outline for a standalone boundary. Preserve surrounding List or Feed semantics and keep confirmation, undo, persistence, and coordination between rows in the application.
+
+## Rules
+
+- **MUST:** Treat swipe and keyboard reveal as enhancements; neither replaces the required obvious tap or click route to every important action.
+- **MUST:** Give every Actions panel a localized accessible group name and every child complete native semantics; keep closed panels inert and accessibility-hidden.
+- **MUST:** Preserve pan-y vertical scrolling, horizontal intent detection, pointer capture, cancellation rollback, measured logical-side widths, threshold settlement, and one owned pointer interaction.
+- **MUST:** Keep Content focusable and preserve direction-aware Arrow reveal, opposite-Arrow close, and Escape close only when Content owns the key; nested controls retain their own keyboard behavior.
+- **MUST:** Do not implement gesture execution around Brick SwipeableItem: Brick intentionally omits Atom's onFullSwipe and fullSwipeThreshold props so destructive or consequential commands require an explicit control.
+- **MUST:** Use openSide with onOpenSideChange or defaultOpenSide, preserve disabled versus focusable read-only behavior, and treat start and end as logical sides that follow LTR and RTL.
+- **MUST:** Keep authored Content wrapping, visible alternatives reachable, actions measured, and the shared clipped radius intact at narrow widths, zoom, RTL, forced colors, and reduced motion.
+- **MUST:** Load styles.css or core.css plus swipeable-item.css and the CSS for every composed action or row component.
+
+## Common mistakes
+
+- **Avoid:** Making swipe the only route to Delete, blocking vertical scroll, firing a destructive threshold gesture, or letting Arrow keys from nested controls reveal actions. **Instead:** Provide an obvious explicit control, preserve pan-y and gesture intent, use Brick's no-full-swipe API, and retain keyboard target isolation.
+- **Avoid:** Using SwipeableItem as List, Feed, navigation, selection, confirmation, or multi-row coordination ownership. **Instead:** Keep semantic row ownership and application effects outside the three-part enhancement boundary.
+
+## Validation checklist
+
+- Verify controlled/uncontrolled start/end/null state, LTR and RTL mapping, measured widths and offsets, pointer down/move/up settlement, threshold boundaries, cancellation, capture, vertical pan, disabled/read-only state, and action closeOnClick.
+- Verify Content focus, Arrow reveal/close, Escape, descendant keyboard isolation, inert hidden panels, group and control names, obvious pointer fallback, absence of full-swipe execution, native props, refs, and real-browser mouse/touch scrolling.
+- Verify plain and outline boundaries, long content, narrow widths, zoom, RTL, shared radii, focus, light/dark appearance, forced colors, reduced motion, and surrounding List or Feed semantics.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/swipeable-item`
+- `dropdown-menu`
+- `button`
+- `icon-button`
+- `link`
+- `list`
+- `feed`

package/dist/agents/switch.json

@@ -0,0 +1,92 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "switch",
+  "name": "Switch",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished immediately applied on/off setting while Atom owns switch semantics, controlled or uncontrolled state, keyboard activation, validation, and optional form participation.",
+  "useWhen": [
+    "A setting becomes active or inactive immediately when the user operates it."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The choice is a form answer applied later, a command whose pressed state remains active, or one of several exclusive values.",
+      "useInstead": "Checkbox, Toggle, or RadioGroup"
+    }
+  ],
+  "composition": [
+    "Give Switch.Root a stable visible or native accessible setting name and add Switch.Thumb as its decorative movable part. Compose Root in Field when visible Label, Description, Error, required, or invalid context is needed; use name, value, and form when checked state must submit.",
+    "Choose Root size sm, md, or lg for the finished track, thumb, travel, and target geometry. Keep Thumb decorative and let Atom state attributes drive Brick paint."
+  ],
+  "rules": [
+    {
+      "id": "switch-immediate",
+      "level": "must",
+      "statement": "Use Switch only for an immediately applied on/off setting; use Checkbox for a deferred form answer and Toggle for a persistent pressed command."
+    },
+    {
+      "id": "switch-name",
+      "level": "must",
+      "statement": "Give Root a complete stable accessible setting name with visible Field Label, native labeling, aria-label, or aria-labelledby; Thumb remains decorative and aria-hidden."
+    },
+    {
+      "id": "switch-state",
+      "level": "must",
+      "statement": "Use checked with onCheckedChange for controlled state or defaultChecked for uncontrolled state and preserve role=switch with boolean aria-checked."
+    },
+    {
+      "id": "switch-readonly",
+      "level": "must",
+      "statement": "Use readOnly when the setting must stay focusable while Enter, Space, pointer, and custom-element activation cannot change state; do not replace it with disabled."
+    },
+    {
+      "id": "switch-form",
+      "level": "must",
+      "statement": "Preserve named checked-value submission, required validity, Field state and descriptions, validation focus, external form association, and uncontrolled reset when form behavior applies."
+    },
+    {
+      "id": "switch-state-paint",
+      "level": "must",
+      "statement": "Use Brick's canonical checked, unchecked, focus, disabled, read-only, and invalid paint; invalid changes the boundary without replacing the checked meaning, and mixed or loading state is unsupported."
+    },
+    {
+      "id": "switch-responsive",
+      "level": "should",
+      "statement": "Keep intrinsic geometry and complete target size, allow surrounding label text to reflow, and verify logical thumb travel in RTL without reversing on/off meaning."
+    },
+    {
+      "id": "switch-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus switch.css and Field CSS when composed."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Switch for a submit-later checkbox or pressed command, relying on Thumb as the accessible control, or changing the setting label between states.",
+      "correction": "Choose by timing and semantics, name Root directly, keep Thumb decorative, and preserve one stable setting name."
+    },
+    {
+      "mistake": "Using disabled when the value should remain discoverable and read-only or inventing mixed, loading, tone, or shape props.",
+      "correction": "Use readOnly for locked focusable state and stay within the canonical binary visual recipe."
+    }
+  ],
+  "validation": [
+    "Verify accessible name, role and aria-checked, controlled and uncontrolled updates, pointer, Enter, and Space activation, disabled and read-only behavior, Thumb state inheritance, and native, asChild, and render semantics.",
+    "Verify named checked-value submission, required validity with and without name, invalid and Field descriptions, validation focus, external form association, and uncontrolled reset.",
+    "Verify three sizes, checked and unchecked contrast, focus, disabled, read-only and invalid paint, intrinsic and narrow layout, mobile targets, 200% text and 400% zoom, RTL travel, reduced motion, forced colors, and complete CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "switch",
+      "versionPolicy": "installed-exact"
+    },
+    "checkbox",
+    "toggle",
+    "radio-group",
+    "field",
+    "form"
+  ]
+}

package/dist/agents/switch.md

@@ -0,0 +1,49 @@
+# Switch agent guide
+
+## Purpose
+
+Present a finished immediately applied on/off setting while Atom owns switch semantics, controlled or uncontrolled state, keyboard activation, validation, and optional form participation.
+
+## Use when
+
+- A setting becomes active or inactive immediately when the user operates it.
+
+## Choose something else when
+
+- The choice is a form answer applied later, a command whose pressed state remains active, or one of several exclusive values. Use Checkbox, Toggle, or RadioGroup.
+
+## Required composition
+
+- Give Switch.Root a stable visible or native accessible setting name and add Switch.Thumb as its decorative movable part. Compose Root in Field when visible Label, Description, Error, required, or invalid context is needed; use name, value, and form when checked state must submit.
+- Choose Root size sm, md, or lg for the finished track, thumb, travel, and target geometry. Keep Thumb decorative and let Atom state attributes drive Brick paint.
+
+## Rules
+
+- **MUST:** Use Switch only for an immediately applied on/off setting; use Checkbox for a deferred form answer and Toggle for a persistent pressed command.
+- **MUST:** Give Root a complete stable accessible setting name with visible Field Label, native labeling, aria-label, or aria-labelledby; Thumb remains decorative and aria-hidden.
+- **MUST:** Use checked with onCheckedChange for controlled state or defaultChecked for uncontrolled state and preserve role=switch with boolean aria-checked.
+- **MUST:** Use readOnly when the setting must stay focusable while Enter, Space, pointer, and custom-element activation cannot change state; do not replace it with disabled.
+- **MUST:** Preserve named checked-value submission, required validity, Field state and descriptions, validation focus, external form association, and uncontrolled reset when form behavior applies.
+- **MUST:** Use Brick's canonical checked, unchecked, focus, disabled, read-only, and invalid paint; invalid changes the boundary without replacing the checked meaning, and mixed or loading state is unsupported.
+- **SHOULD:** Keep intrinsic geometry and complete target size, allow surrounding label text to reflow, and verify logical thumb travel in RTL without reversing on/off meaning.
+- **MUST:** Load styles.css or core.css plus switch.css and Field CSS when composed.
+
+## Common mistakes
+
+- **Avoid:** Using Switch for a submit-later checkbox or pressed command, relying on Thumb as the accessible control, or changing the setting label between states. **Instead:** Choose by timing and semantics, name Root directly, keep Thumb decorative, and preserve one stable setting name.
+- **Avoid:** Using disabled when the value should remain discoverable and read-only or inventing mixed, loading, tone, or shape props. **Instead:** Use readOnly for locked focusable state and stay within the canonical binary visual recipe.
+
+## Validation checklist
+
+- Verify accessible name, role and aria-checked, controlled and uncontrolled updates, pointer, Enter, and Space activation, disabled and read-only behavior, Thumb state inheritance, and native, asChild, and render semantics.
+- Verify named checked-value submission, required validity with and without name, invalid and Field descriptions, validation focus, external form association, and uncontrolled reset.
+- Verify three sizes, checked and unchecked contrast, focus, disabled, read-only and invalid paint, intrinsic and narrow layout, mobile targets, 200% text and 400% zoom, RTL travel, reduced motion, forced colors, and complete CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/switch`
+- `checkbox`
+- `toggle`
+- `radio-group`
+- `field`
+- `form`

package/dist/agents/table.json

@@ -0,0 +1,113 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "table",
+  "name": "Table",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present finished static row-and-column relationships with native table semantics while Atom owns the semantic parts and sort metadata.",
+  "useWhen": [
+    "People need to compare values across meaningful columns in pricing, reports, invoices, inventories, audit results, or compact summaries."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The region needs arrow-key cell navigation, row selection, editing, resizing, or another interactive composite model.",
+      "useInstead": "Data Grid or an application-owned data tool"
+    },
+    {
+      "condition": "The content is a sequence without meaningful column relationships or a label/value definition structure.",
+      "useInstead": "List, Grid, Stack, or a semantic definition-list composition"
+    },
+    {
+      "condition": "The narrow layout must convert rows into unrelated cards and no longer preserves column comparison.",
+      "useInstead": "An application-owned alternate view with an explicit responsive policy"
+    }
+  ],
+  "composition": [
+    "Compose optional Container > Root > Caption, Header, Body, and optional Footer; place Row inside each section and Head or Cell inside Row according to native table content rules.",
+    "Use Head with scope=\"row\" for body row labels and keep the default column scope for header cells; use id and headers for complex associations.",
+    "Author Container explicitly when honest comparison needs horizontal overflow, and set the public minimum-inline-size token to the smallest width that preserves the column relationships.",
+    "When Table moves vertically, put the visible border and radius on the stable labelled Scroll Area viewport, use Table variant=line inside it, and keep persistent naming outside the moving viewport with aria-labelledby.",
+    "Put an independently named Button and optional decorative SortIndicator inside the active Head when the application owns sorting."
+  ],
+  "rules": [
+    {
+      "id": "table-native-relationships",
+      "level": "must",
+      "statement": "Preserve native table anatomy and meaningful row and column headers; do not rebuild tabular comparison with generic Grid, Stack, div, or ARIA role substitutes."
+    },
+    {
+      "id": "table-static-boundary",
+      "level": "must",
+      "statement": "Keep Table static and readable; do not add row focus, whole-row activation, selection, arrow-key cell navigation, data mapping, filtering, pagination, editing, or virtualization to Table."
+    },
+    {
+      "id": "table-explicit-overflow",
+      "level": "must",
+      "statement": "Author Table.Container or a separately labelled Scroll Area when wide comparison needs overflow; Root never inserts a wrapper and Table never hides columns or converts them into cards."
+    },
+    {
+      "id": "table-responsive-comparison",
+      "level": "must",
+      "statement": "At narrow widths, preserve header-to-cell relationships, complete material values, and an understandable comparison path rather than merely stacking unrelated plan or record cards."
+    },
+    {
+      "id": "table-vertical-scroll-boundary",
+      "level": "must",
+      "statement": "For bounded vertical scrolling, let the stable Scroll Area viewport own the visible border and radius; do not use a moving Table outline as the scroll-frame boundary."
+    },
+    {
+      "id": "table-sort-ownership",
+      "level": "must",
+      "statement": "Let the application sort data and pass sortDirection only to the active header; SortIndicator is decorative and never supplies the control, name, or behavior."
+    },
+    {
+      "id": "table-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus table.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using generic layout components for a pricing matrix because custom positioning feels easier.",
+      "correction": "Use Table's native Head and Cell relationships, then customize the closed recipes and public Table variables for the product-specific comparison."
+    },
+    {
+      "mistake": "Hiding material columns on mobile or visually cloning labels into card rows.",
+      "correction": "Contain honest horizontal overflow or provide a separately authored application view; do not destroy or fake the native column relationships."
+    },
+    {
+      "mistake": "Making rows hoverable or clickable without a complete interaction owner.",
+      "correction": "Keep rows structural and place independently named Brick links or buttons inside the appropriate cells."
+    },
+    {
+      "mistake": "Using Table variant=outline as the visible frame inside a vertically scrolling viewport.",
+      "correction": "Paint the stable Scroll Area viewport with Surface, use Table variant=line inside it, and connect a persistent external label with aria-labelledby."
+    },
+    {
+      "mistake": "Using a visible recommendation color as the only explanation for a preferred pricing column.",
+      "correction": "Keep the plan label and recommendation reason readable in ordinary text, then use Table paint only as supporting emphasis."
+    }
+  ],
+  "validation": [
+    "Check caption or surrounding naming, header scope, cell associations, source order, plan or record labels, and independently named controls.",
+    "Check Container overflow, the authored minimum comparison width, stable viewport corners during vertical scrolling, sticky header boundaries when used, 320 CSS pixels, zoom, long content, RTL, and no page-level horizontal overflow.",
+    "Check light and dark themes, forced colors, row and column boundaries, recommendation meaning without color, focus visibility for interactive descendants, and CSS delivery.",
+    "Check that sorting, selection, filtering, pagination, data services, and responsive alternate-view policy remain application owned."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "table",
+      "versionPolicy": "installed-exact"
+    },
+    "data-grid",
+    "tree-grid",
+    "scroll-area",
+    "button",
+    "badge",
+    "icon",
+    "text"
+  ]
+}