@d4gger/design-system 2.7.0

package/dist/docs/select.md

@@ -0,0 +1,406 @@
+---
+title: Select
+status: canonical
+category: Components
+archetype: radix-compound
+package_path: packages/d4gger-design-system/src/components/select/Select.tsx
+css_path: packages/d4gger-design-system/src/styles/components/select.css
+props_path: packages/d4gger-design-system/src/components/select/select.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Select.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-select (the entire state machine, the option list, the trigger / value / item / separator / group parts, the `role='combobox'` semantics, the portal, and the focus return to the trigger on close)"
+  - ScrollArea (the `Select.Content` slot mounts a `ScrollArea` to host the option list, so long option sets scroll inside a token-aligned scroll viewport)
+  - VisuallyHidden (the `Select.HiddenSelect` slot renders the hidden native `<select>` through `VisuallyHidden` for native form submission and autofill)
+  - Icon (lucide-react `chevron-down` is the trigger trailing icon and lucide-react `check` is the item indicator glyph)
+  - "_internal/BaseDialog (the `PortalThemeBoundary` and `PortalThemeWrapper` helpers mirror the `data-dsx-*` attribute contract into the content portal)"
+  - "_internal/baseMenu.css (the shared menu shell, border, surface, and focus contract)"
+---
+
+# Select
+
+> 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 controlled option picker for known, medium-sized lists. Pairs the Radix Select state machine with DS token-aligned trigger, content, and item styling, mirrors the `data-dsx-*` theme contract into the content portal through the `BaseDialog` portal helpers, and exposes a hidden native `<select>` for native form submission. Use `Select` for known lists where the user picks one value; use `Combobox` for search-first pickers over large option sets.
+
+## Anatomy & slots
+
+**Parent:** `Select` (alias of `Select.Root` and of the `Select` default export that re-exports the full compound).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Select` (Root) | `@radix-ui/react-select` `Root` wrapped in `PortalThemeBoundary` and `SelectContext.Provider` | The Radix root. Owns open state and the value pipeline. | Reads `accentColor`, `size`, and `variant` into `SelectContext` so subcomponents can resolve them. |
+| `Select.Trigger` | `@radix-ui/react-select` `Trigger` | `dsx-select__trigger`, plus a trailing `dsx-select__icon` (lucide `chevron-down`) and a `dsx-select__value` (the `SelectValue` slot). Writes `data-size`, `data-variant`. | The button that opens the menu. Renders as a `<button>`. The `SelectValue` renders by default when no children are provided. |
+| `Select.Value` | `@radix-ui/react-select` `Value` | `dsx-select__value` | The displayed value. Honors `placeholder` when no value is selected. |
+| `Select.Content` | `@radix-ui/react-select` `Content` wrapped in `PortalThemeWrapper`, with a `ScrollArea` + `Viewport` for the option list | `dsx-select__content` on the popover, `dsx-select__scroll-area` on the `ScrollArea`, `dsx-select__viewport` on the inner viewport. Writes `data-size`, `data-variant`. | The floating menu. Renders into a portal. The `position` prop selects between `item-aligned` (default) and `popper`. |
+| `Select.Group` | `@radix-ui/react-select` `Group` | n/a (no DS class) | A semantic group of items, used with `Select.ItemGroupLabel`. |
+| `Select.ItemGroupLabel` | `@radix-ui/react-select` `Label` | `dsx-select__group-label` | The label rendered at the top of a group. |
+| `Select.Label` | `@radix-ui/react-select` `Label` | `dsx-select__label` | A standalone label inside `Content`. |
+| `Select.Item` | `@radix-ui/react-select` `Item` | `dsx-select__item` (the row), `dsx-select__item-indicator` (the leading check slot), `dsx-select__item-text` (the text container) | A single option. The leading check appears only when the item is the selected value. |
+| `Select.Separator` | `@radix-ui/react-select` `Separator` | `dsx-select__separator` | Visual divider between groups. |
+| `Select.ValueText` | `@radix-ui/react-select` `ItemText` | `dsx-select__item-text` | Custom-renderable text container. Useful for embedding markup in the displayed value. |
+| `Select.HiddenSelect` | native `<select>` wrapped in `VisuallyHidden` | `dsx-select__hidden` (on the `<select>`) | Hidden native `<select>` for native form submission and autofill. Honors `name`, `disabled`, `required`, and an `options` array. |
+
+## Props contract
+
+**Root props (`Select` / `Select.Root`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Trigger / content size. Writes `data-size` on `Select.Trigger` and `Select.Content` and resolves the `dsx-select-size-{sm,md,lg}` modifier class. | no |
+| `variant` | `'default' \| 'ghost'` | `'default'` | no | Trigger / content variant. Writes `data-variant` and resolves the `dsx-select-variant-{default,ghost}` modifier class. | no |
+| `accentColor` | `'default' \| 'primary'` | `'default'` | no | Accent color override. Writes `data-accent-color` on the trigger and content. | no |
+| (Radix `Select.Root` props) | n/a | n/a | no | All standard Radix Select root props (`value`, `defaultValue`, `onValueChange`, `open`, `defaultOpen`, `onOpenChange`, `name`, `disabled`, `required`, `dir`, `form`) are forwarded. | no |
+
+`SelectRootProps` extends `React.ComponentPropsWithoutRef<typeof SelectPrimitive.Root> & SelectRootOwnProps`.
+
+**`Select.Trigger` props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the trigger through `Slot`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Trigger size override. Resolves against the explicit prop first, then `data-size` on the trigger, then the `SelectContext.size` value. | no |
+| `variant` | `'default' \| 'ghost'` | `'default'` | no | Trigger variant override. Resolves against the explicit prop first, then `data-variant` on the trigger, then the `SelectContext.variant` value. | no |
+| `data-size` | `'sm' \| 'md' \| 'lg'` | `undefined` | no | Direct data-attribute override. Wins over the resolved `size`. | no |
+| `data-variant` | `'default' \| 'ghost'` | `undefined` | no | Direct data-attribute override. Wins over the resolved `variant`. | no |
+| (Radix `Select.Trigger` props) | n/a | n/a | no | All other Radix trigger props are forwarded. | no |
+
+`SelectTriggerProps` extends `React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger> & SelectTriggerOwnProps & SelectDataAttributes`.
+
+When `asChild` is set, the trigger renders only the children. The trailing chevron and the default `SelectValue` are skipped, so the slotted child is responsible for rendering its own label.
+
+**`Select.Content` props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the content through `Slot`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Content size override. Resolved the same way as the trigger. | no |
+| `variant` | `'default' \| 'ghost'` | `'default'` | no | Content variant override. Resolved the same way as the trigger. | no |
+| `position` | `'item-aligned' \| 'popper'` | `'item-aligned'` | no | Radix positioning mode. `popper` uses `sideOffset={4}`; `item-aligned` uses `sideOffset={undefined}` (Radix default). | no |
+| `sideOffset` | `number` | `position === 'popper' ? 4 : undefined` | no | Distance from the trigger. | no |
+| `data-size` | `'sm' \| 'md' \| 'lg'` | `undefined` | no | Direct data-attribute override. Wins over the resolved `size`. | no |
+| `data-variant` | `'default' \| 'ghost'` | `undefined` | no | Direct data-attribute override. Wins over the resolved `variant`. | no |
+| (Radix `Select.Content` props) | n/a | n/a | no | All other Radix content props are forwarded. | no |
+
+`SelectContentProps` extends `React.ComponentPropsWithoutRef<typeof SelectPrimitive.Content> & SelectContentOwnProps & SelectDataAttributes & { position?: 'item-aligned' | 'popper' }`.
+
+**`Select.Value` props:** standard `React.ComponentPropsWithoutRef<typeof SelectPrimitive.Value>`.
+
+**`Select.Group`, `Select.Separator`, `Select.Item`, `Select.ItemGroupLabel`, `Select.Label`, `Select.ValueText` props:** the corresponding Radix primitive props are forwarded as-is.
+
+**`Select.HiddenSelect` props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `name` | `string` | `undefined` | no | Native form field name. | no |
+| `disabled` | `boolean` | `undefined` | no | Native disabled. | no |
+| `required` | `boolean` | `undefined` | no | Native required marker. | no |
+| `options` | `Array<{ value: string; label: string; disabled?: boolean }>` | `undefined` | no | Convenience list. The runtime renders one `<option>` per entry, mapping `value`, `label`, and `disabled`. | no |
+| (HTML select props) | n/a | n/a | no | `value` and `defaultValue` are forwarded. The hidden select has `tabIndex={-1}` and `aria-hidden="true"` baked in. | no |
+
+Rules:
+
+- The accent color, size, and variant resolved in the root flow into `SelectContext` so any subcomponent without an explicit override inherits them. The trigger and content both write the resolved `data-size` and `data-variant` so the CSS picks them up regardless of where they were set.
+- The hidden native `<select>` is the only slot that owns a real form-control element. Apps that need native form submission (or autofill) should mount `Select.HiddenSelect` inside `Select`.
+
+## CSS class contract
+
+**Root class:** `dsx-select__trigger` (on the trigger) and `dsx-select__content` (on the floating menu).
+
+**Modifier classes** (driven by `data-*` attributes and class merging written by the component):
+
+| Attribute / source | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-select__trigger[data-size='sm'\|'md'\|'lg']` min-height and padding; `.dsx-select-size-{sm,md,lg}` | `select.css` |
+| `data-variant` | `default`, `ghost` | `.dsx-select__trigger[data-variant='ghost']` transparent background; `.dsx-select-variant-ghost` | `select.css` |
+| `data-placeholder` | (Radix-native) | `.dsx-select__trigger[data-placeholder]` muted text | `select.css` |
+| `data-state` | `open`, `closed` (Radix-native) | `.dsx-select__trigger[data-state='open']` primary border + focus ring | `select.css` |
+| `data-disabled` | (Radix-native) | `.dsx-select__trigger[data-disabled]` disabled cursor and opacity | `select.css` |
+| `data-accent-color` | `default`, `primary` | (attribute written; CSS does not yet declare matching rules) | `select.css` |
+| `aria-invalid` | `true` | `.dsx-select__trigger[aria-invalid='true']` error border | `select.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Select.Trigger` | `dsx-select__trigger` | `select.css` |
+| `Select.Value` | `dsx-select__value` | `select.css` |
+| `Select.Content` | `dsx-select__content` | `select.css` |
+| `Select.Item` | `dsx-select__item` | `select.css` |
+| Item indicator | `dsx-select__item-indicator` | `select.css` |
+| Item text | `dsx-select__item-text` | `select.css` |
+| `Select.Group` | (no DS class) | n/a |
+| `Select.ItemGroupLabel` | `dsx-select__group-label` | `select.css` |
+| `Select.Label` | `dsx-select__label` | `select.css` |
+| `Select.Separator` | `dsx-select__separator` | `select.css` |
+| `Select.ValueText` | `dsx-select__item-text` | `select.css` |
+| `Select.HiddenSelect` (on the `<select>`) | `dsx-select__hidden` | `select.css` |
+| `ScrollArea` inside content | `dsx-select__scroll-area` | `select.css` |
+| `ScrollArea` viewport | `dsx-select__viewport` | `select.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of the prop defs are `responsive: true`. Size and variant are single-value only.
+
+**Reduced motion:**
+
+- The CSS file paints the trigger's transition tokens (`var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`). The CSS does not currently gate this transition behind `prefers-reduced-motion`; the global stylesheet is the source of any reduced-motion override.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Trigger min-height (md) | `var(--dsx-size-xl)` | Default control height. |
+| Trigger min-height (sm) | `var(--dsx-size-lg)` | Small control height. |
+| Trigger min-height (lg) | `calc(var(--dsx-size-xl) + var(--dsx-space-sm))` | Large control height. |
+| Trigger padding (md) | `var(--dsx-space-sm) var(--dsx-space-md)` | Default control padding. |
+| Trigger padding (sm) | `var(--dsx-space-xs) var(--dsx-space-sm)` | Small control padding. |
+| Trigger padding (lg) | `var(--dsx-space-md) var(--dsx-space-lg)` | Large control padding. |
+| Trigger border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Resting edge. |
+| Trigger radius | `var(--dsx-rounded-md)` | Default corner roundness. |
+| Trigger background | `var(--dsx-color-surface)` | Resting surface. |
+| Trigger background (hover) | `var(--dsx-color-surface-hover)` | Hover surface. |
+| Trigger background (variant=ghost) | `transparent` | Ghost surface. |
+| Trigger text | `var(--dsx-color-on-surface)` | Trigger label. |
+| Trigger placeholder text | `var(--dsx-color-on-surface-variant)` | Placeholder fill. |
+| Trigger focus border | `var(--dsx-color-primary)` | Focus state. |
+| Trigger focus ring | `var(--dsx-shadow-focus-ring)` | Focus-visible ring. |
+| Trigger error border | `var(--dsx-color-error)` | Invalid state. |
+| Trigger transition | `var(--dsx-motion-duration-fast, 150ms) var(--dsx-motion-easing-standard, ease)` | Trigger transitions. |
+| Trigger icon color | `var(--dsx-color-on-surface-variant)` | Trailing chevron. |
+| Content background | `var(--dsx-color-panel-translucent)` | Floating menu surface. |
+| Content border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Floating menu edge. |
+| Content radius | `var(--dsx-rounded-lg)` | Floating menu corner roundness. |
+| Content padding | `var(--dsx-space-xs)` | Floating menu inner gutter. |
+| Content min-width | `var(--radix-select-trigger-width, 200px)` | Radix CSS var fallback. |
+| Content max-height | `var(--dsx-size-popover-max-width)` | Scroll ceiling (used by the inner ScrollArea). |
+| Content z-index | `var(--dsx-z-index-dropdown)` | Overlay stacking. |
+| Item min-height | `var(--dsx-size-lg)` | Default option height. |
+| Item padding | `var(--dsx-space-sm) var(--dsx-space-sm) var(--dsx-space-sm) calc(var(--dsx-space-lg) + var(--dsx-space-sm))` | Option padding (right side reserves room for the leading check indicator). |
+| Item border | `0` | Items are borderless. |
+| Item radius | `var(--dsx-rounded-md)` | Option corner roundness. |
+| Item background | `transparent` | Resting option surface. |
+| Item text | `var(--dsx-color-on-surface)` | Option label. |
+| Item typography | `var(--dsx-typography-body-medium-*)` | Option label ramp. |
+| Item indicator left | `var(--dsx-space-sm)` | Indicator gutter. |
+| Item indicator size | `var(--dsx-size-md)` | Indicator tile size. |
+| Group label padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Group label gutter. |
+| Group label color | `var(--dsx-color-on-surface-variant)` | Group label fill. |
+| Group label typography | `var(--dsx-typography-caption-font-*, var(--dsx-typography-body-small-font-*))` | Group label ramp. |
+| Hidden select clip | `rect(0, 0, 0, 0)` | Standard visually-hidden clip path. |
+| Motion | `var(--dsx-motion-duration-fast, 150ms) var(--dsx-motion-easing-standard, ease)` | Trigger transitions. |
+
+Rules:
+
+- The CSS does not currently declare per-accent-color rules. The `data-accent-color` attribute is the contract hook; the accent color flows in from the parent `Theme` context through the portal mirroring.
+- The trigger's outline, background, and border colors all track the design tokens; the only intentionally non-token value is the `transparent` background for the `ghost` variant.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| `Select.Trigger` (background, border, box-shadow, color) | `var(--dsx-motion-duration-fast, 150ms) var(--dsx-motion-easing-standard, ease)` | 150ms ease | inherited from the global `prefers-reduced-motion` stylesheet |
+| `Select.Content` open/close | inherited from Radix `Select` (no DS binding) | n/a | inherited from the global stylesheet |
+
+Rules:
+
+- The `Select` runtime does not import `usePrefersReducedMotion` or `MOTION_TRANSITIONS`. The trigger's transition is CSS-only and the content's open/close motion is owned by Radix. Reduced motion is honored at the global stylesheet level, not at the `Select` level.
+
+## Accessibility
+
+**Roles:**
+
+- The trigger renders as a `<button>` with `role="combobox"` (Radix Select sets the role).
+- The content is a `role="listbox"`. Each item is a `role="option"`.
+- The hidden native `<select>` has `aria-hidden="true"` and `tabIndex={-1}`. It is invisible to assistive tech but participates in native form submission and autofill.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to or from the trigger. |
+| `Space`, `Enter` | Opens the menu. |
+| `ArrowDown`, `ArrowUp` | Open the menu and move through the options. |
+| `Home`, `End` | Jump to the first or last option. |
+| `Enter` | Confirms the highlighted option and closes the menu. |
+| `Escape` | Closes the menu and returns focus to the trigger. |
+
+**Focus:**
+
+- The trigger paints a `var(--dsx-shadow-focus-ring)` ring on `:focus-visible` and on `[data-state='open']`. The ring is visible on dark and light surfaces.
+
+**Reduced motion:**
+
+- The trigger's color, background, border, and box-shadow transitions honor the global `prefers-reduced-motion` stylesheet. The component does not introduce its own reduced-motion handling.
+
+**Color and meaning:**
+
+- Selected state is communicated by the leading check icon, the `data-state="checked"` Radix attribute, and the option's `aria-selected`. The trigger's text changes too. Color is not the only signal.
+
+**Naming:**
+
+- The trigger is a `<button>`. Provide an accessible name through the trigger's children, through `Select.Value` (the displayed value is the accessible name), or through an explicit `aria-label`.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Select` with a `Select.Trigger` and a `Select.Content` containing three `Select.Item` rows. Asserts the trigger has `role="combobox"`, `aria-expanded="false"`, the content is hidden until opened, and the trigger's `data-size="md"`, `data-variant="default"`.
+
+**Variant story:**
+
+- Renders one `Select` per `variant` value (`default`, `ghost`). Asserts the matching `data-variant` attribute is set on the trigger.
+
+**Size story:**
+
+- Renders one `Select` per `size` value (`sm`, `md`, `lg`). Asserts the matching `data-size` attribute and the `dsx-select-size-{value}` modifier class.
+
+**State story:**
+
+- Renders `Select` with `open={true}`. Asserts `aria-expanded="true"` on the trigger and that the `listbox` and `option` roles are present.
+- Renders `Select.HiddenSelect` with `name`, `disabled`, and `required`. Asserts the hidden select is in the DOM, has the right attributes, and the option list reflects the `options` prop.
+
+**Composition story:**
+
+- Renders `Select` with `Select.Group`, `Select.ItemGroupLabel`, and `Select.Item` rows. Asserts the group label has the `dsx-select__group-label` class.
+- Renders `Select.Item` with `Select.ValueText` to verify the `dsx-select__item-text` class is applied.
+
+**Token story:**
+
+- Renders the trigger inside a `Theme` wrapper with `mode="light"` and `accentColor="primary"`. Asserts the content portal mirrors the `data-dsx-theme="light"` and `data-accent-color="primary"` attributes when the menu is open.
+- Renders the trigger inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`. The component does not currently paint accent-color rules, so the story asserts the trigger still renders without an accent-color override.
+
+**A11y story:**
+
+- Uses `vitest-axe` against a `Select` whose content is open. Asserts there are no axe violations.
+- Uses `vitest-axe` against a `Select` whose content is closed. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `variant` | select | `default` |
+| `accentColor` | select | `default` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-select`: the full state machine, the trigger / value / item / group / separator / label / item-text parts, the `role="combobox"` and `role="listbox"` semantics, the portal, and the focus return to the trigger on close.
+- `ScrollArea` (DS primitive): the option list viewport. Long option sets scroll inside a token-aligned scroll viewport.
+- `VisuallyHidden` (DS primitive): the hidden native `<select>` host.
+- `Icon` (lucide-react `chevron-down`): the trigger trailing icon. Lucide-react `check` is the item indicator.
+- `_internal/BaseDialog`: `PortalThemeBoundary` (wraps the root) and `PortalThemeWrapper` (wraps the content) so `data-dsx-theme`, `data-dsx-density`, `data-dsx-scaling`, `data-accent-color`, `data-gray-color`, `data-radius`, `data-panel-background`, `data-has-background`, and `colorScheme` resolve inside the content portal.
+- `_internal/baseMenu.css`: the shared menu shell, border, surface, and focus contract.
+- `@radix-ui/react-slot`: enables `asChild` on `Select`, `Select.Trigger`, and `Select.Content`.
+
+**Used by:**
+
+- `DataTable` (per the roster's wiring notes) does not currently import `Select`; the `DataTable` toolbar uses `SearchBar` for the search input.
+- Form rows that need a known-list option picker. Wrap in `Field.Root` for label, description, and error wiring.
+
+**State boundaries:**
+
+- Owned by `Select`: the trigger / content portal, the `data-*` attribute contract, the focus return to the trigger on close, the `data-state` Radix attribute, the option list rendering loop, the hidden native `<select>` for native form submission, and the portal theme mirroring.
+- Owned by Radix: the option list state, the highlight state, the value pipeline, and the keyboard navigation.
+- Owned by the consumer: the value, the option list, the persistence target, the `name` for native submission, the disabled reason, and the form context.
+
+**Boundary rules:**
+
+- App-owned data: the option list (often fetched from a server or a config file), the value, the persistence target, the disabled reason, the form context, and the analytics events.
+- DS-owned visuals: token bindings, the slot classes, the `data-*` attribute contract, the trailing chevron icon, the item check icon, the portal theme mirroring, and the `ScrollArea` viewport.
+
+**Anomalies** (open items that this spec flags for the next promotion):
+
+1. **Ghost variant had no border override; trigger appeared identical to the default variant.** The `.dsx-select__trigger[data-variant='ghost']` rule already existed and correctly set `background: transparent` (confirmed live: computed background genuinely differed from default's opaque surface fill). However, the base `.dsx-select__trigger` rule always sets `border: var(--dsx-border-width-sm) solid var(--dsx-color-outline)` on every trigger regardless of variant, and the ghost variant never cleared it — so ghost and default rendered with an identical visible border, making the only difference (a transparent background) too subtle to register as "ghost" against a similarly-toned page background. This is the actual "no-op" complaint: not literally zero CSS effect, but visually indistinguishable from the default at a glance. FIXED 2026-07-03: added `border-color: transparent` to the ghost rule at the base level (matching the established DS convention elsewhere, e.g. `.dsx-button`'s base rule is `border: var(--dsx-border-width-sm) solid transparent` with variants opting into a visible border color — select's ghost had the inverse default and needed an explicit opt-out). Also added `:hover:not([data-disabled])` (border-color: `var(--dsx-color-outline-variant)`) and `:focus-visible`/`[data-state='open']` (border-color: `var(--dsx-color-outline)`) overrides scoped to `[data-variant='ghost']` so hovering/opening a ghost trigger still shows a border — otherwise the unconditional `border-color: transparent` would have also suppressed the pre-existing focus-ring border (same specificity, ghost rules sit later in the file). The new rules use specificity `(0,3,0)`, verified against `qa_css_selectors.mjs`'s baseline for this file (maxSpecificity: `[0,4,0]`) — no regression.
+
+## 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 Select. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / Select`.
+- **Dimensions**: `auto × auto` (sized by `data-size`).
+- **Layout**: `Flex` (column for the menu, row for the trigger).
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board: Select>
+  ├── <Frame: trigger>
+  │     ├── <Text: value (or placeholder)>
+  │     └── <Icon: chevron-down>
+  └── <Frame: content>
+        ├── <Frame: scroll area>
+        │     └── <Frame: viewport>
+        │           ├── <Frame: group (optional)>
+        │           │     ├── <Text: group label>
+        │           │     └── <Frame: item × N>
+        │           │           ├── <Frame: indicator (when selected)>
+        │           │           └── <Text: item text>
+        │           └── <Frame: item × N>
+        │                 ├── <Frame: indicator (when selected)>
+        │                 └── <Text: item text>
+        └── <Frame: separator (optional)>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Trigger | fill | `--dsx-color-surface` | Color | `fills` |
+| Trigger (ghost) | fill | `transparent` | Color | `fills` (variant) |
+| Trigger (hover) | fill | `--dsx-color-surface-hover` | Color | `fills` (state) |
+| Trigger | stroke | `--dsx-color-outline` | Color | `strokes` |
+| Trigger | radius | `--dsx-rounded-md` | Radius | `radius` |
+| Trigger (focus / open) | 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-panel-translucent` | Color | `fills` |
+| Content | stroke | `--dsx-color-outline` | Color | `strokes` |
+| Content | radius | `--dsx-rounded-lg` | Radius | `radius` |
+| Item | typography | `--dsx-typography-body-medium-*` | Typography | `typography` |
+| Item (selected) | indicator | lucide `check` | Icon | `indicator` |
+| Group label | typography | `--dsx-typography-caption-*` | Typography | `typography` |
+
+### State transformations
+
+| State | Trigger fill | Trigger stroke | Item indicator |
+|---|---|---|---|
+| `default` | `--dsx-color-surface` | `--dsx-color-outline` | hidden |
+| `hover` | `--dsx-color-surface-hover` | `--dsx-color-outline` | hidden |
+| `focus` / `open` | `--dsx-color-surface` | `--dsx-color-primary` | hidden |
+| `disabled` | `--dsx-color-surface` (opacity `--dsx-opacity-disabled`) | `--dsx-color-outline` | hidden |
+| `invalid` | `--dsx-color-surface` | `--dsx-color-error` | hidden |
+| `selected` (item) | n/a | n/a | shown |
+
+### Variant model
+
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `variant`: `default`, `ghost`. Default `default`.
+- `accentColor`: `default`, `primary`. Default `default`.
+- Total members: 3 × 2 × 2 = 12.
+
+### 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.
+- [ ] The hidden native `<select>` is authored as a separate slot, not as a Penpot variant.

package/dist/docs/separator.md

@@ -0,0 +1,249 @@
+---
+title: Separator
+status: canonical
+category: Primitives
+archetype: radix-wrapper
+package_path: packages/d4gger-design-system/src/components/separator/Separator.tsx
+css_path: packages/d4gger-design-system/src/styles/components/separator.css
+props_path: packages/d4gger-design-system/src/components/separator/separator.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Separator.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/layout.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - '@radix-ui/react-separator (Root)'
+---
+
+# Separator
+
+> 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 visual divider between adjacent content. `Separator` renders a Radix `<hr>` or `<span>` based on orientation, with two variants (default and decorative) and three sizes. Use `Separator` only when spacing alone cannot separate two regions.
+
+## Anatomy & slots
+
+**Parent:** `Separator` (no compound; flat export).
+
+**Slots:**
+
+No slots: flat export. The component renders a single Radix `SeparatorPrimitive.Root` host. The host is a horizontal `<hr>` (or vertical `<span>`) with the matching `data-orientation` attribute and the `dsx-separator` root class.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | no | Sets `data-orientation` on the host and the matching CSS rule. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Reserved hook for the `data-size` attribute. The current CSS only uses the orientation attribute to size the line; `data-size` is the contract for future per-size thickness overrides. | no |
+| `variant` | `'default' \| 'decorative'` | `'default'` | no | When `'decorative'`, applies the `dsx-separator--decorative` modifier class. | no |
+| `color` | `string` | `undefined` | no | Free-form accent color name forwarded to `data-accent-color` on the host. | no |
+| `decorative` | `boolean` | `true` | no | Radix boolean: when true, the host is given `role="none"` and removed from the accessibility tree's semantic structure. When false, the host keeps `role="separator"`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-separator`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host. | no |
+
+Rules that apply to this row:
+
+- The component extends `React.ComponentPropsWithoutRef<typeof SeparatorPrimitive.Root>`, so every standard Radix `Separator.Root` attribute is forwarded.
+- `decorative` is the Radix accessibility opt-out. `Separator` defaults to `decorative={true}`; pass `decorative={false}` to expose the separator to assistive tech as a thematic break. The default is intentional: most separators are visual-only and the default should not add noise to the accessibility tree.
+- The CSS file does not yet read `data-size`; the attribute is the public contract for future per-size thickness overrides and is asserted by the test suite.
+
+## CSS class contract
+
+**Root class:** `dsx-separator`
+
+**Modifier classes** (driven by the `variant` prop and the `data-orientation` attribute):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-orientation` | `horizontal`, `vertical` | `.dsx-separator[data-orientation='horizontal']`, `.dsx-separator[data-orientation='vertical']` | `separator.css` |
+| (no attribute) | (presence) | `dsx-separator--decorative` when `variant === 'decorative'` | `separator.css` |
+| `data-size` | `sm`, `md`, `lg` | reserved for future thickness overrides | `separator.css` (no rule yet) |
+| `data-accent-color` | (any accent token name) | reserved for future accent overrides | `separator.css` (no rule yet) |
+
+**Slot classes:** none.
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. The separator is breakpoint-agnostic. Width and height are driven by `data-orientation` and the parent layout.
+
+**Reduced motion:**
+
+- Separator has no motion. No transitions or animations are declared in `separator.css`.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Background (default) | `var(--dsx-control-separator-color-strong)` | Default line color. |
+| Background (decorative) | `var(--dsx-color-separator-muted)` | Muted line color for the `decorative` variant. |
+| Margin block (horizontal) | `var(--dsx-space-sm)` | Vertical breathing room around a horizontal line. |
+| Margin inline (vertical) | `var(--dsx-space-xs)` | Horizontal breathing room around a vertical line. |
+| Border width | `var(--dsx-border-width-md)` (default `var(--dsx-border-width-sm)`) | The painted line thickness. |
+| Min height (vertical) | `var(--dsx-size-lg)` | Minimum line length for the vertical orientation. |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in `separator.css`. The line is a `background` of the host; it is not a border.
+- The default and decorative variants use different tokens. The decorative token is intentionally lighter; the default token is the strong control line color.
+- Alpha is not used. The line colors are solid.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | `none` | `none` | `none` |
+
+Rules:
+
+- Separator has no motion. The motion section is intentionally empty.
+- A future motion addition (for example, a horizontal wipe on layout transition) should pick a `MOTION_TRANSITIONS` preset by name and gate it with `usePrefersReducedMotion`.
+
+## Accessibility
+
+**Roles:**
+
+- The host is a Radix `SeparatorPrimitive.Root`. When `decorative` is true (the default), the host is a `<div>` with `role="none"` and `data-orientation`; the host has no semantic role in the accessibility tree. When `decorative` is false, the host keeps `role="separator"` and (for vertical orientation only) `aria-orientation="vertical"`.
+
+**Keyboard:**
+
+- Separator is not interactive. No keyboard contract beyond the page-level Tab order. The host is not focusable.
+
+**Focus:**
+
+- Separator has no interactive surface. The host does not show a focus ring and is removed from the Tab order.
+
+**Reduced motion:**
+
+- N/A. Separator has no motion.
+
+**Color and meaning:**
+
+- The separator is a visual divider, not a state. Color changes between `default` and `decorative` are a tone change, not a state change, and they do not carry meaning.
+
+**Naming:**
+
+- The separator does not need an accessible name. The Radix primitive handles `aria-hidden` and `role` based on `decorative`. Pair a non-decorative separator with surrounding landmarks (headings, sections) so the thematic break is announced in context.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Separator`. Asserts the host has `dsx-separator`, `data-orientation="horizontal"`, and `role="none"` (the default `decorative` flag strips the semantic role from the accessibility tree).
+
+**Orientation story** (one per orientation):
+
+- Renders Separator with `orientation="horizontal"` and `orientation="vertical"`. Asserts the matching `data-orientation` attribute and the matching CSS rule (width vs height).
+
+**Size story** (one per size):
+
+- Renders Separator with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` value on the host. The current CSS does not switch the painted thickness per size; the story documents that the attribute is the contract for future overrides.
+
+**Variant story** (one per variant):
+
+- Renders Separator with `variant="default"` and `variant="decorative"`. Asserts the `dsx-separator--decorative` modifier class is present on the decorative variant and absent on the default.
+
+**State story:**
+
+- Renders Separator with `decorative={false}`. Asserts the host has `role="separator"` instead of `role="none"`. For a non-decorative vertical separator, asserts `aria-orientation="vertical"` is also on the host.
+
+**Composition story:**
+
+- Renders Separator inside a `Flex` row to verify the vertical orientation has a meaningful min height and does not collapse to zero.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the line color is unchanged across accents (the current CSS does not read `data-accent-color`; the story documents the contract for future accent overrides).
+
+**A11y story:**
+
+- Uses `vitest-axe` against a rendered default Separator. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `orientation` | select (`horizontal`, `vertical`) | `horizontal` |
+| `size` | select (`sm`, `md`, `lg`) | `md` |
+| `variant` | select (`default`, `decorative`) | `default` |
+| `color` | text | (empty) |
+| `decorative` | boolean | `true` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-separator` (`Root`): provides the `aria-hidden` toggle, the `<hr>` vs `<span>` host swap, and the `aria-orientation` reflection for non-decorative separators.
+
+**Used by:**
+
+- `Breadcrumb.Separator` (composite breadcrumb trail): the visual divider between breadcrumb items.
+- `InputOtp.Separator` (composite verification-code input): the visual break between digit groups.
+- `Stepper.Separator` (composite multi-step wizard): the visual break between step indicators.
+- `Toolbar.Separator` (composite toolbar strip): the visual break between toolbar groups.
+- `Command.Separator` (composite command palette): the visual break between command groups.
+- `DropdownMenu.Separator`, `ContextMenu.Separator`, `Menubar.Separator`: the visual break between menu groups.
+
+**State boundaries:**
+
+- Owned by Separator: the `dsx-separator` root class, the `data-orientation` and `data-size` attributes, the variant modifier class, and the Radix `aria-hidden` toggle.
+- Owned by the consumer: the orientation, size, variant, color, decorative flag, and surrounding layout.
+
+**Boundary rules:**
+
+- App-owned data: the orientation choice, the variant choice, and the decorative flag.
+- DS-owned visuals: token bindings for the line color (default and decorative), the line thickness, and the spacing margins.
+
+## 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 Separator. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Primitives / Separator`.
+- **Dimensions**: `240 × 1` (horizontal default).
+- **Layout**: `Fixed`.
+- **Sizing**: `horizontalSizing = '100%'`, `verticalSizing = 'fix'`.
+
+### Layer tree
+
+```
+<Root Board: Separator / horizontal / default>
+  └── <Frame: line (background, height = border-width)>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Line (default) | fill | `--dsx-control-separator-color-strong` | Color | `fills` |
+| Line (decorative) | fill | `--dsx-color-separator-muted` | Color | `fills` (state) |
+| Line | height | `--dsx-border-width-md` (default `sm`) | Sizing | `size` |
+
+### State transformations
+
+| State | Line fill | Spacing |
+|---|---|---|
+| `default` | `--dsx-control-separator-color-strong` | `--dsx-space-sm` block, `0` inline |
+| `decorative` | `--dsx-color-separator-muted` | `--dsx-space-sm` block, `0` inline |
+| `vertical` | `--dsx-control-separator-color-strong` | `0` block, `--dsx-space-xs` inline |
+
+### Variant model
+
+- `orientation`: `horizontal`, `vertical`. Default `horizontal`.
+- `size`: `sm`, `md`, `lg`. Default `md`. Reserved for future thickness overrides.
+- `variant`: `default`, `decorative`. Default `default`.
+- `decorative`: `true`, `false`. Default `true`.
+- Total members: 24 (2 × 3 × 2 × 2).
+
+### 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.
+- [ ] The default `decorative={true}` removes the separator from the accessibility tree; document the opt-out flag.
+- [ ] The `data-size` attribute is always written; today's CSS does not switch the painted thickness per size.