@d4gger/design-system 2.7.0

package/dist/docs/color-swatch.md

@@ -0,0 +1,246 @@
+---
+title: ColorSwatch
+status: canonical
+category: Primitives
+archetype: primitive
+package_path: packages/d4gger-design-system/src/components/colorSwatch/ColorSwatch.tsx
+css_path: packages/d4gger-design-system/src/styles/components/color-swatch.css
+props_path: packages/d4gger-design-system/src/components/colorSwatch/colorSwatch.props.ts
+test_path: packages/d4gger-design-system/src/test/components/ColorSwatch.test.tsx
+demo_path: apps/playground/app/page.tsx
+depends_on:
+  - Icon (lucide-react `Check`)
+---
+
+# ColorSwatch
+
+> 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 compact, pressable swatch that paints a single color value and reports its checked state to assistive tech. ColorSwatch is intentionally excluded from `data-accent-color` theming because its content IS a color value, so theme inheritance would corrupt the surface it represents.
+
+## Anatomy & slots
+
+**Parent:** `ColorSwatch` (no compound; flat export).
+
+**Slots:**
+
+No slots: flat export. The component renders a single host button (or a slotted child when `asChild` is set) and, when checked, a `Check` glyph from `lucide-react` inside the swatch.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `color` | `string` | `undefined` | yes | CSS color value painted as the swatch background. Stored verbatim and surfaced in the `aria-label`. | no |
+| `checked` | `boolean` | `false` | no | Marks the swatch as selected; drives `data-checked`, the `Check` glyph, and `aria-pressed`. | no |
+| `onClick` | `(color: string) => void` | `undefined` | no | Click handler. Receives the `color` value, not a `MouseEvent`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Swatch box size; selects the `dsx-color-swatch-{sm\|md\|lg}` size class and writes `data-size`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the swatch through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-color-swatch`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style. Merged with the runtime-injected `backgroundColor: color` (consumer `style` wins for other keys, but `backgroundColor` is taken from `color`). | no |
+| `children` | `React.ReactNode` | `undefined` | no | Slotted content when `asChild`; otherwise appended after the optional `Check` glyph. | no |
+
+Rules that apply to this row:
+
+- `asChild` is the only polymorphic infra exposed.
+- `ButtonHTMLAttributes<HTMLButtonElement>` are forwarded to the host button when `asChild` is false, with `onClick` overridden to the `(color) => void` signature above.
+- `size` is wired through `extractProps`; the value joins the prop def's `className` (`dsx-color-swatch`) to produce `dsx-color-swatch-sm`, `dsx-color-swatch-md`, or `dsx-color-swatch-lg`.
+
+## CSS class contract
+
+**Root class:** `dsx-color-swatch`
+
+**Modifier classes** (driven by `data-*` attributes and the `size` prop def):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `dsx-color-swatch-sm`, `dsx-color-swatch-md`, `dsx-color-swatch-lg` | `color-swatch.css` |
+| `data-checked` | (presence) | `.dsx-color-swatch[data-checked]` | `color-swatch.css` |
+
+**Slot classes:** none. The `dsx-color-swatch__check` class is a child glyph class, not a slot export.
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- Hover and active states animate `transform` and `box-shadow` against `var(--dsx-motion-duration-fast)` with `var(--dsx-motion-easing-standard)`. These are CSS transitions only; there is no framer-motion usage, so `usePrefersReducedMotion` is not imported.
+- Honor `prefers-reduced-motion` at the global stylesheet level. No runtime guard is wired in the source.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token. The swatch itself paints the consumer-supplied `color` value, which is intentionally not a token (see purpose).
+
+| Property | Token | Role |
+|---|---|---|
+| Background (default) | transparent | Container background; the swatch fill is the consumer's `color`. |
+| Border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline-variant)` | Default edge. |
+| Border (checked) | `var(--dsx-color-primary)` | Selected edge color. |
+| Border (high-contrast) | `var(--dsx-border-width-md)` + `var(--dsx-color-on-surface)` | High-contrast edge treatment, available via the CSS hook even though the runtime does not currently write `data-high-contrast`. |
+| Check ring (checked) | `var(--dsx-border-width-md)` + `var(--dsx-color-primary-alpha)` | Outer ring around the selected swatch. |
+| Size `sm` | `var(--dsx-size-sm)` + `var(--dsx-rounded-sm)` | Box and radius for the small size. |
+| Size `md` | `var(--dsx-size-md)` + `var(--dsx-rounded-md)` | Box and radius for the default size. |
+| Size `lg` | `var(--dsx-size-lg)` + `var(--dsx-rounded-lg)` | Box and radius for the large size. |
+| Hover shadow | `var(--dsx-shadow-sm)` | Hover elevation. |
+| Check glyph | `white` with `mix-blend-mode: difference` | Visual confirmation that the swatch is selected. Not a token. |
+| Transition | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Hover and active motion. |
+
+Rules:
+
+- The swatch fill is the only intentional non-token color; it must be the consumer's `color` value, so theming it would defeat the component.
+- All other painted values are tokens from `DESIGN.md` and the generated `tokens.css`.
+- Alpha is reserved for effect tokens; the `var(--dsx-color-primary-alpha)` ring follows that rule.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Hover and active transitions (`transform`, `box-shadow`) | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | `transform: scale(1.1)`, `box-shadow: var(--dsx-shadow-sm)` on hover; `transform: scale(0.95)` on active | `none` — relies on the global `prefers-reduced-motion` stylesheet; no runtime gate in the source. |
+
+Rules:
+
+- This row does not import `MOTION_TRANSITIONS` from `src/_internal/motion.ts`. It uses raw CSS transitions against the motion tokens. No framer-motion usage.
+- A future promotion that needs framer-motion should pick a preset from `MOTION_TRANSITIONS`; do not introduce new motion durations.
+
+## Accessibility
+
+**Roles:**
+
+- `button` by default. `aria-pressed` is set to `checked` (boolean), giving the swatch a toggle-button role. When `asChild` is set, the consumer owns the role and the swatch does not write `aria-pressed` itself.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to or from the swatch. |
+| `Enter`, `Space` | Activates the button and calls `onClick(color)`. |
+
+**Focus:**
+
+- Native focus ring via the host element. The CSS does not define a custom focus ring.
+- Focus visibility follows the global focus style; no override at the swatch level.
+
+**Reduced motion:**
+
+- Animations should be disabled by the global stylesheet when `prefers-reduced-motion: reduce` matches. The runtime does not currently gate motion; the CSS transition declarations honor the global override.
+
+**Color and meaning:**
+
+- The component does not communicate state by color alone. The `Check` glyph and the `aria-pressed` attribute communicate the same state for sighted and assistive-tech users.
+- The `aria-label` is auto-generated as ``Color swatch: ${color}${checked ? ', selected' : ''}``. Apps that need a localized or branded label should use `asChild` and supply their own accessible name.
+
+**Naming:**
+
+- Always has an accessible name. Default is the auto-generated `aria-label`; consumers can override via `asChild` with an element that owns its own name.
+
+## 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 `ColorSwatch` with `color="#ff6a00"` and no other props. Asserts the root class is `dsx-color-swatch`, the `data-size` attribute is `md`, and the `aria-label` is `Color swatch: #ff6a00`.
+
+**Variant story** (one per size):
+
+- Renders the swatch with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `dsx-color-swatch-{sm|md|lg}` class and `data-size` value.
+
+**State story:**
+
+- Renders the swatch in `default`, `hover` (`:hover` pseudo-class; no `data-*` attribute), and `checked` (with `checked={true}`). Asserts `data-checked` presence and `aria-pressed="true"`.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper. ColorSwatch does not consume `data-accent-color`, so the story asserts the swatch is visually unchanged between `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. The default `data-accent-color` is `amber`; no override is required.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default swatch. Asserts there are no axe violations and the button has an accessible name.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `color` | text | `#ff6a00` |
+| `checked` | boolean | `false` |
+| `size` | select | `md` |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Icon` (lucide-react `Check`): rendered when `checked` is `true` to communicate the selected state visually.
+- `@radix-ui/react-slot`: enables `asChild` for consumer-supplied host elements.
+
+**Used by:**
+
+- `ColorPicker`: package-stage surface that internally composes `Popover` + `ColorSwatch`. `ColorSwatch` is the swatch surface inside the popover.
+- `ThemePanel`: foundational theme configuration surface for color, gray, radius, density, and scaling. Uses `ColorSwatch` to paint the current accent choice.
+
+**State boundaries:**
+
+- Owned by ColorSwatch: the `data-checked` attribute, the `Check` glyph visibility, the `aria-pressed` reflection, and the `aria-label` template.
+- Owned by the consumer: the `color` value, the `checked` boolean, the `onClick` handler, the host element when `asChild` is set, and the click semantics (single-select vs. multi-select).
+
+**Boundary rules:**
+
+- App-owned data: the actual color list, the selection state model (single or multi), and the persistence of the chosen color.
+- DS-owned visuals: token bindings (`--dsx-color-outline-variant`, `--dsx-color-primary`, `--dsx-color-primary-alpha`, `--dsx-size-*`, `--dsx-rounded-*`, `--dsx-shadow-sm`, `--dsx-motion-*`), the `dsx-color-swatch` root class, the `data-size` and `data-checked` attributes, the `aria-pressed` reflection, and the auto-generated `aria-label`.
+- ColorSwatch intentionally bypasses `data-accent-color`. The CSS does not reference `--dsx-color-primary` for the resting state, only for the selected ring and edge. Consumers must not rely on the swatch to inherit the wrapper's accent color.
+
+## 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 ColorSwatch. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Primitives / ColorSwatch`.
+- **Dimensions**: `32 × 32` (md) and scaled variants for sm and lg.
+- **Layout**: `Fixed`.
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'fix'`.
+
+### Layer tree
+
+```
+<Root Board: ColorSwatch / md>
+  ├── <Frame: swatch fill (backgroundColor = color)>
+  └── <Shape: Check glyph, visible only when checked = true>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Root | stroke | `--dsx-color-outline-variant` | Color | `strokes` |
+| Root (checked) | stroke | `--dsx-color-primary` | Color | `strokes` (state) |
+| Root (checked) | shadow | `--dsx-color-primary-alpha` | Effect | `shadow` (state) |
+| Root (size sm) | width, height | `--dsx-size-sm` | Sizing | `size` |
+| Root (size md) | width, height | `--dsx-size-md` | Sizing | `size` |
+| Root (size lg) | width, height | `--dsx-size-lg` | Sizing | `size` |
+
+### State transformations
+
+| State | Root fill | Stroke | Text fill | Shadow |
+|---|---|---|---|---|
+| `default` | consumer `color` | `--dsx-color-outline-variant` | n/a | none |
+| `hover` | consumer `color` | `--dsx-color-outline-variant` | n/a | `--dsx-shadow-sm` |
+| `checked` | consumer `color` | `--dsx-color-primary` | `white` (Check) | `--dsx-color-primary-alpha` ring |
+
+### Variant model
+
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `checked`: `true`, `false`. Default `false`.
+- Total members: 6.
+
+### Validation checklist
+
+- [ ] Token bindings resolve at the values `DESIGN.md` describes.
+- [ ] Component is promoted to Main Component under `Primitives`.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
+- [ ] High-contrast edge (`data-high-contrast="true"`) renders even though the runtime does not currently emit that attribute; document it as a CSS hook only.

package/dist/docs/combobox.md

@@ -0,0 +1,370 @@
+---
+title: Combobox
+status: canonical
+category: Components
+archetype: radix-compound
+package_path: packages/d4gger-design-system/src/components/combobox/Combobox.tsx
+css_path: packages/d4gger-design-system/src/styles/components/combobox.css
+props_path: packages/d4gger-design-system/src/components/combobox/combobox.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Combobox.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/overlay.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Popover (the open/close, anchor, and portal behavior comes from `@radix-ui/react-popover` through `Popover`)
+  - Command (the searchable list, item selection, keyboard navigation, and `cmdk`-style filtering come from the DS `Command` surface)
+  - Icon (lucide-react `chevron-down` for the trigger affordance and `check` for selected items)
+  - framer-motion (`AnimatePresence` and `motion.div` for the content open/close transition)
+  - "@radix-ui/react-slot (asChild on every subcomponent)"
+---
+
+# Combobox
+
+> 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 search-first option picker for large option sets. The user types into an inline input and a virtualized list of options filters as they type. Pairs `Popover` (for the floating surface, anchor, and portal) with `Command` (for the searchable list and keyboard navigation) and adds DS-specific trigger, content, and item styling on top.
+
+## Anatomy & slots
+
+**Parent:** `Combobox` (alias of `Combobox.Root`). The `Combobox` export is the parent object and `Combobox.Root` resolves to the same internal `ComboboxRoot` component.
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Combobox.Root` | `<div>` with `display: contents` wrapping `Popover` | The root div writes `data-accent-color`, `data-radius`, `data-size`, `data-variant`. The internal `Popover` owns open state and the portal. | Controls open state, forwards Radix `Popover` props (`defaultOpen`, `open`, `onOpenChange`, `modal`, etc.). |
+| `Combobox.Trigger` | `PopoverTrigger` (a `<button>`) | `dsx-combobox__trigger`, plus a trailing `dsx-combobox__icon` chevron. Writes `data-invalid="true"` when `invalid` is set. | The button that toggles the menu. `PopoverTrigger` already supplies `role="combobox"`. |
+| `Combobox.Anchor` | `PopoverAnchor` | The Radix anchor primitive | Optional alternative anchor for positioning. Re-exported as `ComboboxAnchor` and `Combobox.Anchor`. |
+| `Combobox.Content` | `PopoverContent` wrapping `motion.div` + `Command` | `dsx-combobox__content` on the popover content, `dsx-combobox__command` on the inner Command shell. The motion div animates opacity and a small Y offset. | The floating menu. Honors `forceMount` from Radix Popover; the inner motion block also reads `forceMount` to keep the menu mounted. |
+| `Combobox.Input` | `CommandInput` | `dsx-combobox__search` on the wrapper, `dsx-combobox__input` on the `<input>` | The filter input. |
+| `Combobox.List` | `CommandList` | `dsx-combobox__list` | The scroll container of filtered options. |
+| `Combobox.Empty` | `CommandEmpty` | `dsx-combobox__empty` | The empty-state row shown when no option matches the typed filter. |
+| `Combobox.Item` | `CommandItem` | `dsx-combobox__item`, plus a `dsx-combobox__item-icon` (lucide `check`) when `selected` is true. Writes `data-selected="true"` and `aria-selected` when `selected` is true. | A single option in the filtered list. |
+| `Combobox.Group` | `CommandGroup` | `dsx-combobox__group` | Optional grouping for related options. |
+
+## Props contract
+
+**Root props (`Combobox` / `Combobox.Root`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. The prop is consumed by `extractProps` and dropped from the forwarded props. | no |
+| `variant` | `'solid' \| 'soft' \| 'outline' \| 'ghost'` | `'solid'` | no | Visual style of the trigger. Writes `data-variant` on the root. The CSS does not currently declare per-variant rules; the attribute is the contract hook for future styling. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Trigger height. Writes `data-size` on the root. The CSS does not currently declare per-size rules; the attribute is the contract hook. | no |
+| `color` | `string` (any `data-accent-color` value) | `undefined` | no | Accent color override. Writes `data-accent-color` on the root. The prop def is `'enum \| string'` with an empty `values` array, so any string is accepted. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner radius override. Writes `data-radius` on the root. | no |
+| `defaultOpen` | `boolean` | `undefined` | no | Initial open state when uncontrolled. Forwarded to `Popover`. | no |
+| `open` | `boolean` | `undefined` | no | Controlled open state. Forwarded to `Popover`. | no |
+| `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Fires on every open transition. Forwarded to `Popover`. | no |
+| `modal` | `boolean` | `undefined` | no | Forwards Radix `Popover` modal behavior. | no |
+
+`ComboboxProps` extends `React.ComponentPropsWithoutRef<typeof Popover> & ComboboxOwnProps`, so any standard Radix Popover prop (other than the ones the prop bag owns) is forwarded unchanged.
+
+**`Combobox.Trigger` props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the trigger through `Slot`. | no |
+| `invalid` | `boolean` | `false` | no | Marks the trigger as invalid. Writes `data-invalid="true"` and adds the `dsx-combobox-trigger-invalid` class. The CSS uses the class to swap the border to `var(--dsx-color-error)`. | no |
+| (Radix `PopoverTrigger` props) | n/a | n/a | no | All other Popover trigger props are forwarded. | no |
+
+**`Combobox.Content` props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the content through `Slot`. | no |
+| `forceMount` | `boolean` | `false` | no | Forces the inner motion block to stay mounted even when closed. Forwarded to `PopoverContent`. | no |
+| (Radix `PopoverContent` props) | n/a | n/a | no | All other Popover content props are forwarded. | no |
+
+**`Combobox.Input` props:** forwards `React.ComponentPropsWithoutRef<typeof CommandInput>` plus `asChild`.
+
+**`Combobox.List`, `Combobox.Empty`, `Combobox.Group` props:** forwards the corresponding `Command` primitive props plus `asChild`.
+
+**`Combobox.Item` props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the item through `Slot`. | no |
+| `selected` | `boolean` | `false` | no | Marks the item as selected. Writes `data-selected="true"`, `aria-selected={true}`, adds the `dsx-combobox-item-selected` class, and renders a trailing check icon. | no |
+| (Radix `CommandItem` props) | n/a | n/a | no | All other CommandItem props are forwarded. | no |
+
+Rules that apply to this row:
+
+- The root merges `extractProps({ ...props, defaultOpen, onOpenChange, open: openProp }, comboboxPropDefs)`; `defaultOpen`, `onOpenChange`, and `open` are removed from the forwarded bag and re-applied through `Popover` to avoid Radix's `defaultControlled` warning.
+- The internal `ComboboxOpenContext` carries the resolved `open` state so `Combobox.Content` can read it without prop drilling.
+- The CSS contract is light: the trigger and content paint with token-driven colors and surface tokens; variant, size, and radius are wired as `data-*` attributes for future styling but no per-variant / per-size CSS rules are declared today.
+- `selected` on `Combobox.Item` is the only slot-level boolean that drives a `data-*` attribute.
+
+## CSS class contract
+
+**Root class:** `dsx-combobox` (on the inner Popover content's parent Command shell, plus the trigger, content, and item regions).
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-invalid` | `true` | `.dsx-combobox__trigger[data-invalid='true']` border swap to `var(--dsx-color-error)` | `combobox.css` |
+| `data-selected` | `true` | `.dsx-combobox__item[data-selected='true']` font-weight emphasis | `combobox.css` |
+| `data-variant` | `solid`, `soft`, `outline`, `ghost` | (attribute written on root; no per-variant CSS rule today) | `combobox.css` |
+| `data-size` | `sm`, `md`, `lg` | (attribute written on root; no per-size CSS rule today) | `combobox.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (attribute written on root; CSS does not yet declare matching rules) | `combobox.css` |
+| `data-accent-color` | any token name | (attribute written on root; CSS does not yet declare matching rules) | `combobox.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Combobox.Trigger` | `dsx-combobox__trigger` | `combobox.css` |
+| Trigger icon | `dsx-combobox__icon` | `combobox.css` |
+| `Combobox.Content` | `dsx-combobox__content` | `combobox.css` |
+| Inner Command shell | `dsx-combobox__command` | `combobox.css` |
+| `Combobox.Input` wrapper | `dsx-combobox__search` | `combobox.css` |
+| `Combobox.Input` | `dsx-combobox__input` | `combobox.css` |
+| `Combobox.List` | `dsx-combobox__list` | `combobox.css` |
+| `Combobox.Empty` | `dsx-combobox__empty` | `combobox.css` |
+| `Combobox.Item` | `dsx-combobox__item` | `combobox.css` |
+| `Combobox.Item` check icon | `dsx-combobox__item-icon` | `combobox.css` |
+| `Combobox.Group` | `dsx-combobox__group` | `combobox.css` |
+| Trigger (invalid) | `dsx-combobox-trigger-invalid` | `combobox.css` |
+| Item (selected) | `dsx-combobox-item-selected` | `combobox.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of the prop defs are `responsive: true`. Variant, size, and radius are single-value only.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- The content's open/close animation uses `framer-motion` and gates the transition through `usePrefersReducedMotion`. When reduced motion is active, the initial / animate / exit values collapse to opacity-only and the duration drops to `MOTION_TRANSITIONS.reduced`.
+- The CSS file does not declare motion; motion is owned by framer-motion at the JS layer.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Trigger background | `var(--dsx-color-surface)` | Resting trigger surface. |
+| Trigger border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Resting trigger edge. |
+| Trigger border (focus-visible) | `var(--dsx-color-primary)` | Focus state. |
+| Trigger focus ring | `var(--dsx-shadow-focus-ring)` | Focus-visible ring. |
+| Trigger border (invalid) | `var(--dsx-color-error)` | Error state, set via `data-invalid='true'` or the `invalid` class. |
+| Trigger radius | `var(--dsx-rounded-md)` | Default corner roundness. |
+| Trigger text | `var(--dsx-color-on-surface)` | Trigger label. |
+| Trigger typography | `var(--dsx-typography-body-medium-*)` | Trigger label ramp. |
+| Trigger height | `var(--dsx-size-xl)` | Default control height. |
+| Trigger icon color | `var(--dsx-color-on-surface-variant)` | Trailing chevron. |
+| Content background | `var(--dsx-color-surface-overlay)` | Floating menu surface. |
+| Content border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Floating menu edge. |
+| Content radius | `var(--dsx-rounded-md)` | Floating menu corner roundness. |
+| Content width | `var(--dsx-combobox-content-width)` | Floating menu width. |
+| Content z-index | `var(--dsx-z-index-dropdown)` | Overlay stacking. |
+| Search wrapper border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Bottom divider below the input. |
+| Input height | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Density-aware control height. |
+| List max-height | `var(--dsx-combobox-list-max-height)` | Scroll ceiling. |
+| List padding | `var(--dsx-space-xs)` | List inner gutter. |
+| List gap | `var(--dsx-combobox-list-gap)` | Gap between options. |
+| Empty padding | `var(--dsx-space-md)` | Empty-state gutter. |
+| Empty text | `var(--dsx-color-on-surface-variant)` | Empty-state label. |
+| Item padding | `var(--dsx-space-sm) var(--dsx-space-md)` | Option inner gutter. |
+| Item radius | `var(--dsx-rounded-sm)` | Option corner roundness. |
+| Item text | `var(--dsx-color-on-surface)` | Option label. |
+| Item typography | `var(--dsx-typography-body-medium-*)` | Option label ramp. |
+| Item font weight (selected) | `var(--dsx-typography-body-medium-font-weight, 500)` | Selected option emphasis. |
+| Item check icon color | `var(--dsx-color-primary)` | Selected option check. |
+| Motion | `MOTION_TRANSITIONS.combobox` (or `MOTION_TRANSITIONS.reduced` under reduced motion) | Content open/close transition. |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in the CSS file.
+- Tokens come from `DESIGN.md` via the generated `tokens.css`. New tokens land there first, not in the component CSS.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| `Combobox.Content` open/close | `MOTION_TRANSITIONS.combobox` | Opacity 0 → 1 plus a small Y offset (4px down on enter, 2px down on exit) | Opacity-only via `MOTION_TRANSITIONS.reduced` |
+
+Rules:
+
+- The motion is wired through framer-motion's `AnimatePresence` inside `Combobox.Content`. The component checks `usePrefersReducedMotion` and swaps to the `reduced` preset when the user prefers reduced motion.
+- The `MOTION_TRANSITIONS.combobox` preset is the canonical binding for the combobox content open/close animation. Other regions are static.
+
+## Accessibility
+
+**Roles:**
+
+- `Combobox.Trigger` renders as a `<button>` with `role="combobox"` (Radix PopoverTrigger sets the role).
+- The option list rendered through `Command.List` exposes `role="listbox"`, and each `CommandItem` (`Combobox.Item`) exposes `role="option"`. `aria-selected` reflects the `selected` prop.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to or from the trigger. |
+| `Enter`, `Space` | Opens the menu when the trigger is focused. Inside the list, the Command surface handles selection. |
+| `Escape` | Closes the menu and returns focus to the trigger. |
+| Arrow keys | Navigate the option list. |
+| Type | Filters the option list through the input. |
+
+**Focus:**
+
+- The CSS file paints a `var(--dsx-shadow-focus-ring)` ring on the trigger's `:focus-visible`. The ring is visible on dark and light surfaces.
+
+**Reduced motion:**
+
+- The content's open/close transition collapses to an opacity-only fade when `prefers-reduced-motion: reduce` is set. The CSS file does not declare motion; the runtime swap is the only path.
+
+**Color and meaning:**
+
+- Selected state is communicated by the trailing check icon, `data-selected='true'`, and `aria-selected={true}`. The optional font-weight emphasis reinforces the same state.
+
+**Naming:**
+
+- `Combobox.Trigger` renders as a `<button>`. Provide an accessible name via the trigger's children (the button's text content becomes the name) or via `aria-label`.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Combobox` with no extra props. Asserts the root renders a trigger with the default `data-size="md"`, `data-variant="solid"`, and a chevron-down icon.
+
+**Variant story:**
+
+- Renders one `Combobox` per `variant` value (`solid`, `soft`, `outline`, `ghost`). Asserts the matching `data-variant` attribute is set on the root.
+
+**Size story:**
+
+- Renders one `Combobox` per `size` value (`sm`, `md`, `lg`). Asserts the matching `data-size` attribute is set on the root.
+
+**State story:**
+
+- Renders `Combobox.Trigger` with `invalid`. Asserts the trigger has `data-invalid='true'` and the `dsx-combobox-trigger-invalid` class.
+- Renders `Combobox.Item` with `selected`. Asserts the item has `data-selected='true'`, `aria-selected='true'`, and the `dsx-combobox-item-selected` class, and that a check icon is rendered.
+
+**Composition story:**
+
+- Renders a `Combobox` with `Trigger`, `Content`, `Input`, `List`, and `Item` slots populated. Asserts each slot renders the right class.
+
+**Token story:**
+
+- Renders the trigger inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`. Asserts the `data-accent-color` attribute on the root reflects the active accent.
+
+**A11y story:**
+
+- Uses `vitest-axe` against an open `Combobox` with options. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `variant` | select | `solid` |
+| `size` | select | `md` |
+| `radius` | select | (none) |
+| `color` | text | (empty) |
+| `defaultOpen` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Popover` (`@radix-ui/react-popover`): open state, anchor, portal, focus management, and `role="combobox"`.
+- `Command` (DS primitive backed by `cmdk`): searchable list, item selection, keyboard navigation, and the empty-state row.
+- `Icon` (lucide-react `chevron-down`): the trigger trailing icon. Lucide-react `check` is the selected-item glyph.
+- `framer-motion` `AnimatePresence` and `motion.div`: the content's open/close animation.
+- `@radix-ui/react-slot`: enables `asChild` on every subcomponent.
+- `_internal/usePrefersReducedMotion`: gates the framer-motion transition when the user prefers reduced motion.
+- `_internal/motion`: `MOTION_TRANSITIONS.combobox` and `MOTION_TRANSITIONS.reduced` presets.
+
+**Used by:**
+
+- Search-first option pickers across the app shell. The roster currently lists no DS consumer.
+- `DataTable` (per the roster's wiring notes) composes `SearchBar`, which in turn composes `Command`. `Combobox` is the public-facing search-style picker; `SearchBar` is the trigger-plus-menu launcher. They are not interchangeable: `Combobox` opens a menu anchored to a trigger with an inline filter input; `SearchBar` opens a dialog-style palette that listens for a global keyboard shortcut.
+
+**State boundaries:**
+
+- Owned by Combobox: the `ComboboxOpenContext`, the `data-*` attribute contract on the root, the `data-invalid` attribute on the trigger, and the `data-selected` / `aria-selected` on the item.
+- Owned by `Popover` (Radix): the open state, the portal, the focus return to the trigger on close, and the `role="combobox"` semantics.
+- Owned by the consumer: the option list, the filter logic, the selection event handler, the trigger label, and the host form context.
+
+**Boundary rules:**
+
+- App-owned data: the option list (often fetched from a server or a config file), the highlighted filter predicate, and the persistence target.
+- DS-owned visuals: token bindings, the slot classes, the `data-*` attribute contract, the chevron and check icons, and the framer-motion preset binding.
+
+## 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 Combobox. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / Combobox`.
+- **Dimensions**: `320 × auto` (default), `280 × auto` (sm), `360 × auto` (lg).
+- **Layout**: `Flex` (column for the menu, row for the trigger).
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board: Combobox>
+  ├── <Frame: trigger>
+  │     ├── <Text: trigger label>
+  │     └── <Icon: chevron-down>
+  └── <Frame: content>
+        ├── <Frame: search>
+        │     └── <Text: filter input>
+        └── <Frame: list>
+              ├── <Frame: item × N>
+              │     ├── <Text: item label>
+              │     └── <Icon: check (when selected)>
+              └── <Text: empty (when no match)>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Trigger | fill | `--dsx-color-surface` | Color | `fills` |
+| Trigger | stroke | `--dsx-color-outline` | Color | `strokes` |
+| Trigger | radius | `--dsx-rounded-md` | Radius | `radius` |
+| Trigger (focus) | stroke | `--dsx-color-primary` | Color | `strokes` (state) |
+| Trigger (focus) | shadow | `--dsx-shadow-focus-ring` | Effect | `shadow` (state) |
+| Trigger (invalid) | stroke | `--dsx-color-error` | Color | `strokes` (state) |
+| Trigger | typography | `--dsx-typography-body-medium-*` | Typography | `typography` |
+| Trigger icon | fill | `--dsx-color-on-surface-variant` | Color | `fills` |
+| Content | fill | `--dsx-color-surface-overlay` | Color | `fills` |
+| Content | stroke | `--dsx-color-outline` | Color | `strokes` |
+| Content | radius | `--dsx-rounded-md` | Radius | `radius` |
+| Search wrapper | stroke | `--dsx-color-outline` (bottom only) | Color | `strokes` (state) |
+| Item | typography | `--dsx-typography-body-medium-*` | Typography | `typography` |
+| Item (selected) | font-weight | `--dsx-typography-body-medium-font-weight` | Typography | `typography` |
+| Item check icon | fill | `--dsx-color-primary` | Color | `fills` |
+
+### State transformations
+
+| State | Trigger stroke | Trigger fill | Item font-weight | Item check |
+|---|---|---|---|---|
+| `default` | `--dsx-color-outline` | `--dsx-color-surface` | `400` | hidden |
+| `focus` | `--dsx-color-primary` | `--dsx-color-surface` | `400` | hidden |
+| `invalid` | `--dsx-color-error` | `--dsx-color-surface` | `400` | hidden |
+| `selected` (item) | n/a | n/a | `500` | shown |
+
+### Variant model
+
+- `variant`: `solid`, `soft`, `outline`, `ghost`. Default `solid`.
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `radius`: `none`, `sm`, `md`, `lg`, `full`. Default unset (CSS uses `var(--dsx-rounded-md)`).
+- `color`: any accent color token. Default unset.
+- `defaultOpen`: `true`, `false`. Default `false`.
+- Total members: 4 × 3 × 5 × N × 2 = the matrix fans out from `size` in the authoring board; the rest are CSS-only hooks.
+
+### 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.
+- [ ] The chevron and check icons are baked in; do not treat them as themable in Penpot.