@d4gger/design-system 2.7.0

package/dist/docs/checkbox-cards.md

@@ -0,0 +1,352 @@
+---
+title: CheckboxCards
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/checkboxCards/CheckboxCards.tsx
+css_path: packages/d4gger-design-system/src/styles/components/checkbox-cards.css
+props_path: packages/d4gger-design-system/src/components/checkboxCards/checkboxCards.props.ts
+test_path: packages/d4gger-design-system/src/test/components/CheckboxCards.test.tsx
+demo_path: apps/playground/app/page.tsx
+depends_on:
+  - Checkbox (Radix `@radix-ui/react-checkbox`; the `Item` slot wraps `CheckboxPrimitive.Root` and is the source of the `data-state='checked'` attribute)
+  - Card (token-aligned surface; the `Item` reuses the `dsx-card` surface tokens through the `baseCard.css` import)
+  - Icon (lucide-react `check`; the default `Indicator` glyph)
+  - "@radix-ui/react-slot" (enables `asChild` on Root, Item, and Indicator)
+---
+
+# CheckboxCards
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A card-style multi-select cluster. Each option is a tappable card that toggles a hidden checkbox, with an inline `Indicator` showing the checked state.
+
+## Anatomy & slots
+
+**Parent:** `CheckboxCards` (alias of `CheckboxCardsRoot`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `CheckboxCards.Root` (alias `CheckboxCards`) | `<div>` (or `Slot` host) | `dsx-checkbox-cards` + `role="group"` | Layout host. Owns `data-orientation`, `data-size`, `data-variant`, `data-accent-color`. |
+| `CheckboxCards.Item` | `<div>` rendered through `CheckboxPrimitive.Root` via `asChild` | `dsx-checkbox-cards__item` | The selectable card. Carries `data-state='checked' \| 'unchecked' \| 'indeterminate'` from Radix. |
+| `CheckboxCards.Indicator` | `<span>` rendered through `CheckboxPrimitive.Indicator` | `dsx-checkbox-cards__indicator` | Renders only when the parent Item is checked. Default content is the `check` Icon. |
+
+The Item is a Radix Checkbox host, so the checked, unchecked, and indeterminate states come from Radix and are exposed to assistive tech through the checkbox's intrinsic accessibility contract.
+
+## Props contract
+
+### `CheckboxCards.Root` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | no | Flex direction of the cluster. Drives `data-orientation` and the matching CSS rules. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Item padding, gap, and corner radius. Drives `data-size` on the root and the size-specific CSS overrides on the items. | no |
+| `variant` | `'solid' \| 'soft' \| 'surface' \| 'outline'` | `'soft'` | no | Visual treatment. Drives `data-variant` on the root. The CSS does not currently consume `data-variant`; see Anomalies. | no |
+| `color` | `string` | `undefined` | no | Free-form accent override. Written to `data-accent-color` on the root for CSS hooks. The prop def has no enum values, so any string is accepted. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | `CheckboxCards.Item` and `CheckboxCards.Indicator` elements. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-checkbox-cards`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Inline style forwarded to the root. | no |
+
+The Root also accepts every `React.HTMLAttributes<HTMLDivElement>` key (omitting the conflicting `color` attribute) via `Omit<React.HTMLAttributes<HTMLDivElement>, 'color'>`.
+
+### `CheckboxCards.Item` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `string` | `undefined` | yes (Radix) | The Radix Checkbox value. Required by `CheckboxPrimitive.Root` for form participation. | no |
+| `checked` | `boolean \| 'indeterminate'` | `undefined` | no | Controlled checked state. When set, `onCheckedChange` is the only path to update it. | no |
+| `defaultChecked` | `boolean \| 'indeterminate'` | `undefined` | no | Initial value for the uncontrolled mode. | no |
+| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` | `undefined` | no | Called when the user toggles the item. | no |
+| `disabled` | `boolean` | `false` | no | Disables the item. Forwarded to Radix. | no |
+| `name` | `string` | `undefined` | no | Form name. Forwarded to Radix for native form participation. | no |
+| `required` | `boolean` | `false` | no | Form required marker. Forwarded to Radix. | no |
+| `asChild` | `boolean` | `false` | no | Renders the Item host through `Slot`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-checkbox-cards__item`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Inline style forwarded to the Item host. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Card content. The `Indicator` is usually rendered alongside the content. | no |
+
+The Item also accepts every `React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>` except `asChild` (which the component re-declares).
+
+### `CheckboxCards.Indicator` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the Indicator host through `Slot`. | no |
+| `children` | `React.ReactNode` | the `check` Icon | no | Indicator content. The default is `Icon name="check" size="md"` with a `var(--dsx-icon-stroke-width-strong, 2.25)` stroke. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-checkbox-cards__indicator`. | no |
+| `forceMount` | `boolean` | `undefined` | no | Radix escape hatch to force the indicator to mount even when unchecked. | no |
+
+The Indicator also accepts every `React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Indicator>` (including `forceMount`).
+
+Rules that apply to this row:
+
+- The Item's `value` is mandatory for form participation; the runtime does not supply a default.
+- `asChild` is the only polymorphic infra. It is exposed on Root, Item, and Indicator.
+- The `color` prop def is typed as `PropDef<string>` with an empty enum, so any string passes through. The CSS does not currently consume `data-accent-color`; see Anomalies.
+
+## CSS class contract
+
+**Root class:** `dsx-checkbox-cards`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-orientation` | `vertical`, `horizontal` | `.dsx-checkbox-cards[data-orientation='vertical']`, `.dsx-checkbox-cards[data-orientation='horizontal']` (flex direction) | `checkbox-cards.css` |
+| `data-size` | `sm`, `md`, `lg` | `.dsx-checkbox-cards[data-size='sm']`, `.dsx-checkbox-cards[data-size='lg']` (gap overrides) plus per-item padding and radius overrides | `checkbox-cards.css` |
+| `data-variant` | `solid`, `soft`, `surface`, `outline` | `.dsx-checkbox-cards[data-variant='X'] .dsx-checkbox-cards__item` sets the resting background/border per variant; `solid` also flips text to `--dsx-color-on-primary`. A per-variant `[data-state='checked']` override (soft/surface/outline) guarantees the accent border + tint always wins over the resting variant style. See FIXED 2026-07-03 note below. | `checkbox-cards.css` |
+| `data-accent-color` | `string` | No selector reads this attribute directly, but it does not need one: `[data-accent-color='X']` in `tokens.css` rescopes `--dsx-color-primary` (and related aliases) on the element that carries it, and every color this component paints is `var(--dsx-color-primary)`-derived, so the override cascades to items via ordinary CSS custom-property inheritance. | `checkbox-cards.css` / `tokens.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `CheckboxCards.Root` | `dsx-checkbox-cards` | `checkbox-cards.css` |
+| `CheckboxCards.Item` | `dsx-checkbox-cards__item` | `checkbox-cards.css` |
+| `CheckboxCards.Indicator` | `dsx-checkbox-cards__indicator` | `checkbox-cards.css` |
+
+**Data attributes from Radix (visual hooks):**
+
+| Element | Attribute | Allowed values | Class hook | CSS file |
+|---|---|---|---|---|
+| Item | `data-state` | `checked`, `unchecked`, `indeterminate` | `.dsx-checkbox-cards__item[data-state='checked']` (primary border + ghost fill) | `checkbox-cards.css` |
+| Item | `data-disabled` | (presence) | `.dsx-checkbox-cards__item[data-disabled]` (cursor + opacity) | `checkbox-cards.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`. Orientation, size, and variant are single-value only.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- The Item transitions `background-color`, `border-color`, and `box-shadow` against `var(--dsx-motion-duration-fast, 150ms)` and `var(--dsx-motion-easing-standard, ease)`.
+- A `@media (prefers-reduced-motion: reduce)` block sets the Item's transition to `none`.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Root gap (default) | `var(--dsx-space-sm)` | Gap between items. |
+| Root gap (`sm`) | `var(--dsx-space-xs)` | Tighter cluster. |
+| Root gap (`lg`) | `var(--dsx-space-md)` | Looser cluster. |
+| Item padding (default) | `var(--dsx-space-md)` | Inner gutter. |
+| Item padding (`sm`) | `var(--dsx-space-sm)` | Small control. |
+| Item padding (`lg`) | `var(--dsx-space-lg)` | Large control. |
+| Item gap | `var(--dsx-space-sm)` | Gap between content and indicator. |
+| Item gap (`sm`) | `var(--dsx-space-xs)` | Small control. |
+| Item gap (`lg`) | `var(--dsx-space-md)` | Large control. |
+| Item radius (default) | `var(--dsx-rounded-lg)` | Card corner radius. |
+| Item radius (`sm`) | `var(--dsx-rounded-md)` | Small control. |
+| Item radius (`lg`) | `var(--dsx-rounded-xl)` | Large control. |
+| Item border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline-variant)` | Resting edge. |
+| Item fill | `var(--dsx-color-surface)` | Resting surface. |
+| Item text | `var(--dsx-color-on-surface)` | Resting text. |
+| Item hover fill | `var(--dsx-effect-hover-ghost)` | Hover surface. |
+| Item hover border | `var(--dsx-color-outline)` | Hover edge. |
+| Item focus ring | `var(--dsx-shadow-focus-ring)` | Focus state. |
+| Item checked border | `var(--dsx-color-primary)` | Active edge. |
+| Item checked fill | `var(--dsx-color-primary-ghost)` with `color-mix` fallback at `8%` | Active surface. |
+| Item disabled cursor | `not-allowed` (raw) | Disabled cursor. |
+| Item disabled opacity | `var(--dsx-opacity-disabled)` | Disabled fade. |
+| Indicator color | `currentColor` | Inherits from item text. |
+| Motion | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Item transitions. |
+
+Rules:
+
+- Tokens come from `DESIGN.md` and the generated `tokens.css`.
+- `--dsx-color-primary-ghost` is a relative-color token; the CSS supplies a `color-mix(in srgb, var(--dsx-color-primary) 8%, transparent)` fallback so the rule resolves even when the alias is not generated.
+- The CSS file no longer imports `../../_internal/baseCard.css`; the import only ever matched `.dsx-card` and `.dsx-alert` selectors and was a no-op for `CheckboxCards`. Removed 2026-07-03 (see Anomalies).
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Item background, border, and box-shadow | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Hover, focus, and checked transitions | `none`. Declared in a `@media (prefers-reduced-motion: reduce)` block. |
+
+Rules:
+
+- This row does not import `MOTION_TRANSITIONS` from `src/_internal/motion.ts`. All motion is CSS-only.
+- A future promotion that uses framer-motion should pick a preset from `MOTION_TRANSITIONS` and gate it with `usePrefersReducedMotion`.
+
+## Accessibility
+
+**Roles:**
+
+- `CheckboxCards.Root` is a `role="group"`. Consumers can supply `aria-label` or `aria-labelledby` to name the group.
+- `CheckboxCards.Item` is a Radix `CheckboxPrimitive.Root` and exposes the implicit `checkbox` role. The native checkbox semantics cover name, state, and value.
+- `CheckboxCards.Indicator` does not declare a role; it is a visual presentation of the checked state. Radix keeps it mounted only when the parent is checked.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to / from the next / previous focusable Item. |
+| `Space` | Toggles the focused Item. |
+| `Enter` | The native checkbox does not toggle on Enter; the user activates with `Space`. |
+| Arrow keys | The composite does not implement arrow-key navigation between Items. Wrap in a `CheckboxGroup` or add app-level roving tabindex if the use case requires arrow keys. |
+
+**Focus:**
+
+- Visible focus ring is owned by `.dsx-checkbox-cards__item:focus-visible` via `box-shadow: var(--dsx-shadow-focus-ring)`. The inner element is `outline: none`.
+
+**Reduced motion:**
+
+- Item transitions collapse to `none` when `prefers-reduced-motion: reduce` matches.
+
+**Color and meaning:**
+
+- The checked state is communicated by both the `data-state='checked'` attribute (read by assistive tech) and the visual border + fill change. Color is not the only signal.
+- The disabled state is communicated by both `data-disabled` and the visual cursor + opacity change.
+
+**Naming:**
+
+- The Root has no implicit accessible name. Consumers must supply `aria-label` or `aria-labelledby` to identify the cluster.
+- Each Item's accessible name comes from its child content. There is no built-in label slot.
+
+## Playground demo spec
+
+The demo file at `demo_path` exposes the component to the playground. The playground lives at `apps/playground/app/` (Next.js app router, no per-component routes today). The `demo_path` recorded here is the current playground root; the spec assumes a single shared page that renders all components. Per-component routes are an aspirational target and not yet present in the repo.
+
+**Default story:**
+
+- Renders `CheckboxCards` with two `CheckboxCards.Item` children, each carrying a label and a `CheckboxCards.Indicator`. Asserts the root class is `dsx-checkbox-cards` and the root has `role="group"`.
+
+**Variant story** (one per orientation, size, and variant):
+
+- Renders with `orientation="vertical"` and `orientation="horizontal"`. Asserts the matching `data-orientation` attribute and the flex direction.
+- Renders with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute and item padding overrides.
+- Renders with `variant="solid"`, `variant="soft"`, `variant="surface"`, and `variant="outline"`. Asserts the matching `data-variant` attribute (the CSS does not currently consume it; see Anomalies).
+
+**Composition story** (one per slot):
+
+- Renders the full slot hierarchy: `CheckboxCards` > `CheckboxCards.Item` × 3, each with a `CheckboxCards.Indicator`. Asserts each Item carries `dsx-checkbox-cards__item` and the indicator only renders when the item is checked.
+
+**State story:**
+
+- Renders an Item and clicks it. Asserts `data-state="checked"` and the indicator mounts with the `check` Icon.
+- Renders an Item with `disabled`. Asserts the cursor is `not-allowed` and the item has `data-disabled`.
+- Renders an Item with `defaultChecked`. Asserts the initial state is `checked`.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the checked item border tracks `data-accent-color` (the CSS does not currently consume it; see Anomalies).
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default CheckboxCards. Asserts the group has an accessible name and each Item is announced as a checkbox.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `orientation` | select | `vertical` |
+| `size` | select | `md` |
+| `variant` | select | `soft` |
+| `color` | text | (empty) |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Checkbox` (Radix `@radix-ui/react-checkbox`): the `Item` slot wraps `CheckboxPrimitive.Root` and `CheckboxPrimitive.Indicator`. The `data-state` and disabled semantics come from Radix.
+- `Card`: the `Item` reuses the `dsx-card` surface tokens through the `baseCard.css` import. The TSX does not import the `Card` component.
+- `Icon` (lucide-react `check`): renders the default `Indicator` glyph.
+- `@radix-ui/react-slot`: enables `asChild` on Root, Item, and Indicator.
+
+**Used by:**
+
+- Multi-select choice clusters where each option needs more visual weight than a plain checkbox row. Pairs with `Field` for label, description, and error wiring at the app level. No DS component currently wraps `CheckboxCards`.
+
+**State boundaries:**
+
+- Owned by CheckboxCards: the cluster layout, the orientation, size, and variant attributes, and the visual checked, hover, and focus state.
+- Owned by the consumer: the per-item `checked`, `defaultChecked`, `onCheckedChange`, `value`, `name`, `required`, and `disabled` props. The composite does not lift the selection; the form state lives at the app level.
+
+**Boundary rules:**
+
+- App-owned data: the selection model (which items are checked), the form integration, and the surrounding field context.
+- DS-owned visuals: token bindings, the `dsx-checkbox-cards` and slot classes, the `data-orientation`, `data-size`, `data-variant`, and `data-accent-color` attributes, and the default `check` Icon glyph.
+- The component does not own a `Field` integration. Wrap in `Field.Root` (or `CheckboxGroup`) at the app level for label, description, and error wiring.
+
+**Anomalies** (open items that this spec flags):
+
+1. **FIXED 2026-07-03 — `variant` had a real CSS consumer, but it silently ate the checked state.** The stale claim that "`variant` has no CSS consumer" was wrong; `checkbox-cards.css` already defined `[data-variant='X']` rules. The actual bug: those rules (specificity `0,3,0`) unconditionally beat `.dsx-checkbox-cards__item[data-state='checked']` (specificity `0,2,0`), so for every variant except `solid` the checked accent border/tint never rendered. Fixed with a single `:where([data-variant='soft'], [data-variant='surface'], [data-variant='outline'])` override that ties the variant rules' specificity (`0,3,0`, since `:where()` contributes zero) and wins on source order, rather than escalating the file's max specificity further. `solid` is untouched by design: it is already fully filled with the accent color at rest.
+2. **FIXED 2026-07-03 — `soft` variant's `border-color: transparent` washed cards into the page background.** Removed the `border-color: transparent` override so `soft` (the default variant) falls back to the base item's `var(--dsx-color-outline-variant)` border while keeping its tinted background.
+3. **FIXED 2026-07-03 — `data-accent-color` "no CSS consumer" claim was misleading.** No selector in this file reads `[data-accent-color]` directly, and none needs to: `tokens.css` defines `[data-accent-color='silver']` / `[data-accent-color='bronze']` blocks that rescope `--dsx-color-primary` (and its aliases) wherever the attribute appears in the DOM, and every color this component paints is `var(--dsx-color-primary)`-derived, so it inherits the rescoped value automatically. The check-icon indicator already used `currentColor`, so it was never the bottleneck; the real bottleneck was anomaly #1 above (no visible checked accent border to compare between colors in the `soft` default).
+4. **FIXED 2026-07-03 — `baseCard.css` import was a no-op.** Removed. It only ever targeted `.dsx-card` and `.dsx-alert`; extending it to also match `.dsx-checkbox-cards__item` was considered and rejected because `baseCard.css`'s own hover/selected recipe differs from this component's (and uses `data-selected`/`aria-selected`, not Radix's `data-state='checked'`), so extending it would have re-created a second competing source of truth for the same states this file already owns outright.
+5. **`color` prop is typed as a free-form string.** The prop def is `PropDef<string>` with an empty enum, so any string passes through without a default. The downstream `data-accent-color` value is not validated against the `Theme` accent enum. Not addressed this batch.
+6. **`role="group"` is hard-coded.** The Root renders `role="group"` regardless of context. If the cluster is used inside a `Field` that already provides a group role, the duplicate role is harmless but worth noting. Not addressed this batch.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. Keep this section when the component has a published Penpot asset, or when the spec needs to call out a visual decision the package does not encode. Skip the section when the component is utility or layout-primitive; the package code is the only authority.
+
+The package does not yet publish a Penpot asset for CheckboxCards. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / CheckboxCards`.
+- **Dimensions**: `auto × auto` (cluster width and height driven by item count and item size).
+- **Layout**: `Flex` (column default, row when `orientation="horizontal"`).
+- **Sizing**: `horizontalSizing = 'auto'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board: CheckboxCards>
+  └── <Frame: Item 1>
+  │   ├── <Frame: indicator (when checked)>
+  │   └── <Text: item label>
+  └── <Frame: Item 2>
+      ├── <Frame: indicator (when checked)>
+      └── <Text: item label>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Item | fill | `--dsx-color-surface` | Color | `fills` |
+| Item | stroke | `--dsx-color-outline-variant` | Color | `strokes` |
+| Item | radius | `--dsx-rounded-lg` | Radius | `radius` |
+| Item (hover) | fill | `--dsx-effect-hover-ghost` | Color | `fills` (state) |
+| Item (hover) | stroke | `--dsx-color-outline` | Color | `strokes` (state) |
+| Item (focus) | shadow | `--dsx-shadow-focus-ring` | Effect | `shadow` (state) |
+| Item (checked) | stroke | `--dsx-color-primary` | Color | `strokes` (state) |
+| Item (checked) | fill | `--dsx-color-primary-ghost` | Color | `fills` (state) |
+| Item (disabled) | opacity | `--dsx-opacity-disabled` | Effect | `opacity` (state) |
+| Indicator | text | `currentColor` | Color | `fills` |
+
+### State transformations
+
+| State | Item fill | Item stroke | Indicator visibility |
+|---|---|---|---|
+| `default` | `--dsx-color-surface` | `--dsx-color-outline-variant` | hidden |
+| `hover` | `--dsx-effect-hover-ghost` | `--dsx-color-outline` | hidden |
+| `focus` | `--dsx-color-surface` | `--dsx-color-outline-variant` | hidden |
+| `checked` | `--dsx-color-primary-ghost` | `--dsx-color-primary` | visible (check glyph) |
+| `disabled` | `--dsx-color-surface` (faded) | `--dsx-color-outline-variant` | hidden |
+
+### Variant model
+
+- `orientation`: `vertical`, `horizontal`. Default `vertical`.
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `variant`: `solid`, `soft`, `surface`, `outline`. Default `soft`. (CSS consumer pending; see Anomalies.)
+- Total members for the visual matrix: 2 × 3 = 6 today; the variant axis is reserved for a future promotion.
+
+### Validation checklist
+
+- [ ] Token bindings resolve at the values `DESIGN.md` describes.
+- [ ] Component is promoted to Main Component under `Components`.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
+- [ ] Checked state is communicated by both `data-state` and the visual border + fill change.
+- [ ] The Indicator default glyph is the `check` Icon; do not treat the glyph as themable in Penpot.
+- [ ] When the `variant` and `data-accent-color` CSS consumers land, re-run the spec QA and re-validate the Penpot recipe against the new CSS.

package/dist/docs/checkbox-group.md

@@ -0,0 +1,229 @@
+---
+title: CheckboxGroup
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/checkboxGroup/CheckboxGroup.tsx
+css_path: packages/d4gger-design-system/src/styles/components/checkbox-group.css
+props_path: packages/d4gger-design-system/src/components/checkboxGroup/checkboxGroup.props.ts
+test_path: packages/d4gger-design-system/src/test/components/CheckboxGroup.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/forms.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Checkbox
+  - Field
+  - Icon
+---
+
+# CheckboxGroup
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A managed multi-select group of checkboxes with an optional master checkbox that toggles every registered item. The group owns value state (controlled or uncontrolled), exposes a checked/indeterminate/unchecked `data-state` on the root, and renders a master checkbox inside `CheckboxGroup.Label` that selects all when partial and clears all when fully checked.
+
+## Anatomy & slots
+
+**Parent:** `CheckboxGroup` (alias of `CheckboxGroup.Root`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `CheckboxGroup.Root` | `<div role="group">` | context provider + host | Owns the value state, the master/indeterminate/unchecked derivation, and the `data-size` / `data-accent-color` / `data-state` attributes. |
+| `CheckboxGroup.Label` | `<label>` | master checkbox + label text | Clicking the label toggles every registered item. Renders a `minus` icon when indeterminate and a `check` icon when fully checked. |
+| `CheckboxGroup.Item` | `<label>` | `CheckboxPrimitive.Root` + label text | Each item registers its value with the root on mount and unregisters on unmount. The item-control is a Radix `CheckboxPrimitive.Root` rendered as a child span. |
+
+## Props contract
+
+### `CheckboxGroup.Root` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `string[]` | `undefined` | no | Controlled value. When set, the group is controlled; `onValueChange` is the only path to update it. | no |
+| `defaultValue` | `string[]` | `[]` | no | Uncontrolled initial value. The root seeds `useState` with a `Set<string>` of this list. | no |
+| `onValueChange` | `(value: string[]) => void` | `undefined` | no | Called with the next value array on every item toggle. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Item-control and master checkbox size. Drives the `data-size` attribute and the master `dsx-checkbox-group__master` sizing. | no |
+| `color` | `string` | `undefined` | no | Accent color name forwarded as `data-accent-color`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | `CheckboxGroup.Label` and `CheckboxGroup.Item` children. | no |
+| Standard `<div>` props | `HTMLAttributes<HTMLDivElement>` | n/a | no | The interface omits `'color'` to avoid clashing with the accent `color` prop. Other `<div>` props are forwarded. | no |
+
+### `CheckboxGroup.Label` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the label host through `Slot`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Label text. Wraps the master checkbox plus the user-supplied text. | no |
+| Standard `<label>` props | `LabelHTMLAttributes<HTMLLabelElement>` | n/a | no | `htmlFor`, `id`, etc. | no |
+
+### `CheckboxGroup.Item` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `string` | — | yes | Unique value the item registers with the root. | no |
+| `onCheckedChange` | `(checked: boolean) => void` | `undefined` | no | Called with the next checked state when the item toggles. | no |
+| `asChild` | `boolean` | `false` | no | Renders the item host through `Slot`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Item label text. | no |
+| Standard `<label>` props | `LabelHTMLAttributes<HTMLLabelElement>` | n/a | no | Forwarded. The interface omits `'asChild'` from the base label props to avoid clashing. | no |
+
+Rules:
+
+- Item values must be unique inside the group. The `registerItem` callback stores values in a `Set<string>`; duplicates are deduped silently.
+- The master checkbox's `checked` is derived as `allValues.size > 0 && allValues.size === values.size`. It is `indeterminate` when at least one item is checked but not all, and `unchecked` when no item is checked.
+- The `Icon` used for the master indicator is `minus` when indeterminate and `check` when fully checked, with a stroke width of `var(--dsx-icon-stroke-width-strong, 2.25)`.
+
+## CSS class contract
+
+**Root class:** `dsx-checkbox-group`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-checkbox-group[data-size='sm']` row gap `var(--dsx-space-xs)`, `.dsx-checkbox-group[data-size='lg']` row gap `var(--dsx-space-md)` | `checkbox-group.css` |
+| `data-accent-color` | any string | inherited by item-control via cascade | `checkbox-group.css` |
+| `data-state` | `checked`, `indeterminate`, `unchecked` | n/a (root is informational; item-controls and master track their own `data-state`) | `checkbox-group.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `CheckboxGroup.Label` | `dsx-checkbox-group__label` | `checkbox-group.css` |
+| Master checkbox | `dsx-checkbox-group__master` | `checkbox-group.css` |
+| Master indicator | `dsx-checkbox-group__master-indicator` | `checkbox-group.css` |
+| `CheckboxGroup.Item` | `dsx-checkbox-group__item` | `checkbox-group.css` |
+| Item control | `dsx-checkbox-group__item-control` | `checkbox-group.css` |
+| Item indicator | `dsx-checkbox-group__item-indicator` | `checkbox-group.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size is single-value only.
+
+**Reduced motion:**
+
+- The master checkbox and the item-control transition `background-color` and `border-color` against `var(--dsx-motion-duration-fast, 150ms)` and `var(--dsx-motion-easing-standard, ease)`. Both transitions are disabled inside `@media (prefers-reduced-motion: reduce)`.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Root layout | `display: flex; flex-direction: column;` | Vertical stack. |
+| Root gap (default) | `var(--dsx-space-sm)` | Default row gap. |
+| Root gap (sm) | `var(--dsx-space-xs)` | Tighter row gap. |
+| Root gap (lg) | `var(--dsx-space-md)` | Looser row gap. |
+| Master/item width and height (default) | `var(--dsx-size-md)` | Default control size. |
+| Master/item width and height (sm) | `var(--dsx-size-sm)` | Small control. |
+| Master/item width and height (lg) | `var(--dsx-size-lg)` | Large control. |
+| Master/item radius | `var(--dsx-rounded-sm)` | Square-ish corners. |
+| Master/item border | `var(--dsx-border-width-md)` solid `var(--dsx-color-outline-variant)` | Resting edge. |
+| Master/item background | `var(--dsx-color-surface)` | Resting fill. |
+| Master/item text color | `var(--dsx-color-on-surface)` | Resting text. |
+| Master/item checked background and border | `var(--dsx-color-primary)` | Active fill and edge. |
+| Master/item checked text color | `var(--dsx-color-on-primary)` | Active text. |
+| Master/item focus ring | `var(--dsx-shadow-focus-ring)` | Focus indicator. |
+| Master/item transition | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Background and border transitions. |
+| Label typography | `var(--dsx-typography-label-medium-*)` | Master label ramp. |
+| Item typography | `var(--dsx-typography-body-medium-*)` | Item label ramp. |
+| Stroke width | `var(--dsx-icon-stroke-width-strong, 2.25)` | Master and item check stroke. |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Master and item-control background and border | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Background and border swap on state change | Disabled inside `@media (prefers-reduced-motion: reduce)`. |
+
+## Accessibility
+
+**Roles:**
+
+- The root is `<div role="group">`. The label is a native `<label>` element. Each item is a native `<label>` element with an inner Radix `CheckboxPrimitive.Root`.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus into and out of the group, then between the master checkbox and the item controls. |
+| `Space` | Toggles the focused master or item checkbox. |
+| `Enter` | Activates the focused master or item (the underlying Radix `CheckboxPrimitive.Root` accepts both). |
+
+**Focus:**
+
+- The master and item-control both rely on `:focus-visible` to draw the `var(--dsx-shadow-focus-ring)` focus ring. The item-control does not draw its own outline; the focus ring replaces it.
+
+**Reduced motion:**
+
+- The transitions in the master and item-control honor `prefers-reduced-motion: reduce` via the CSS media query and become `transition: none`.
+
+**Color and meaning:**
+
+- State is communicated by the icon (`check` for selected, `minus` for indeterminate, empty for unchecked) plus the background swap, not by color alone.
+
+**Naming:**
+
+- The root needs an `aria-label` or `aria-labelledby` to give the group an accessible name. Items should each have visible label text inside `CheckboxGroup.Item`.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `CheckboxGroup` with one item checked, no master label. Asserts the root class is `dsx-checkbox-group`, `data-size="md"`, and `data-state="checked"`.
+
+**Size story:**
+
+- Renders with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute and that the item-control size shrinks or grows.
+
+**State story:**
+
+- Renders with `defaultValue=[]`. Asserts `data-state="unchecked"`.
+- Renders with `defaultValue=['a']` (one of two items). Asserts `data-state="indeterminate"`.
+- Renders with `defaultValue=['a','b']` (all items). Asserts `data-state="checked"`.
+- Clicks an item label. Asserts `onValueChange` is called with the next value array.
+
+**Composition story:**
+
+- Renders a group with `CheckboxGroup.Label`, two `CheckboxGroup.Item` slots, and no master override. Asserts the master checkbox toggles every item when clicked.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the `data-accent-color` attribute is set on the root.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default group. Asserts the group has an accessible name and the items have label text.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `color` | text | (empty) |
+| `defaultValue` | text (CSV) | (empty) |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-checkbox`: the master checkbox and the per-item control. The root derives its `data-state` from the live `Set<string>` of selected values.
+- `@radix-ui/react-slot`: enables `asChild` on the root, label, and item hosts.
+- `Icon` (lucide-react `check`, `minus`): the master and item indicators.
+
+**Used by:**
+
+- Filter panels and settings rows where a group of yes/no choices needs a shared master toggle.
+- Form specs that need multi-select without writing their own `Set` management.
+
+**State boundaries:**
+
+- Owned by CheckboxGroup: the value `Set`, the `allValues` registration `Set`, the master checked/indeterminate/unchecked derivation, and the master toggle handler.
+- Owned by the consumer: the item values, the visible labels, the controlled/uncontrolled value, and the `onValueChange` callback. Consumers that need to call into `react-hook-form` wire `onValueChange` to the form.
+
+**Boundary rules:**
+
+- App-owned data: the values themselves and the onValueChange handler.
+- DS-owned visuals: the root, label, and item classes, the master and item indicator rendering, the `data-size` and `data-accent-color` attributes, and the `data-state` derivation.