@d4gger/design-system 2.7.0

package/dist/docs/radio-cards.md

@@ -0,0 +1,360 @@
+---
+title: RadioCards
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/radioCards/RadioCards.tsx
+css_path: packages/d4gger-design-system/src/styles/components/radio-cards.css
+props_path: packages/d4gger-design-system/src/components/radioCards/radioCards.props.ts
+test_path: packages/d4gger-design-system/src/test/components/RadioCards.test.tsx
+demo_path: apps/playground/app/page.tsx
+depends_on:
+  - RadioGroup (Radix `@radix-ui/react-radio-group`; the `Root` wraps `RadioGroupPrimitive.Root` and the `Item` wraps `RadioGroupPrimitive.Item`, the `data-state='checked'` attribute is the source of the visual selected state)
+  - Card (token-aligned surface; the `Item` reuses the `dsx-card` surface tokens through the `baseCard.css` import)
+  - "@radix-ui/react-slot" (enables `asChild` on Root, Item, and Indicator)
+---
+
+# RadioCards
+
+> 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 mutually exclusive choice cluster. Each option is a tappable card that selects a single value, with an inline `Indicator` showing the radio dot for the chosen option.
+
+## Anatomy & slots
+
+**Parent:** `RadioCards` (alias of `RadioCardsRoot`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `RadioCards.Root` (alias `RadioCards`) | `<div>` (or `Slot` host) wrapped in `RadioGroupPrimitive.Root` | `dsx-radio-cards` | Layout host. Owns `data-orientation`, `data-size`, `data-variant`, `data-accent-color`. |
+| `RadioCards.Item` | `<div>` rendered through `RadioGroupPrimitive.Item` via `asChild` | `dsx-radio-cards__item` | One option. Carries `data-state='checked' \| 'unchecked'` from Radix. |
+| `RadioCards.Indicator` | `<span>` rendered through `RadioGroupPrimitive.Indicator` | `dsx-radio-cards__indicator` | Renders only when the parent Item is selected. Default content is the `dsx-radio-cards__dot` span. |
+
+The Item is a Radix RadioGroup host, so the selection state, keyboard navigation, and form participation come from Radix.
+
+## Props contract
+
+### `RadioCards.Root` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `string` | `undefined` | no | Controlled selected value. When set, `onValueChange` is the only path to update it. | no |
+| `defaultValue` | `string` | `undefined` | no | Initial selected value for the uncontrolled mode. | no |
+| `onValueChange` | `(value: string) => void` | `undefined` | no | Called with the new selected value. | 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 |
+| `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. 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 | `RadioCards.Item` and `RadioCards.Indicator` elements. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-radio-cards`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Inline style forwarded to the root. | no |
+
+The Root also accepts every `React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>` key (omitting the conflicting `color` and `orientation` attributes, which the component re-declares) via `Omit<React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>, 'color'>`.
+
+### `RadioCards.Item` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `string` | (none) | yes | The Radix RadioGroup value. Required by `RadioGroupPrimitive.Item`; the runtime throws if missing. | no |
+| `disabled` | `boolean` | `false` | no | Disables the item. Forwarded to Radix. | no |
+| `asChild` | `boolean` | `false` | no | Renders the Item host through `Slot`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-radio-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 RadioGroupPrimitive.Item>` except `asChild` (which the component re-declares).
+
+### `RadioCards.Indicator` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the Indicator host through `Slot`. | no |
+| `children` | `React.ReactNode` | the radio dot span | no | Indicator content. The default is `<span class="dsx-radio-cards__dot" />`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-radio-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 RadioGroupPrimitive.Indicator>` (including `forceMount`).
+
+Rules that apply to this row:
+
+- The Item's `value` is mandatory for selection; 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-radio-cards`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-orientation` | `vertical`, `horizontal` | `.dsx-radio-cards[data-orientation='vertical']`, `.dsx-radio-cards[data-orientation='horizontal']` (flex direction) | `radio-cards.css` |
+| `data-size` | `sm`, `md`, `lg` | `.dsx-radio-cards[data-size='sm']`, `.dsx-radio-cards[data-size='lg']` (gap overrides) plus per-item padding and radius overrides | `radio-cards.css` |
+| `data-variant` | `solid`, `soft`, `surface`, `outline` | `.dsx-radio-cards[data-variant='X'] .dsx-radio-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. | `radio-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. | `radio-cards.css` / `tokens.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `RadioCards.Root` | `dsx-radio-cards` | `radio-cards.css` |
+| `RadioCards.Item` | `dsx-radio-cards__item` | `radio-cards.css` |
+| `RadioCards.Indicator` | `dsx-radio-cards__indicator` | `radio-cards.css` |
+| (radio dot, internal) | `dsx-radio-cards__dot` | `radio-cards.css` |
+
+**Data attributes from Radix (visual hooks):**
+
+| Element | Attribute | Allowed values | Class hook | CSS file |
+|---|---|---|---|---|
+| Item | `data-state` | `checked`, `unchecked` | `.dsx-radio-cards__item[data-state='checked']` (primary border + ghost fill) | `radio-cards.css` |
+| Item | `data-disabled` | (presence) | `.dsx-radio-cards__item[data-disabled]` (cursor + opacity) | `radio-cards.css` |
+| Dot | (inherits from parent Item) | n/a | `.dsx-radio-cards__item[data-state='checked'] .dsx-radio-cards__dot` (primary fill) | `radio-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. |
+| Dot size | `var(--dsx-space-sm)` square | Radio dot. |
+| Dot radius | `var(--dsx-rounded-full)` | Round dot. |
+| Dot fill | `var(--dsx-color-primary)`, or `var(--dsx-color-on-primary)` under `data-variant='solid'` | Active fill. The solid variant fills the whole card with `--dsx-color-primary`, so the dot swaps to the on-primary contrast color there or it disappears into the background. |
+| 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 `RadioCards`. 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:**
+
+- `RadioCards.Root` is a `role="radiogroup"`. Consumers can supply `aria-label` or `aria-labelledby` to name the group.
+- `RadioCards.Item` is a Radix `RadioGroupPrimitive.Item` and exposes the implicit `radio` role. The native radio semantics cover name, state, and value.
+- `RadioCards.Indicator` does not declare a role; it is a visual presentation of the selected state. Radix keeps it mounted only when the parent Item is selected.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus into and out of the radiogroup. |
+| `Arrow keys` | Radix RadioGroup implements roving focus between items. `↑` / `←` move to the previous focusable item; `↓` / `→` move to the next; focus wraps when `wrap` is enabled on the underlying RadioGroup. |
+| `Space` | Selects the focused item. |
+| `Enter` | The native radio does not select on Enter; the user activates with `Space`. |
+
+**Focus:**
+
+- Visible focus ring is owned by `.dsx-radio-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 selected state is communicated by both the `data-state='checked'` attribute (read by assistive tech) and the visual border + fill change plus the radio dot. 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 `RadioCards` with two `RadioCards.Item` children, each carrying a label and a `RadioCards.Indicator`. Asserts the root class is `dsx-radio-cards` and the root is a `radiogroup`.
+
+**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: `RadioCards` > `RadioCards.Item` × 3, each with a `RadioCards.Indicator`. Asserts each Item carries `dsx-radio-cards__item` and the indicator + dot only render when the item is selected.
+
+**State story:**
+
+- Renders three Items and clicks the second. Asserts `data-state="checked"` on the second item and `data-state="unchecked"` on the others.
+- Renders an Item with `disabled`. Asserts the cursor is `not-allowed` and the item has `data-disabled`.
+- Renders `RadioCards` with `defaultValue="b"` and three Items whose `value` is `"a" | "b" | "c"`. Asserts the `b` item starts 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 RadioCards. Asserts the group has an accessible name and each Item is announced as a radio.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `orientation` | select | `vertical` |
+| `size` | select | `md` |
+| `variant` | select | `soft` |
+| `color` | text | (empty) |
+| `asChild` | boolean | `false` |
+| `defaultValue` | text | (empty) |
+
+## Wiring notes
+
+**Composes from:**
+
+- `RadioGroup` (Radix `@radix-ui/react-radio-group`): the `Root` slot wraps `RadioGroupPrimitive.Root` and the `Item` slot wraps `RadioGroupPrimitive.Item`. The `data-state`, roving focus, and keyboard navigation 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.
+- `@radix-ui/react-slot`: enables `asChild` on Root, Item, and Indicator.
+
+**Used by:**
+
+- Mutually exclusive choice clusters where each option needs more visual weight than a plain radio row. Pairs with `Field` for label, description, and error wiring at the app level. No DS component currently wraps `RadioCards`.
+
+**State boundaries:**
+
+- Owned by RadioCards: the cluster layout, the orientation, size, and variant attributes, and the visual selected, hover, and focus state.
+- Owned by the consumer: the `value`, `defaultValue`, `onValueChange`, `name`, and `required` props, and the per-item `value` 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 item is selected), the form integration, and the surrounding field context.
+- DS-owned visuals: token bindings, the `dsx-radio-cards` and slot classes, the `data-orientation`, `data-size`, `data-variant`, and `data-accent-color` attributes, and the default radio dot.
+- The component does not own a `Field` integration. Wrap in `Field.Root` 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; `radio-cards.css` already defined `[data-variant='X']` rules. The actual bug: those rules (specificity `0,3,0`) unconditionally beat `.dsx-radio-cards__item[data-state='checked']` (specificity `0,2,0`), so for every variant except `solid` the checked accent border/tint never rendered — matching the visual-triage report of "only solid selection visible". 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, so there is no separate checked treatment to add.
+2. **FIXED 2026-07-03 — `soft` variant's `border-color: transparent` washed cards into the page background.** This was the literal cause of "no border at rest… full-width pale strips that wash into the page bg" in the visual triage. 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 — radio dot was a 0×0 element in every variant, not just invisible on `solid`.** `.dsx-radio-cards__dot` set `width`/`height` but never set `display`, so it defaulted to `display: inline` — and browsers ignore `width`/`height` on non-replaced inline elements entirely. The dot never occupied any space, in any variant, at any time; this is the real, literal explanation for "no radio indicator" in the original visual triage. Fixed by adding `display: block` to `.dsx-radio-cards__dot`. Separately, the dot was also hard-coded to `background: var(--dsx-color-primary)`, identical to the `solid` variant's own fill, so even after the display fix a checked `solid` item's dot would have been invisible against its own background. Added `.dsx-radio-cards[data-variant='solid'] .dsx-radio-cards__dot { background: var(--dsx-color-on-primary); }`, placed immediately after the base `.dsx-radio-cards__dot` rule (a redundant duplicate `[data-state='checked'] .dsx-radio-cards__dot` rule further down the file — same value as the base rule — was deleted; it was tying this override on specificity and winning by source order).
+4. **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 — including on an ancestor `Theme` wrapper — and every color this component paints is `var(--dsx-color-primary)`-derived, so it inherits the rescoped value automatically. The reason the amber/silver/bronze demo rows looked identical was anomaly #1 above: the checked accent border never rendered for the `soft` variant, so there was no accent-colored surface to compare between the three colors in the first place. Now that checked-state rendering is fixed, the three token-story rows show distinct hues.
+5. **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-radio-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.
+6. **`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.
+7. **`Root` does not forward `loop` semantics from the underlying RadioGroup.** When the consumer wants wrap-around arrow navigation, they need to set `wrap` on the underlying `RadioGroupPrimitive.Root` via the prop spread; the DS `Root` does not surface a `wrap` prop. 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 RadioCards. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / RadioCards`.
+- **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: RadioCards>
+  └── <Frame: Item 1>
+  │   ├── <Frame: indicator (when checked)>
+  │   │   └── <Shape: dot>
+  │   └── <Text: item label>
+  └── <Frame: Item 2>
+      ├── <Frame: indicator (when checked)>
+      │   └── <Shape: dot>
+      └── <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) |
+| Dot | fill | `--dsx-color-primary` | Color | `fills` |
+| Dot | radius | `--dsx-rounded-full` | Radius | `radius` |
+
+### State transformations
+
+| State | Item fill | Item stroke | Dot 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 |
+| `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.
+- [ ] Selected state is communicated by both `data-state` and the visual border + fill + dot.
+- [ ] The Indicator default is a span with the `dsx-radio-cards__dot` class; do not treat the dot as a separate component 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/radio-group.md

@@ -0,0 +1,235 @@
+---
+title: RadioGroup
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/radioGroup/RadioGroup.tsx
+css_path: packages/d4gger-design-system/src/styles/components/radio-group.css
+props_path: packages/d4gger-design-system/src/components/radioGroup/radioGroup.props.ts
+test_path: packages/d4gger-design-system/src/test/components/RadioGroup.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:
+  - "@radix-ui/react-radio-group"
+---
+
+# RadioGroup
+
+> 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 mutually exclusive selection cluster backed by `@radix-ui/react-radio-group`. Each item can be a bare radio control or a labelled option with a description, and the root supports size, variant, accent color, and high-contrast overrides that propagate to every item.
+
+## Anatomy & slots
+
+**Parent:** `RadioGroup` (alias of `RadioGroup.Root`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `RadioGroup` (Root) | `<div>` | `RadioGroupPrimitive.Root` host with class | The cluster container. Writes `data-size`, `data-variant`, `data-accent-color`, and `data-high-contrast`. |
+| `RadioGroupItem` | `<button>` (or `<label>` when `label` or `description` is set) | `RadioGroupPrimitive.Item` + indicator dot | The bare item is a `<button>` with an internal `Indicator` span and a `Dot` span. When the consumer passes `label` or `description`, the item wraps itself in a `<label class="dsx-radio-option">` with content and description blocks. |
+
+## Props contract
+
+### `RadioGroup` (Root) props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'solid' \| 'soft' \| 'outline'` | `'solid'` | no | Visual treatment. Drives `data-variant`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Root-level size token. Drives `data-size`. Item-level `size` overrides this per item. | no |
+| `orientation` | `'horizontal' \| 'vertical'` | `undefined` | no | Optional. Passed through to the Radix root. The CSS does not currently key off `data-orientation`; layout falls back to the `display: grid` flow. | no |
+| `color` | `string` | `undefined` | no | Accent color. Drives `data-accent-color`. | no |
+| `highContrast` | `boolean` | `false` | no | High-contrast treatment. Drives `data-high-contrast="true"` when `true`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. | no |
+| `value`, `defaultValue`, `onValueChange`, `name`, `required`, `disabled` | Radix `RadioGroupPrimitive.Root` props | n/a | no | Standard Radix controlled/uncontrolled state. Forwarded. | no |
+| `children` | `React.ReactNode` | `undefined` | no | `RadioGroupItem` children. | no |
+| Standard props | `ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>` | n/a | no | The interface omits `'color'` to avoid clashing with the accent `color` prop. Other props pass through. | no |
+
+### `RadioGroupItem` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `string` | — | yes | Unique value for this item. | no |
+| `size` | `'sm' \| 'md'` | `'md'` | no | Item-level size override. Drives the `dsx-radio-item--{size}` class. | no |
+| `label` | `ReactNode` | `undefined` | no | When set, the item wraps itself in a `<label class="dsx-radio-option">` and renders the label inside a `dsx-radio-option__label` span. | no |
+| `description` | `ReactNode` | `undefined` | no | When set, the item renders a `dsx-radio-option__description` span under the label. | no |
+| `asChild` | `boolean` | `false` | no | Renders the item host through `Slot`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Item children. With `asChild` the children render through `Slottable`. | no |
+| Standard props | `ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>` | n/a | no | Forwarded. | no |
+
+Rules:
+
+- The indicator is a single `dsx-radio-item__indicator` span wrapping a `dsx-radio-item__dot` span. The dot is the only visible "selected" mark; the item border swap to `var(--dsx-color-primary)` on `data-state='checked'` carries the rest of the visual.
+- The item-control's host element is `<button>` by default. The CSS does not currently key off `data-size`; item-level sizing is driven by the `dsx-radio-item--sm` and `dsx-radio-item--md` modifier classes.
+
+## CSS class contract
+
+**Root class:** `dsx-radio-group`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | n/a (no size-specific root CSS today) | `radio-group.css` |
+| `data-variant` | `solid`, `soft`, `outline` | n/a (no variant-specific root CSS today) | `radio-group.css` |
+| `data-accent-color` | any string | inherited by item border via cascade | `radio-group.css` |
+| `data-high-contrast` | `true` (or absent) | n/a (no high-contrast root CSS today) | `radio-group.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `RadioGroupItem` (host) | `dsx-radio-item` | `radio-group.css` |
+| `RadioGroupItem` (size sm) | `dsx-radio-item--sm` | `radio-group.css` |
+| `RadioGroupItem` (size md) | `dsx-radio-item--md` | `radio-group.css` |
+| Item indicator | `dsx-radio-item__indicator` | `radio-group.css` |
+| Item dot | `dsx-radio-item__dot` | `radio-group.css` |
+| Option wrapper | `dsx-radio-option` | `radio-group.css` |
+| Option content | `dsx-radio-option__content` | `radio-group.css` |
+| Option label | `dsx-radio-option__label` | `radio-group.css` |
+| Option description | `dsx-radio-option__description` | `radio-group.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size, variant, and orientation are single-value only.
+
+**Reduced motion:**
+
+- The item control does not currently animate. The CSS includes a `@media (prefers-reduced-motion: reduce)` block that flips `transition: none`, but the base rule does not currently declare a transition. The block is forward-looking.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Root layout | `display: grid; gap: var(--dsx-space-md)` | Cluster grid. |
+| Option layout | `display: inline-flex; align-items: flex-start; gap: var(--dsx-space-md)` | Option row layout. |
+| Option content layout | `display: grid; gap: var(--dsx-space-xs)` | Label/description stack. |
+| Option label/description typography | `var(--dsx-typography-body-medium-*)` | Body ramp. |
+| Option description color | `var(--dsx-color-on-surface-variant)` | Muted description. |
+| Item size (default) | `var(--dsx-size-md)` | Default control. |
+| Item size (sm) | `var(--dsx-size-sm)` | Small control. |
+| Item radius | `var(--dsx-rounded-full)` | Round. |
+| Item border | `var(--dsx-border-width-md)` solid `var(--dsx-color-outline-variant)` | Resting edge. |
+| Item background | `var(--dsx-color-surface)` | Resting fill. |
+| Item focus ring | `var(--dsx-shadow-focus-ring)` | Focus indicator. |
+| Item checked border | `var(--dsx-color-primary)` | Active edge. |
+| Item disabled opacity | `var(--dsx-opacity-disabled)` | Disabled fade. |
+| Dot size | `var(--dsx-space-sm)` square | Filled center. |
+| Dot radius | `var(--dsx-rounded-full)` | Round dot. |
+| Dot background | `var(--dsx-color-primary)` | Active dot. |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Item control | `none` today (the CSS has a reduced-motion block but no base transition) | `none` | The reduced-motion block sets `transition: none`. |
+
+## Accessibility
+
+**Roles:**
+
+- The root renders `RadioGroupPrimitive.Root`, which carries the WAI-ARIA `radiogroup` role. Each item carries the `radio` role. When `label` or `description` is set, the item wraps itself in a `<label>` that visually associates the description with the control.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus into the radio group, then to the selected (or first) item. |
+| `Arrow Down`, `Arrow Right` | Moves to the next item. |
+| `Arrow Up`, `Arrow Left` | Moves to the previous item. |
+| `Space` | Selects the focused item. |
+
+**Focus:**
+
+- The item relies on `:focus-visible` to draw the `var(--dsx-shadow-focus-ring)` focus ring. The base rule sets `outline: none` so the focus ring replaces the default outline.
+
+**Reduced motion:**
+
+- The CSS includes a `@media (prefers-reduced-motion: reduce)` block; the base rule does not currently declare a transition, so the block is a forward-looking guard.
+
+**Color and meaning:**
+
+- Selected state is communicated by the dot fill and the border swap to `var(--dsx-color-primary)`, not by color alone.
+
+**Naming:**
+
+- The root needs an `aria-label` or `aria-labelledby` to give the group an accessible name. Each item is named by its label text, by its description, or by its `aria-label`.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `RadioGroup` with two items, the first selected. Asserts the root class is `dsx-radio-group`, `data-size="md"`, `data-variant="solid"`, the first item is `data-state="checked"`, and the second is `data-state="unchecked"`.
+
+**Variant story:**
+
+- Renders with `variant="solid"`, `variant="soft"`, and `variant="outline"`. Asserts the matching `data-variant` attribute.
+
+**Size story:**
+
+- Renders with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute on the root.
+
+**Item size story:**
+
+- Renders items with `size="sm"` and `size="md"`. Asserts the matching `dsx-radio-item--{size}` class.
+
+**Composition story:**
+
+- Renders items with `label` and `description`. Asserts the option wrapper renders with `dsx-radio-option` and the description renders with `dsx-radio-option__description`.
+
+**State story:**
+
+- Renders the group with `disabled`. Asserts every item is disabled.
+- Renders with `highContrast`. Asserts `data-high-contrast="true"`.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the matching `data-accent-color` attribute on the root.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default group. Asserts the group has an accessible name and every item has a label.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `variant` | select | `solid` |
+| `size` | select | `md` |
+| `orientation` | select | (none) |
+| `color` | text | (empty) |
+| `highContrast` | boolean | `false` |
+| `disabled` | boolean | `false` |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-radio-group`: the root and the item primitive. The package does not implement its own radio semantics.
+- `@radix-ui/react-slot`: enables `asChild` on the root and the item.
+
+**Used by:**
+
+- `RadioCards`: card-style mutually exclusive cluster. RadioCards wraps `RadioGroup` and styles the items as cards.
+- Form specs that need a single-select decision with 2+ options and a visible label per option.
+
+**State boundaries:**
+
+- Owned by RadioGroup: the controlled/uncontrolled value, the `data-size`, `data-variant`, `data-accent-color`, and `data-high-contrast` attributes, and the indicator and dot rendering.
+- Owned by the consumer: the item values, the visible labels and descriptions, the `onValueChange` callback, the form context, and the surrounding `Field` integration.
+
+**Boundary rules:**
+
+- App-owned data: the values, the onValueChange handler, the validation rules.
+- DS-owned visuals: the root and item classes, the dot rendering, the focus ring, the disabled opacity, and the variant/size/contrast attributes.
+
+**Anomalies** (open items that this spec flags for the next promotion):
+
+1. **Orientation prop had zero CSS implementation; items never switched to horizontal layout.** The `orientation` prop is a real, working prop (`radioGroup.props.ts` defines it; Radix's `RadioGroupPrimitive.Root` sets `data-orientation` on the DOM automatically via the `asChild` merge when present). However, `radio-group.css` contained no rules targeting `[data-orientation]` — the layout was always a single-column grid regardless of the attribute's value. This is the literal "orientation no-op": the data was there on the DOM, but the CSS file did not consume it. FIXED 2026-07-03: added `.dsx-radio-group[data-orientation='horizontal'] { grid-auto-flow: column; gap: var(--dsx-space-lg); }` to enable horizontal layout. The vertical orientation needs no explicit rule — it is the implicit single-column grid default established by the base `.dsx-radio-group { display: grid; gap: var(--dsx-space-md); }` rule.