@d4gger/design-system 2.7.0 → 3.0.1

package/dist/docs/components/segmented-control.md

@@ -0,0 +1,258 @@
+---
+title: SegmentedControl
+status: canonical
+category: Components
+archetype: composite
+depends_on:
+  - ToggleGroup
+---
+
+# SegmentedControl
+
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+
+## Purpose
+
+A single-select control that renders a row of mutually exclusive options, backed by `ToggleGroup` from Radix. `default` is a sunken track with a sliding softly tinted raised pill behind the active option; `outline` is the same pill inside an outer frame; `subtle` is the borderless treatment with the same selected pill. Used for switching between views, filters, or modes in forms and toolbars. Boundary rule (F6 brief): exclusive single-select with a thumb is always a SegmentedControl; frameless toolbar button clusters without a thumb are `ToggleGroup`. Never multi-select, never dismissible.
+
+## Anatomy & slots
+
+**Parent:** `SegmentedControl` (alias of `SegmentedControl.Root`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `SegmentedControl.Root` | `ToggleGroupPrimitive.Root` | Radix ToggleGroup root + class | Single-select container. Writes `data-size`, `data-variant`, `data-activation-mode`, `data-disabled`. Renders the selected indicator pill as its last child. |
+| `SegmentedControl.Item` | `ToggleGroupPrimitive.Item` | Radix ToggleGroup item + class | Individual option. Writes `data-state` (`on`/`off`), `data-disabled`, and opt-in `data-icon-only`. Accepts composed rich content with `space-xs` rhythm. |
+| Indicator | `span.dsx-segmented-control__indicator` | Measured wrapper for the raised pill behind the active item | `aria-hidden="true"`. Positioned by inline `transform: translateX()` + `width` from the root measure pass; its `::before` paint layer is inset by `space-2xs` on every side so edge selections clear the track frame. Not a public slot. |
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height and item padding; writes `data-size` and `dsx-segmented-control--{size}` class. | no |
+| `variant` | `'default' \| 'outline' \| 'subtle'` | `'default'` | no | Container surface treatment; writes `data-variant` and `dsx-segmented-control--{variant}` class. `subtle` keeps the measured selected pill but removes the track surface and frame. | no |
+| `activationMode` | `'manual' \| 'automatic'` | `'manual'` | no | Selection timing; writes `data-activation-mode`. `manual` selects only on activation (click, `Enter`, `Space`). `automatic` selects on item focus, so arrow-key navigation selects without `Enter`. | no |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | no | Stacking axis; writes `data-orientation`. Vertical stacks icon columns (ref: view-switcher rails); the sliding indicator measures y/height and arrow keys move up/down via Radix. | no |
+| `disabled` | `boolean` | `false` | no | Disables the entire control; writes `data-disabled`. | no |
+| `fill` | `boolean` | `false` | no | Distributes the track width equally across items; writes `data-fill` and `dsx-segmented-control--fill`; both selectors share the same fill styling. Opt-in for few-item groups that fit (method pickers); the default hug-content root with scroll containment stays for overflowing groups. The sliding indicator measures live boxes, so it tracks fill widths with no change. | no |
+| `value` | `string` | `undefined` | no | Controlled selected value. | no |
+| `defaultValue` | `string` | `undefined` | no | Uncontrolled initial selected value. | no |
+| `onValueChange` | `(value: string) => void` | `undefined` | no | Callback when the selected value changes. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-segmented-control`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | `SegmentedControl.Item` children. | no |
+
+**SegmentedControl.Item props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `string` | — | yes | Unique value for this item. | no |
+| `iconOnly` | `boolean` | `false` | no | Declares an icon-only item and gives it a square hit target. Requires an accessible name. | no |
+| `disabled` | `boolean` | `undefined` | no | Disables this item. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-segmented-control__item`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Item label content. Accepts composed rich content (icon, status dot, count badge, tag); items lay children out with `gap: var(--dsx-space-xs)` and icons never shrink. | no |
+
+Rules:
+
+- `size` and `disabled` are wired through `extractProps` and the prop def bag on the Root. `variant`, `activationMode`, and `fill` are destructured with their defaults and kept out of the extract bag (their defs declare no `className`, so they would otherwise leak onto the DOM); `fill` writes `data-fill` plus the `--fill` modifier class manually, same as `variant`.
+- `value`, `defaultValue`, and `onValueChange` are passed through to the Radix ToggleGroup root directly.
+- The Root forces `type="single"` and filters empty string values from `onValueChange` to prevent deselection.
+- Deselect guard: the Root owns the selection state. Uncontrolled usage seeds internal state from `defaultValue` and passes the resolved value back into Radix as a controlled `value`, so clicking the active item (which fires `""`) can never clear Radix internal state or render the control with no active item. Controlled usage passes `value` straight through; `""` is still swallowed.
+- Activation mode: in `automatic` mode each item's `onFocus` selects its own value when it differs from the current value (the item reads the mode and the current selection from an internal Root context; Radix strips the `value` prop from the DOM, so the Root cannot recover the focused value from the event target). The focus value goes through the same guarded setter, so focus can never empty the selection and tabbing into the group (which lands on the already-selected item) is a no-op. Disabled items never select on focus. In `manual` mode (default) focus never selects; selection happens only on activation. Consumer `onFocus` handlers on the Root and on items keep working in both modes.
+- Choosing a mode: `automatic` is the radio-faithful choice for lightweight view/filter/mode switching. `manual` is required when `onValueChange` drives expensive side effects (network requests, navigation, heavy recompute) that must not fire on focus or hover.
+- Indicator geometry: the Root measures the active `[data-state="on"]` item with `getBoundingClientRect` in a layout effect (before first paint), re-measures on selection change and via `ResizeObserver` on the root and the active item. The offset is a physical-pixel diff (`active.left - root.left`), which is direction-agnostic and therefore RTL-correct without special-casing. A ready gate holds `transition: none` until the first positioned frame so mount never animates from the origin. Variable-width items are required; the indicator wrapper tracks each item's own width (no equal-width `nth-child` CSS), while its painted `::before` surface keeps a symmetric `space-2xs` inset inside that measured wrapper.
+
+## CSS class contract
+
+**Root class:** `dsx-segmented-control`
+
+**Modifier classes** (driven by `data-*` attributes and class names written by the component):
+
+| Attribute / Class | Allowed values | CSS selector | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-segmented-control--sm`, `.dsx-segmented-control--md`, `.dsx-segmented-control--lg` | `segmented-control.css` |
+| `data-variant` | `default`, `outline`, `subtle` | `.dsx-segmented-control--default`, `.dsx-segmented-control--outline`, `.dsx-segmented-control--subtle` | `segmented-control.css` |
+| `data-disabled` | (present/absent) | `.dsx-segmented-control[data-disabled]` | `segmented-control.css` |
+| `data-orientation` | `horizontal`, `vertical` | `.dsx-segmented-control[data-orientation='vertical']` (column stack; indicator measures y/height) | `segmented-control.css` |
+| `data-fill` | (present/absent) | `.dsx-segmented-control--fill` (root spans the container, items share width equally) | `segmented-control.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `SegmentedControl.Root` | `dsx-segmented-control` | `segmented-control.css` |
+| `SegmentedControl.Item` | `dsx-segmented-control__item` | `segmented-control.css` |
+| Indicator | `dsx-segmented-control__indicator` | `segmented-control.css` |
+
+**Selector note:**
+
+- Every item uses the same inset-corrected pill radius as the selected indicator, so hover and keyboard focus trace the same shape at every position.
+
+**Responsive behavior:**
+
+- The component does not write viewport `@media` rules. Size and variant are single-value only.
+- The component writes one `@media (prefers-reduced-motion: reduce)` rule that sets the indicator transition to `none`.
+
+**Reduced motion:**
+
+- The indicator pill animates `transform` and `width` with `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`, gated by an explicit `@media (prefers-reduced-motion: reduce) { transition: none }` rule.
+- Item transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)` for background-color and color; the token values collapse to `0` under the global reduced-motion override. Focus ring paint is intentionally immediate and never interpolated.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Container background | `var(--dsx-color-surface-sunken)` | Sunken well; the track recedes, the pill comes forward |
+| Container border | `var(--dsx-boundary-control-width)` with a transparent color, except `outline` which paints `var(--dsx-boundary-control-color)` | Geometry preserved everywhere; only `outline` paints an outer frame |
+| Container radius | `var(--dsx-grouped-radius, var(--dsx-rounded-md))` | Container roundness |
+| Outline dividers | none | Dividers removed: they clipped against the frame and broke rhythm around selection; `outline` is frame-only |
+| Item text color | `var(--dsx-color-on-surface-variant)` | Unselected item label |
+| Item selected background | `transparent` (surface moved to the indicator pill) | Selected item keeps the label color only |
+| Item selected text | `var(--dsx-color-accent-indicator)` | Readable accent text on the pale pill — a raw accent-9 fails contrast on bright accents (spark); indicator is the ramp step designed for text on tints |
+| Indicator surface | `linear-gradient(var(--dsx-effect-pressed-layer), var(--dsx-effect-pressed-layer)), var(--dsx-control-active-background)` | Theme-aware raised surface with a soft accent wash; visibly selected without becoming a solid accent button |
+| Indicator shadow | `var(--dsx-effect-shadow-2)` | Clear pill elevation in light and dark themes; no selected outline, so the focus ring remains unambiguous |
+| Indicator radius | `max(0px, calc(grouped - space-2xs))` | Inset-corrected roundness so the pill never crosses the track corners |
+| Indicator inset | `var(--dsx-space-2xs)` on every side | Symmetric clearance between the selected paint and the track or outline frame |
+| Item hover | `var(--dsx-effect-hover-ghost)` + `var(--dsx-color-primary)` | Pointer-local transient state on an unselected item |
+| Icon-only rhythm | matching density control height via `data-icon-only` | Explicit square hit target at every size |
+| Subtle container | `transparent` (background, border, shadow all cleared) | Borderless track; segments float on the parent surface |
+| Subtle selected fill | Same theme-aware softly tinted indicator surface as the other variants | Keeps selection visible on a transparent track, including icon-only composition |
+| Subtle selected text | `var(--dsx-color-accent-indicator)` | Same readable-accent rule as the pill variants |
+| Item gap | `var(--dsx-space-xs)` | Rhythm between composed children (icon, dot, badge, tag) |
+| Focus ring | `var(--dsx-shadow-focus-ring)` | Focus indicator |
+| Disabled opacity | `var(--dsx-opacity-disabled)` | Disabled fade |
+| Item padding (sm) | `var(--dsx-space-sm)` | Small item horizontal padding |
+| Item padding (md) | `var(--dsx-space-md)` | Default item horizontal padding |
+| Item padding (lg) | `var(--dsx-space-lg)` | Large item horizontal padding |
+| Height (sm) | `var(--dsx-density-control-height-sm, var(--dsx-size-lg))` | Small control height |
+| Height (md) | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Default control height |
+| Height (lg) | `var(--dsx-density-control-height-lg, var(--dsx-size-2xl))` | Large control height |
+| Typography | `var(--dsx-typography-label-large-*)`, `var(--dsx-typography-label-small-*)` | Item label type ramp |
+| Transition duration | `var(--dsx-motion-duration-fast, 150ms)` | Item transition speed |
+| Transition easing | `var(--dsx-motion-easing-standard, ease)` | Item transition curve |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Indicator pill slide/resize | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` on `transform, width` | `150ms` ease | `transition: none` via `@media (prefers-reduced-motion: reduce)` |
+| Item background/color transition | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | `150ms` ease | Global `prefers-reduced-motion` override via token layer; focus ring paint is immediate |
+
+## Accessibility
+
+**Roles:**
+
+- `group` (Radix ToggleGroup root). Each item is a `radio` role within the group.
+
+**Keyboard:**
+
+Manual mode (`activationMode="manual"`, default):
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to / from the control. |
+| `Arrow Left`, `Arrow Right` | Moves focus between items; selection is unchanged. |
+| `Space`, `Enter` | Selects the focused item. |
+
+Automatic mode (`activationMode="automatic"`):
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to / from the control. Tabbing in lands on the selected item, so selection is unchanged. |
+| `Arrow Left`, `Arrow Right` | Moves focus between items and selects the newly focused item. `Enter` is unnecessary. |
+| `Space`, `Enter` | No-op on the already-selected item (re-activation is swallowed by the deselect guard). |
+
+**Focus:**
+
+- Keyboard focus uses `box-shadow: var(--dsx-shadow-focus-ring)` on the focused item through `:focus-visible`, so pointer clicks do not add a focus ring.
+- Pointer hover is local to the hovered unselected item and never moves or duplicates the selected pill.
+- Selection and focus remain separate signals: the indicator owns fill and elevation, while the item owns the focus ring. SegmentedControl is the explicit exception to the general selected-boundary rule in `DESIGN.md`.
+
+**Reduced motion:**
+
+- The indicator pill disables its slide/resize transition under `prefers-reduced-motion` via an explicit CSS gate.
+- Item transitions collapse when the global reduced-motion token override sets durations to `0`.
+
+**Decorative nodes:**
+
+- The indicator pill is `aria-hidden="true"` and pointer-transparent; it carries no semantics and never intercepts input.
+
+**Color and meaning:**
+
+- Selected state is communicated by elevation + fill + text color, not by color alone. Focus is communicated by the shared focus ring and is the only outline on a segment.
+
+**Naming:**
+
+- The Root requires an `aria-label` or `aria-labelledby` to name the group.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `SegmentedControl` with three items and `defaultValue="day"`. Asserts the root class is `dsx-segmented-control`, `data-size="md"`, and `data-variant="default"`. The indicator pill renders behind the selected item in every story that sets a value; no fixture change was needed.
+
+**Size story:**
+
+- Renders with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute and `dsx-segmented-control--{size}` class.
+
+**Variant story:**
+
+- Renders with `variant="default"`, `variant="outline"`, and `variant="subtle"`. Asserts the matching `data-variant` attribute and `dsx-segmented-control--{variant}` class. In `subtle`, the container is transparent and borderless while the measured raised pill remains the selected signal.
+
+**Subtle composition story:**
+
+- Renders `variant="subtle"` rows: explicit `iconOnly` appearance controls, icon + label + status dot (views), counts (tasks with badges), and an affixed tag (billing with promo). The selected segment uses the same measured fill/elevation indicator as the other variants. Hover stays local to the pointed item and focus uses `:focus-visible`.
+
+**State story:**
+
+- Renders with `disabled={true}`. Asserts `data-disabled` is present and items are not interactive.
+
+**Activation-mode story:**
+
+- Renders Manual (`activationMode="manual"`, the default) and Automatic (`activationMode="automatic"`) side by side with the same Day/Week/Month values. In manual, arrows move focus without selecting; `Enter` selects. In automatic, arrows select without `Enter`. Asserts the root writes the matching `data-activation-mode`.
+
+**Composition story:**
+
+- Renders with each `SegmentedControl.Item` populated. Asserts each item renders with `dsx-segmented-control__item` class and the selected item has `data-state="on"`.
+
+**Token story:**
+
+- Renders inside `Theme` wrappers with alternate accents. SegmentedControl inherits the ambient accent: selected label, focus ring, and soft indicator wash follow it without requiring a component-level accent prop.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default control. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `variant` | select | `default` |
+| `activationMode` | select | `manual` |
+| `disabled` | boolean | `false` |
+| `fill` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-toggle-group`: provides the single-select toggle group semantics and keyboard navigation.
+
+**Used by:**
+
+- `ThemePanel`: theme configuration panel uses SegmentedControl for density and mode switching.
+- `ConfigDrawer`: app-config drawer uses SegmentedControl for setting groups.
+
+**State boundaries:**
+
+- Owned by SegmentedControl: the selected value, the `data-size`, `data-variant`, `data-activation-mode`, `data-disabled` attributes, the CSS classes, and the indicator pill geometry (measured offsets, never consumer-provided).
+- Owned by the consumer: the item values, the item labels, the controlled/uncontrolled value, and the `onValueChange` callback.
+
+**Boundary rules:**
+
+- App-owned data: the item values and labels, the selection state semantics.
+- DS-owned visuals: token bindings, slot classes, motion presets, and the container/item layout.

package/dist/docs/{segmented-meter.md → components/segmented-meter.md}

@@ -3,19 +3,12 @@ title: SegmentedMeter
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/segmentedMeter/SegmentedMeter.tsx
-css_path: packages/d4gger-design-system/src/styles/components/segmented-meter.css
-props_path: packages/d4gger-design-system/src/components/segmentedMeter/segmentedMeter.props.ts
-test_path: packages/d4gger-design-system/src/test/components/SegmentedMeter.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # SegmentedMeter
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{select.md → components/select.md}

@@ -3,25 +3,16 @@ 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -37,12 +28,13 @@ A controlled option picker for known, medium-sized lists. Pairs the Radix Select
 |---|---|---|---|
 | `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.Value` | `@radix-ui/react-select` `Value` inside a styled span | `dsx-select__value` on the outer single-line text slot | The displayed value. Honors `placeholder` when no value is selected; the wrapper preserves ellipsis styling because Radix drops `className` on `Value`, and mirrors the rendered text into `title` (kept in sync with a MutationObserver) so ellipsized long values stay discoverable on hover. |
+| `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. `popper` is the default so the panel aligns to the trigger start edge and mirrors the trigger width at minimum (`min-width: trigger-width`), growing to fit long option content up to the available viewport width (`width: max-content`, capped by `--radix-select-content-available-width`); `item-aligned` remains available for native-menu-style alignment. |
 | `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.Item` | `@radix-ui/react-select` `Item` | `dsx-select__item` (the row), `dsx-select__item-indicator` (the trailing check slot), `dsx-select__item-text` (the single-line text container rendered through `ItemText asChild`) | A single option. The trailing check appears only when the item is the selected value. Rows that fit stay single-line ellipsis; a row whose text exceeds the row box latches `data-overflow` (ResizeObserver, one-way) and wraps to a second line so the full text stays visible with the highlight spanning the full row. |
+| `Select.ItemMedia` | plain `<div>` | `dsx-select__item-media` | Optional leading media slot inside `Select.Item` (avatar, checkbox, icon). Fixed `size-lg` box, centered, non-shrinking; the row `gap` separates it from the text. `Select.Item` partitions media out of the text flow so it stays a direct flex child (and out of the trigger value display). |
 | `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. |
@@ -54,8 +46,8 @@ A controlled option picker for known, medium-sized lists. Pairs the Radix Select
 | 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 |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Trigger density. Writes `data-size` on `Select.Trigger` and `Select.Content` and resolves the `dsx-select-size-{sm,md,lg}` modifier class (scoped to the trigger in CSS). The panel renders one row spec at every size — `size` changes trigger height and trigger type only. | no |
+| `variant` | `'default' \| 'ghost' \| 'vision'` | `'default'` | no | Trigger / content variant. Writes `data-variant`. `vision` is the direction-3 reference copy (12px panel, 40px rows, neutral wash, plain checks, sentence-case labels); the trigger keeps the default chrome. | 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 |
 
@@ -83,7 +75,7 @@ When `asChild` is set, the trigger renders only the children. The trailing chevr
 | `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 |
+| `position` | `'item-aligned' \| 'popper'` | `'popper'` | no | Radix positioning mode. `popper` magnetizes under the trigger at trigger width with `sideOffset={4}` (the DS default — matches dropdown/combobox behavior); `item-aligned` is the native-macOS-menu mode that aligns to the active item. | 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 |
@@ -118,7 +110,7 @@ Rules:
 
 | 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-size` | `sm`, `md`, `lg` | `.dsx-select__trigger[data-size='sm'\|'md'\|'lg']` min-height, padding, and type; `.dsx-select-size-{sm,md,lg}` (trigger-scoped; the class also lands on content via prop extraction but has no panel-side rules). Panel rows are size-invariant by design. | `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` |
@@ -136,6 +128,7 @@ Rules:
 | `Select.Item` | `dsx-select__item` | `select.css` |
 | Item indicator | `dsx-select__item-indicator` | `select.css` |
 | Item text | `dsx-select__item-text` | `select.css` |
+| `Select.ItemMedia` | `dsx-select__item-media` | `select.css` |
 | `Select.Group` | (no DS class) | n/a |
 | `Select.ItemGroupLabel` | `dsx-select__group-label` | `select.css` |
 | `Select.Label` | `dsx-select__label` | `select.css` |
@@ -159,12 +152,12 @@ 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 min-height (md) | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Default control height. |
+| Trigger min-height (sm) | `var(--dsx-density-control-height-sm, var(--dsx-size-lg))` | Small control height. |
+| Trigger min-height (lg) | `var(--dsx-density-control-height-lg, var(--dsx-size-2xl))` | Large control height. |
+| Trigger padding (md) | density `control-padding-*` tokens | Default control padding. |
+| Trigger padding (sm) | density `control-padding-*-sm` tokens | Small control padding. |
+| Trigger padding (lg) | density `control-padding-*-lg` tokens | 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. |
@@ -180,18 +173,18 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | 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 padding | `var(--dsx-space-sm)` | Floating menu inner gutter. |
+| Content width / min-width / max-width | `max-content` / `var(--radix-select-trigger-width, 200px)` / `min(--radix-select-content-available-width, 40rem)` | Mirror-at-minimum with grow-to-fit; past 40rem (or the viewport edge) rows wrap via `data-overflow` instead of stretching the panel. The 40rem ceiling is a token candidate for the size batch. |
 | 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. |
+| Content z-index | `var(--dsx-z-index-dropdown)` standalone; `calc(var(--dsx-z-index-modal, 90) + 2)` when nested inside a modal-tier host (`dsx-menu__nested`, see the shared nested floating tier contract in `menu.md`) | Overlay stacking; nested menus clear their host popup. |
 | 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 padding | density-aware block/inline tokens with trailing indicator reservation | Option padding; the right side reserves room for the trailing 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 right | `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. |
@@ -244,7 +237,7 @@ Rules:
 
 **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.
+- Selected state is communicated by the trailing 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:**
 
@@ -258,7 +251,7 @@ Rules:
 
 **Variant story:**
 
-- Renders one `Select` per `variant` value (`default`, `ghost`). Asserts the matching `data-variant` attribute is set on the trigger.
+- Renders one `Select` per `variant` value (`default`, `ghost`, `vision`). Asserts the matching `data-variant` attribute is set on the trigger and portalled content.
 
 **Size story:**
 
@@ -273,6 +266,7 @@ Rules:
 
 - 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.
+- Renders `Select.Item` with `Select.ItemMedia` (avatar/checkbox) to verify the `dsx-select__item-media` class is applied and the row keeps single-line ellipsis.
 
 **Token story:**
 
@@ -301,7 +295,8 @@ Rules:
 - `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.
+- `_internal/baseMenu.css`: the shared menu shell, border, surface, and focus contract — including the nested floating tier rule (`dsx-menu__nested` at `modal + 2`).
+- `_internal/floatingLayer`: `useFloatingLayerHost` tells `Select.Content` whether it renders inside a modal-tier host (`Popover.Content` / `Dialog.Content`); when nested, the content adds `dsx-menu__nested` so the options list paints above its host. Standalone content never carries the class and stays at the dropdown tier, below the modal overlay.
 - `@radix-ui/react-slot`: enables `asChild` on `Select`, `Select.Trigger`, and `Select.Content`.
 
 **Used by:**

package/dist/docs/{separator.md → components/separator.md}

@@ -3,20 +3,13 @@ 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{shared.md → components/shared.md}

@@ -3,17 +3,12 @@ title: Shared
 status: canonical
 category: Foundations
 archetype: utility
-package_path: packages/d4gger-design-system/src/foundations/Shared.tsx
-test_path: packages/d4gger-design-system/src/test/foundations/Shared.test.ts
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/utility.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Shared
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -40,7 +35,7 @@ No slots: flat module export. Shared does not render any host element. It export
 | `ShadowTone` | type union | `'none' \| '1' \| '2' \| '3' \| '4' \| '5' \| '6' \| 'gold' \| 'gold-strong'`. |
 | `TextTone` | type union | `'default' \| 'muted' \| 'primary' \| 'secondary' \| 'success' \| 'error'`. |
 | `PolymorphicProps<T, OwnProps>` | generic type | `OwnProps & { as?: T; asChild?: boolean; children?: React.ReactNode; className?: string; style?: React.CSSProperties } & Omit<React.ComponentPropsWithoutRef<T>, keyof OwnProps \| 'as' \| 'asChild' \| 'children' \| 'className' \| 'style'>`. The canonical polymorphic prop bag for the foundations and the layout primitives. |
-| `withVars(style, vars)` | function | Merges a `React.CSSProperties` object with a `--*` CSS custom property map. Returns a typed `StyleWithVars` (a `React.CSSProperties` extended with `--*` keys). |
+| `withVars(style, vars)` | function | Merges a `React.CSSProperties` object with a `--*` CSS custom property map. Returns a typed `StyleWithVars` (a `React.CSSProperties` extended with `--*` keys). Precedence: `style` wins over `vars` on conflict — an entry in `style` overrides the same key in `vars`. |
 | `resolveSpace(token?)` | function | Returns `'0px'` for `'none'`, `var(--dsx-space-{token})` for numeric and named tokens, or the raw value for arbitrary input. Returns `undefined` when no token is supplied. |
 | `resolveRadius(token?)` | function | Returns `'0px'` for `'none'`, `var(--dsx-rounded-{token})` for known tokens, or the raw value. Returns `undefined` when no token is supplied. |
 | `resolveSurface(tone?)` | function | Returns `undefined` for `undefined` or `'transparent'`, otherwise `var(--dsx-color-{tone})`. |