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

package/public/packages/atom/0.24.0/components/badge.txt

@@ -0,0 +1,123 @@
+# Badge
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: badge
+
+# Badge agent guide
+
+## Purpose
+
+Wrap a short contextual label, count, or status as normal inline semantic content without adding interaction or automatic announcement behavior.
+
+## Use when
+
+- A compact count or status word supplements nearby content and can be understood from its visible owning context.
+
+## Choose something else when
+
+- The element performs an action, communicates task completion, represents identity, or a changing update must be announced automatically. Use Button, Progress, Avatar, or a deliberately chosen live-region pattern.
+
+## Required composition
+
+- Place concise Badge text beside the content it qualifies. Include a visual count attached to a control in that control's accessible naming or owning context, and add live-region semantics outside Badge only when the update's urgency and frequency justify announcement.
+
+## Rules
+
+- **MUST:** Keep Badge noninteractive; use a real Button or Link when the content activates an action or navigation.
+- **MUST:** Provide enough nearby text or owning-control context for a count or status to be understood without relying on color, shape, or position alone.
+- **MUST:** When Badge is visually attached to a control, ensure the meaningful count or status is included in that control's accessible name or description because a sibling Badge is not incorporated automatically.
+- **MUST:** Do not assume Badge announces changes; add an appropriate live region deliberately only when an update needs announcement and avoid noisy duplicate paths.
+- **MUST:** Do not rely on aria-label to give the default generic span meaning; use understandable text and surrounding semantics.
+
+## Common mistakes
+
+- **Avoid:** Making Badge clickable or using a color-only dot as an essential status. **Instead:** Use an actual interactive primitive for actions and include concise textual status in an understandable context.
+- **Avoid:** Assuming a notification count beside an icon button is part of the button name or will announce when it changes. **Instead:** Author the control name or description and live behavior explicitly.
+
+## Validation checklist
+
+- Verify concise count and text-status variants are understandable in reading order and without color, and that no unintended role, Tab stop, or keyboard behavior exists.
+- Inspect controls with attached Badges to confirm their accessible names or descriptions contain the meaningful status independently of visual proximity.
+- For dynamic updates, verify the chosen announcement owner, priority, and frequency and confirm Badge does not create a duplicate live path; verify server-safe subpath and composition behavior.
+
+## Related guidance
+
+- `button`
+- `progress`
+- `avatar`
+- `toast`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "badge",
+  "name": "Badge",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Wrap a short contextual label, count, or status as normal inline semantic content without adding interaction or automatic announcement behavior.",
+  "useWhen": [
+    "A compact count or status word supplements nearby content and can be understood from its visible owning context."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The element performs an action, communicates task completion, represents identity, or a changing update must be announced automatically.",
+      "useInstead": "Button, Progress, Avatar, or a deliberately chosen live-region pattern"
+    }
+  ],
+  "composition": [
+    "Place concise Badge text beside the content it qualifies. Include a visual count attached to a control in that control's accessible naming or owning context, and add live-region semantics outside Badge only when the update's urgency and frequency justify announcement."
+  ],
+  "rules": [
+    {
+      "id": "badge-passive",
+      "level": "must",
+      "statement": "Keep Badge noninteractive; use a real Button or Link when the content activates an action or navigation."
+    },
+    {
+      "id": "badge-context",
+      "level": "must",
+      "statement": "Provide enough nearby text or owning-control context for a count or status to be understood without relying on color, shape, or position alone."
+    },
+    {
+      "id": "badge-control-name",
+      "level": "must",
+      "statement": "When Badge is visually attached to a control, ensure the meaningful count or status is included in that control's accessible name or description because a sibling Badge is not incorporated automatically."
+    },
+    {
+      "id": "badge-live-boundary",
+      "level": "must",
+      "statement": "Do not assume Badge announces changes; add an appropriate live region deliberately only when an update needs announcement and avoid noisy duplicate paths."
+    },
+    {
+      "id": "badge-generic-span",
+      "level": "must",
+      "statement": "Do not rely on aria-label to give the default generic span meaning; use understandable text and surrounding semantics."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Making Badge clickable or using a color-only dot as an essential status.",
+      "correction": "Use an actual interactive primitive for actions and include concise textual status in an understandable context."
+    },
+    {
+      "mistake": "Assuming a notification count beside an icon button is part of the button name or will announce when it changes.",
+      "correction": "Author the control name or description and live behavior explicitly."
+    }
+  ],
+  "validation": [
+    "Verify concise count and text-status variants are understandable in reading order and without color, and that no unintended role, Tab stop, or keyboard behavior exists.",
+    "Inspect controls with attached Badges to confirm their accessible names or descriptions contain the meaningful status independently of visual proximity.",
+    "For dynamic updates, verify the chosen announcement owner, priority, and frequency and confirm Badge does not create a duplicate live path; verify server-safe subpath and composition behavior."
+  ],
+  "related": [
+    "button",
+    "progress",
+    "avatar",
+    "toast"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/bottom-navigation.txt

@@ -0,0 +1,96 @@
+# BottomNavigation
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: bottom-navigation
+
+# BottomNavigation agent guide
+
+## Purpose
+
+Provide a named navigation landmark with active state for a short, stable set of primary application destinations.
+
+## Use when
+
+- A compact application has a small stable set of top-level destinations commonly presented at the bottom.
+
+## Choose something else when
+
+- The items are long, grouped, or switch panels within one page. Use NavList or Tabs.
+
+## Required composition
+
+- Compose Item parts with unique values inside Root; provide href for real destinations and omit it only for application-controlled view changes.
+
+## Rules
+
+- **MUST:** Use link Items for URL destinations and button Items only for view changes.
+- **MUST:** Keep authored label text available as each Item's accessible name even when the styled layer hides it.
+
+## Common mistakes
+
+- **Avoid:** Using BottomNavigation for a large menu or hiding labels from assistive technology. **Instead:** Use NavList for larger navigation and preserve every Item name.
+
+## Validation checklist
+
+- Confirm the landmark name distinguishes it from other navigation.
+- Confirm the active destination exposes aria-current and disabled Items cannot navigate.
+
+## Related guidance
+
+- `nav-list`
+- `tabs`
+- `link`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "bottom-navigation",
+  "name": "BottomNavigation",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide a named navigation landmark with active state for a short, stable set of primary application destinations.",
+  "useWhen": [
+    "A compact application has a small stable set of top-level destinations commonly presented at the bottom."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The items are long, grouped, or switch panels within one page.",
+      "useInstead": "NavList or Tabs"
+    }
+  ],
+  "composition": [
+    "Compose Item parts with unique values inside Root; provide href for real destinations and omit it only for application-controlled view changes."
+  ],
+  "rules": [
+    {
+      "id": "bottom-nav-destination-semantics",
+      "level": "must",
+      "statement": "Use link Items for URL destinations and button Items only for view changes."
+    },
+    {
+      "id": "bottom-nav-label",
+      "level": "must",
+      "statement": "Keep authored label text available as each Item's accessible name even when the styled layer hides it."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using BottomNavigation for a large menu or hiding labels from assistive technology.",
+      "correction": "Use NavList for larger navigation and preserve every Item name."
+    }
+  ],
+  "validation": [
+    "Confirm the landmark name distinguishes it from other navigation.",
+    "Confirm the active destination exposes aria-current and disabled Items cannot navigate."
+  ],
+  "related": [
+    "nav-list",
+    "tabs",
+    "link"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/breadcrumb.txt

@@ -0,0 +1,96 @@
+# Breadcrumb
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: breadcrumb
+
+# Breadcrumb agent guide
+
+## Purpose
+
+Represent the current page's ancestry as a named navigation landmark and ordered hierarchy.
+
+## Use when
+
+- The current page belongs to a hierarchy and users may navigate to ancestor pages.
+
+## Choose something else when
+
+- The choices are result pages or a general destination list. Use Pagination or NavList.
+
+## Required composition
+
+- Compose Root > List > Item containing ancestor Link or the single current Page, with decorative Separator parts between items.
+
+## Rules
+
+- **MUST:** Render one non-link Page for the current location and use links only for ancestors.
+- **MUST:** When Ellipsis opens hidden pages, compose it with a real named button.
+
+## Common mistakes
+
+- **Avoid:** Making the current page another link or placing separators outside the ordered list. **Instead:** Use Page once and keep Item and Separator parts inside List.
+
+## Validation checklist
+
+- Confirm the nav has a useful accessible name and one aria-current page.
+- Confirm separators are absent from the accessibility tree.
+
+## Related guidance
+
+- `link`
+- `pagination`
+- `nav-list`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "breadcrumb",
+  "name": "Breadcrumb",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Represent the current page's ancestry as a named navigation landmark and ordered hierarchy.",
+  "useWhen": [
+    "The current page belongs to a hierarchy and users may navigate to ancestor pages."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The choices are result pages or a general destination list.",
+      "useInstead": "Pagination or NavList"
+    }
+  ],
+  "composition": [
+    "Compose Root > List > Item containing ancestor Link or the single current Page, with decorative Separator parts between items."
+  ],
+  "rules": [
+    {
+      "id": "breadcrumb-one-current",
+      "level": "must",
+      "statement": "Render one non-link Page for the current location and use links only for ancestors."
+    },
+    {
+      "id": "breadcrumb-interactive-ellipsis",
+      "level": "must",
+      "statement": "When Ellipsis opens hidden pages, compose it with a real named button."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Making the current page another link or placing separators outside the ordered list.",
+      "correction": "Use Page once and keep Item and Separator parts inside List."
+    }
+  ],
+  "validation": [
+    "Confirm the nav has a useful accessible name and one aria-current page.",
+    "Confirm separators are absent from the accessibility tree."
+  ],
+  "related": [
+    "link",
+    "pagination",
+    "nav-list"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/button.txt

@@ -0,0 +1,98 @@
+# Button
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: button
+
+# Button agent guide
+
+## Purpose
+
+Provide native action behavior or safe emphasized-link behavior while preserving the correct button or link semantics through custom rendering.
+
+## Use when
+
+- The user triggers an action such as submit, save, open, dismiss, or retry.
+- A destination is intentionally presented as an emphasized action control and Button receives its href.
+
+## Choose something else when
+
+- A destination should read as ordinary inline or standalone navigation. Use Link.
+
+## Required composition
+
+- Use Button.Root without href for an action and with href for an emphasized destination; compose through asChild or render only when the replacement preserves the resolved semantics.
+
+## Rules
+
+- **MUST:** Omit href for actions and provide href for emphasized destinations so Button resolves the correct native semantics.
+- **SHOULD:** Set type explicitly inside a form unless submit is intended.
+
+## Common mistakes
+
+- **Avoid:** Navigating from onPress without exposing a destination. **Instead:** Provide href for Button link mode, or use Link when the destination should read as ordinary navigation.
+
+## Validation checklist
+
+- Confirm the rendered element has an accessible name.
+- Confirm keyboard activation and disabled behavior match the intended action.
+
+## Related guidance
+
+- `link`
+- `pressable`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "button",
+  "name": "Button",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Provide native action behavior or safe emphasized-link behavior while preserving the correct button or link semantics through custom rendering.",
+  "useWhen": [
+    "The user triggers an action such as submit, save, open, dismiss, or retry.",
+    "A destination is intentionally presented as an emphasized action control and Button receives its href."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A destination should read as ordinary inline or standalone navigation.",
+      "useInstead": "Link"
+    }
+  ],
+  "composition": [
+    "Use Button.Root without href for an action and with href for an emphasized destination; compose through asChild or render only when the replacement preserves the resolved semantics."
+  ],
+  "rules": [
+    {
+      "id": "button-resolved-semantics",
+      "level": "must",
+      "statement": "Omit href for actions and provide href for emphasized destinations so Button resolves the correct native semantics."
+    },
+    {
+      "id": "button-explicit-type",
+      "level": "should",
+      "statement": "Set type explicitly inside a form unless submit is intended."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Navigating from onPress without exposing a destination.",
+      "correction": "Provide href for Button link mode, or use Link when the destination should read as ordinary navigation."
+    }
+  ],
+  "validation": [
+    "Confirm the rendered element has an accessible name.",
+    "Confirm keyboard activation and disabled behavior match the intended action."
+  ],
+  "related": [
+    "link",
+    "pressable",
+    "form"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/carousel.txt

@@ -0,0 +1,128 @@
+# Carousel
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: carousel
+
+# Carousel agent guide
+
+## Purpose
+
+Coordinate one-active-slide content rotation, optional automatic playback, direct selection, native swipe scrolling, and accessible inactive-slide semantics.
+
+## Use when
+
+- A small sequence of authored content should occupy one viewport and support previous, next, direct, touch, or optional timed selection.
+
+## Choose something else when
+
+- All items should remain visible, named document panels are selected, or a row reveals actions. Use ordinary layout or scrolling, Tabs, or SwipeableItem.
+
+## Required composition
+
+- Compose Root, Viewport, Track, and uniquely valued Slide parts; add Previous, Next, Picker with PickerItem, and RotationControl only when the experience needs those controls.
+
+## Rules
+
+- **MUST:** Provide value or defaultValue matching one Slide and give every Slide a short unique accessible label.
+- **MUST:** When automatic rotation is enabled, include visible RotationControl, Previous, and Next controls; Picker controls remain optional.
+- **SHOULD:** Keep grouped PickerItem controls to a small set because each native picker button is a tab stop.
+- **MUST:** Supply viewport overflow, one-slide track geometry, and scroll snap in the styled layer; do not replace Atom selection, pause, or inactive semantics.
+- **MUST:** Keep styled viewport motion instant until Root exposes data-initialized, then enable the ordinary motion recipe so SSR hydration cannot start a competing native snap animation.
+- **MUST:** Style carousel-loop-boundary spacers and data-loop-position Slides as one-viewport boundary positions so Next and Previous preserve their requested direction; never clone authored slide content.
+- **MUST:** Do not place essential content only in a slide that users cannot reach without waiting for automatic rotation.
+
+## Common mistakes
+
+- **Avoid:** Using Tabs for decorative dots, enabling autoplay without a stop control, reusing SwipeableItem, or adding custom timers and aria-hidden logic around Carousel. **Instead:** Use Carousel's optional grouped Picker, complete autoplay controls, and Atom-owned state, pause, scrolling, and inactive-slide contract.
+
+## Validation checklist
+
+- Verify controlled and uncontrolled selection, Previous/Next boundaries, last-to-first forward motion, first-to-last backward motion, picker selection, native touch scrolling, LTR and RTL, and external value changes.
+- Verify autoplay timing, focus stop without automatic restart, temporary hover and document-visibility pause, visible rotation control, live-region mode, inactive inert state, labels, and reduced-motion handling in the styled layer.
+
+## Related guidance
+
+- `tabs`
+- `swipeable-item`
+- `pagination`
+- `scroll-area`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "carousel",
+  "name": "Carousel",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Coordinate one-active-slide content rotation, optional automatic playback, direct selection, native swipe scrolling, and accessible inactive-slide semantics.",
+  "useWhen": [
+    "A small sequence of authored content should occupy one viewport and support previous, next, direct, touch, or optional timed selection."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "All items should remain visible, named document panels are selected, or a row reveals actions.",
+      "useInstead": "ordinary layout or scrolling, Tabs, or SwipeableItem"
+    }
+  ],
+  "composition": [
+    "Compose Root, Viewport, Track, and uniquely valued Slide parts; add Previous, Next, Picker with PickerItem, and RotationControl only when the experience needs those controls."
+  ],
+  "rules": [
+    {
+      "id": "carousel-initial-value",
+      "level": "must",
+      "statement": "Provide value or defaultValue matching one Slide and give every Slide a short unique accessible label."
+    },
+    {
+      "id": "carousel-autoplay-controls",
+      "level": "must",
+      "statement": "When automatic rotation is enabled, include visible RotationControl, Previous, and Next controls; Picker controls remain optional."
+    },
+    {
+      "id": "carousel-small-picker",
+      "level": "should",
+      "statement": "Keep grouped PickerItem controls to a small set because each native picker button is a tab stop."
+    },
+    {
+      "id": "carousel-layout-owner",
+      "level": "must",
+      "statement": "Supply viewport overflow, one-slide track geometry, and scroll snap in the styled layer; do not replace Atom selection, pause, or inactive semantics."
+    },
+    {
+      "id": "carousel-initial-motion-gate",
+      "level": "must",
+      "statement": "Keep styled viewport motion instant until Root exposes data-initialized, then enable the ordinary motion recipe so SSR hydration cannot start a competing native snap animation."
+    },
+    {
+      "id": "carousel-directional-loop-layout",
+      "level": "must",
+      "statement": "Style carousel-loop-boundary spacers and data-loop-position Slides as one-viewport boundary positions so Next and Previous preserve their requested direction; never clone authored slide content."
+    },
+    {
+      "id": "carousel-content-access",
+      "level": "must",
+      "statement": "Do not place essential content only in a slide that users cannot reach without waiting for automatic rotation."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Tabs for decorative dots, enabling autoplay without a stop control, reusing SwipeableItem, or adding custom timers and aria-hidden logic around Carousel.",
+      "correction": "Use Carousel's optional grouped Picker, complete autoplay controls, and Atom-owned state, pause, scrolling, and inactive-slide contract."
+    }
+  ],
+  "validation": [
+    "Verify controlled and uncontrolled selection, Previous/Next boundaries, last-to-first forward motion, first-to-last backward motion, picker selection, native touch scrolling, LTR and RTL, and external value changes.",
+    "Verify autoplay timing, focus stop without automatic restart, temporary hover and document-visibility pause, visible rotation control, live-region mode, inactive inert state, labels, and reduced-motion handling in the styled layer."
+  ],
+  "related": [
+    "tabs",
+    "swipeable-item",
+    "pagination",
+    "scroll-area"
+  ]
+}
+```

package/public/packages/atom/0.24.0/components/checkbox-group.txt

@@ -0,0 +1,118 @@
+# CheckboxGroup
+
+Source: @flowstack-ui/atom@0.24.0
+Kind: component
+ID: checkbox-group
+
+# CheckboxGroup agent guide
+
+## Purpose
+
+Manage a named set of independent checkbox choices with multi-value state, group validation, form submission, structured item relationships, and deterministic select-all behavior.
+
+## Use when
+
+- A user may select any number of related form choices and the choices share naming, state, validation, or submission behavior.
+
+## Choose something else when
+
+- There is one yes-or-no choice, exactly one option must be chosen, or the controls represent pressed commands instead of form choices. Use Checkbox, RadioGroup, or ToggleGroup.
+
+## Required composition
+
+- Give Root an accessible group name and compose uniquely valued Item parts. Plain Item children may name concise options; use ItemLabel and ItemDescription for structured relationships. Add Parent only with an explicit complete allValues set, and use a native fieldset and legend when a visible legend is required.
+
+## Rules
+
+- **MUST:** Give Root a concise accessible name with native ARIA or an inherited Fieldset Legend; do not use unsupported aria-required on role=group.
+- **MUST:** Give every Item a stable unique value and keep controlled value arrays synchronized through onValueChange; use name and form when the checked values must submit.
+- **MUST:** Render Parent only when Root allValues explicitly names the complete currently selectable set; omit disabled values while disabled and preserve selected values outside that declared set.
+- **MUST:** Use plain children as an Item name or pair one ItemLabel and optional ItemDescription; preserve native aria-label, aria-labelledby, and aria-describedby precedence.
+- **MUST:** Preserve disabled, read-only, invalid, and required behavior, including one-or-more group validity, first-enabled validation focus, form reset, and hidden per-item submission inputs.
+
+## Common mistakes
+
+- **Avoid:** Treating required as every checkbox being required, computing Parent from only mounted or selected values, or using CheckboxGroup for exclusive or pressed-button choices. **Instead:** Required means at least one selected; declare Parent's full selectable set with allValues and choose RadioGroup or ToggleGroup for different interaction models.
+
+## Validation checklist
+
+- Verify controlled and uncontrolled arrays, unique values, independent Enter and Space toggling, disabled and read-only items, group and item naming, structured descriptions, orientation metadata, and asChild/render prop and ref merging.
+- Verify named form submission, group-level required validity with and without a name, inline and native validation, first-enabled focus, Fieldset integration, reset, Parent unchecked/mixed/checked transitions, disabled-value exclusion, and preservation of outside values.
+
+## Related guidance
+
+- `checkbox`
+- `radio-group`
+- `toggle-group`
+- `fieldset`
+- `form`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "checkbox-group",
+  "name": "CheckboxGroup",
+  "package": "@flowstack-ui/atom",
+  "layer": "atom",
+  "kind": "component",
+  "purpose": "Manage a named set of independent checkbox choices with multi-value state, group validation, form submission, structured item relationships, and deterministic select-all behavior.",
+  "useWhen": [
+    "A user may select any number of related form choices and the choices share naming, state, validation, or submission behavior."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "There is one yes-or-no choice, exactly one option must be chosen, or the controls represent pressed commands instead of form choices.",
+      "useInstead": "Checkbox, RadioGroup, or ToggleGroup"
+    }
+  ],
+  "composition": [
+    "Give Root an accessible group name and compose uniquely valued Item parts. Plain Item children may name concise options; use ItemLabel and ItemDescription for structured relationships. Add Parent only with an explicit complete allValues set, and use a native fieldset and legend when a visible legend is required."
+  ],
+  "rules": [
+    {
+      "id": "checkbox-group-name",
+      "level": "must",
+      "statement": "Give Root a concise accessible name with native ARIA or an inherited Fieldset Legend; do not use unsupported aria-required on role=group."
+    },
+    {
+      "id": "checkbox-group-values",
+      "level": "must",
+      "statement": "Give every Item a stable unique value and keep controlled value arrays synchronized through onValueChange; use name and form when the checked values must submit."
+    },
+    {
+      "id": "checkbox-group-parent",
+      "level": "must",
+      "statement": "Render Parent only when Root allValues explicitly names the complete currently selectable set; omit disabled values while disabled and preserve selected values outside that declared set."
+    },
+    {
+      "id": "checkbox-group-labeling",
+      "level": "must",
+      "statement": "Use plain children as an Item name or pair one ItemLabel and optional ItemDescription; preserve native aria-label, aria-labelledby, and aria-describedby precedence."
+    },
+    {
+      "id": "checkbox-group-state",
+      "level": "must",
+      "statement": "Preserve disabled, read-only, invalid, and required behavior, including one-or-more group validity, first-enabled validation focus, form reset, and hidden per-item submission inputs."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Treating required as every checkbox being required, computing Parent from only mounted or selected values, or using CheckboxGroup for exclusive or pressed-button choices.",
+      "correction": "Required means at least one selected; declare Parent's full selectable set with allValues and choose RadioGroup or ToggleGroup for different interaction models."
+    }
+  ],
+  "validation": [
+    "Verify controlled and uncontrolled arrays, unique values, independent Enter and Space toggling, disabled and read-only items, group and item naming, structured descriptions, orientation metadata, and asChild/render prop and ref merging.",
+    "Verify named form submission, group-level required validity with and without a name, inline and native validation, first-enabled focus, Fieldset integration, reset, Parent unchecked/mixed/checked transitions, disabled-value exclusion, and preservation of outside values."
+  ],
+  "related": [
+    "checkbox",
+    "radio-group",
+    "toggle-group",
+    "fieldset",
+    "form"
+  ]
+}
+```