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

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

@@ -0,0 +1,194 @@
+# Surface
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: surface
+
+# Surface agent guide
+
+## Purpose
+
+Apply semantic background tones and layers, boundaries, elevation, radius, inset, and optional decorative media layering without implying a specific content object.
+
+## Use when
+
+- A region needs a semantic visual plane but Card, Dialog, or another purposeful component would add the wrong anatomy.
+- Decorative image, video, canvas, or authored artwork needs to sit behind foreground content with an optional contrast scrim.
+
+## Choose something else when
+
+- The region represents one bounded subject with card anatomy. Use Card.
+
+## 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. 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.
+- **SHOULD:** Choose Scrim strength through the public prop and let the theme provide only the semantic scrim color unless one deliberate instance requires an advanced recipe override.
+- **MUST:** Verify foreground contrast against every media state; Scrim does not prove contrast by itself.
+
+## Common mistakes
+
+- **Avoid:** Using arbitrary background colors to recreate a surface. **Instead:** Use Surface and theme its semantic tokens.
+- **Avoid:** Adding absolute-positioning and z-index CSS for ordinary background media. **Instead:** Use Surface.Media, Surface.Scrim, and Surface.Content.
+- **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
+
+- 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 responsive inset changes at the intended shared breakpoint while media and scrim remain edge-to-edge.
+
+## Related guidance
+
+- `card`
+- `section`
+- `container`
+- `stack`
+- `grid`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "surface",
+  "name": "Surface",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "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."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The region represents one bounded subject with card anatomy.",
+      "useInstead": "Card"
+    }
+  ],
+  "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. Use xl and 2xl for page-sized panels or heroes, and the responsive value shape when that inset should grow with the viewport."
+  ],
+  "rules": [
+    {
+      "id": "surface-semantic-level",
+      "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",
+      "statement": "Use asChild only with one existing non-Fragment host that already owns the required semantics or layout; preserve that child's meaning and keep Surface responsible only for paint."
+    },
+    {
+      "id": "surface-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus surface.css."
+    },
+    {
+      "id": "surface-inset-owner",
+      "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",
+      "statement": "Treat Surface.Media as decorative and noninteractive; keep meaningful media and controls in Content or ordinary document flow."
+    },
+    {
+      "id": "surface-media-image-fill",
+      "level": "must",
+      "statement": "Give Brick Image explicit fill inside Surface.Media so its actual Content and Fallback consume the complete media layer."
+    },
+    {
+      "id": "surface-media-content",
+      "level": "must",
+      "statement": "Put every foreground child inside Surface.Content when Media or Scrim is used."
+    },
+    {
+      "id": "surface-scrim-strength",
+      "level": "should",
+      "statement": "Choose Scrim strength through the public prop and let the theme provide only the semantic scrim color unless one deliberate instance requires an advanced recipe override."
+    },
+    {
+      "id": "surface-media-contrast",
+      "level": "must",
+      "statement": "Verify foreground contrast against every media state; Scrim does not prove contrast by itself."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using arbitrary background colors to recreate a surface.",
+      "correction": "Use Surface and theme its semantic tokens."
+    },
+    {
+      "mistake": "Adding absolute-positioning and z-index CSS for ordinary background media.",
+      "correction": "Use Surface.Media, Surface.Scrim, and Surface.Content."
+    },
+    {
+      "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 responsive inset changes at the intended shared breakpoint while media and scrim remain edge-to-edge."
+  ],
+  "related": [
+    "card",
+    "section",
+    "container",
+    "stack",
+    "grid"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/swipeable-item.txt

@@ -0,0 +1,154 @@
+# SwipeableItem
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: swipeable-item
+
+# 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`
+
+## Machine record
+
+```json
+{
+  "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/public/packages/brick/0.1.11/components/switch.txt

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