@d4gger/design-system 2.7.0 → 3.0.1

package/dist/docs/{checkbox-cards.md → components/checkbox-cards.md}

@@ -3,11 +3,6 @@ title: CheckboxCards
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/checkboxCards/CheckboxCards.tsx
-css_path: packages/d4gger-design-system/src/styles/components/checkbox-cards.css
-props_path: packages/d4gger-design-system/src/components/checkboxCards/checkboxCards.props.ts
-test_path: packages/d4gger-design-system/src/test/components/CheckboxCards.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - Checkbox (Radix `@radix-ui/react-checkbox`; the `Item` slot wraps `CheckboxPrimitive.Root` and is the source of the `data-state='checked'` attribute)
   - Card (token-aligned surface; the `Item` reuses the `dsx-card` surface tokens through the `baseCard.css` import)
@@ -17,7 +12,7 @@ depends_on:
 
 # CheckboxCards
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{checkbox-group.md → components/checkbox-group.md}

@@ -3,13 +3,6 @@ title: CheckboxGroup
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/checkboxGroup/CheckboxGroup.tsx
-css_path: packages/d4gger-design-system/src/styles/components/checkbox-group.css
-props_path: packages/d4gger-design-system/src/components/checkboxGroup/checkboxGroup.props.ts
-test_path: packages/d4gger-design-system/src/test/components/CheckboxGroup.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/forms.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Checkbox
   - Field
@@ -18,7 +11,7 @@ depends_on:
 
 # CheckboxGroup
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

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

@@ -3,20 +3,13 @@ title: Checkbox
 status: canonical
 category: Primitives
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/checkbox/Checkbox.tsx
-css_path: packages/d4gger-design-system/src/styles/components/checkbox.css
-props_path: packages/d4gger-design-system/src/components/checkbox/checkbox.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Checkbox.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:
   - Icon
 ---
 
 # Checkbox
 
-> 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
 
@@ -90,6 +83,10 @@ Rules:
 
 - The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`.
 
+**Hit area:**
+
+- The visual box stays 20/24/32px per `size`, but a `::before` layer extends the pointer target to 44px (WCAG 2.5.8 minimum 24px, TMA touch 44px). Absolutely positioned — never affects layout.
+
 **Reduced motion:**
 
 - The `transition` properties on `dsx-checkbox` collapse to `none` when `@media (prefers-reduced-motion: reduce)` matches. The rule is in `checkbox.css`.

package/dist/docs/{code-input.md → components/code-input.md}

@@ -3,13 +3,6 @@ title: CodeInput
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/codeInput/CodeInput.tsx
-css_path: packages/d4gger-design-system/src/styles/components/code-input.css
-props_path: packages/d4gger-design-system/src/components/codeInput/codeInput.props.ts
-test_path: packages/d4gger-design-system/src/test/components/CodeInput.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:
   - Field
   - InputGroup

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

@@ -3,19 +3,12 @@ title: Code
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/code/Code.tsx
-css_path: packages/d4gger-design-system/src/styles/components/code.css
-props_path: packages/d4gger-design-system/src/components/code/code.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Code.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/typography.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Code
 
-> 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
 
@@ -33,7 +26,7 @@ No slots: flat export. The component renders a single `<code>` host element (or
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'solid' \| 'soft' \| 'outline' \| 'ghost'` | `'soft'` | no | Code treatment. Writes the `dsx-code--{variant}` modifier class and the `data-variant` attribute. `solid` paints a primary background; `soft` paints a raised surface with an outline; `outline` paints a transparent background with an inset outline; `ghost` paints nothing. | no |
+| `variant` | `'solid' \| 'soft' \| 'outline' \| 'ghost'` | `'soft'` | no | Code treatment. Writes the `dsx-code--{variant}` modifier class and the `data-variant` attribute. `solid` paints a primary background; `soft` paints a sunken surface with an outline; `outline` paints a transparent background with an inset outline; `ghost` paints nothing. | no |
 | `tone` | `'default' \| 'muted' \| 'inverse'` | `'default'` | no | Tone modifier. Writes `dsx-code--{tone}` for `muted` and `inverse`. The CSS combines `dsx-code--solid.dsx-code--muted` and `dsx-code--soft.dsx-code--inverse` for tone-on-variant pairings. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Code cap size. Writes the `data-size` attribute. | no |
 | `color` | `string` | `undefined` | no | Free-form accent color. Writes the `data-accent-color` attribute. The component is not opinionated about the value; consumers that pass it get the `data-accent-color` attribute for downstream CSS targeting. | no |
@@ -81,14 +74,14 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Property | Token | Role |
 |---|---|---|
-| Font family | `'JetBrains Mono', 'Fira Code', 'SF Mono', monospace` (hard-coded fallback) | Monospace stack. |
-| Font size | `var(--dsx-typography-code-font-size, 0.875em)` | Default code size. |
-| Font weight | `var(--dsx-typography-code-font-weight, 400)` | Code weight. |
-| Line height | `var(--dsx-typography-code-line-height, 1.25)` | Code rhythm. |
-| Letter spacing | `var(--dsx-typography-code-letter-spacing, -0.01em)` | Code tracking. |
+| Font family | `var(--dsx-typography-code-font-family)` | Monospace stack (token-backed; see rules). |
+| Font size | `var(--dsx-typography-code-font-size)` | Default code size. |
+| Font weight | `var(--dsx-typography-code-font-weight)` | Code weight. |
+| Line height | `var(--dsx-typography-code-line-height)` | Code rhythm. |
+| Letter spacing | `var(--dsx-typography-code-letter-spacing)` | Code tracking. |
 | Border radius | `var(--dsx-rounded-sm)` | Code cap roundness. |
 | Padding | `var(--dsx-space-0-5, 2px) var(--dsx-space-1-5, 6px)` | Inline gutter. |
-| Background (soft) | `var(--dsx-color-surface-raised)` | Soft surface. |
+| Background (soft) | `var(--dsx-color-surface-sunken)` | Soft surface (Direction #3 Q1 pick: sunken, pressed into the page). |
 | Border (soft) | `var(--dsx-color-outline-variant)` | Soft outline (via `inset 0 0 0 1px`). |
 | Background (solid) | `var(--dsx-color-primary)` | Solid surface. |
 | Color (solid) | `var(--dsx-color-on-primary)` | Solid text. |
@@ -103,7 +96,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 Rules:
 
-- The monospace font stack is a hard-coded fallback. `DESIGN.md` and the generated `tokens.css` do not define a monospace token; the stack is the runtime default.
+- The monospace font stack resolves from `var(--dsx-typography-code-font-family)` (the `code` node in `tokens/typography.json`); it is token-backed, not a CSS hard-code.
 - The `color-mix` expressions are token-driven; the alpha is encoded in the token, not as a raw value.
 
 ## Motion contract
@@ -237,7 +230,7 @@ The package does not yet publish a Penpot asset for Code. The recipe is visual r
 
 | Shape | Property | Token | Token type | Penpot property name |
 |---|---|---|---|---|
-| Root | typography | monospace (hard-coded fallback) | Typography | `typography` |
+| Root | typography | `--dsx-typography-code-*` token family | Typography | `typography` |
 | Root | radius | `--dsx-rounded-sm` | Radius | `radius` |
 | Root (soft) | fill | `--dsx-color-surface-raised` | Color | `fills` (state) |
 | Root (soft) | stroke | `--dsx-color-outline-variant` | Color | `strokes` (state) |
@@ -267,4 +260,4 @@ The package does not yet publish a Penpot asset for Code. The recipe is visual r
 - [ ] 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.
-- [ ] Monospace font stack is a CSS hard-code, not a token; do not treat it as themable in Penpot.
+- [ ] Monospace font stack resolves from `--dsx-typography-code-font-family`; treat it as token-backed in Penpot.

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

@@ -3,20 +3,13 @@ title: Collapsible
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/collapsible/Collapsible.tsx
-css_path: packages/d4gger-design-system/src/styles/components/collapsible.css
-props_path: packages/d4gger-design-system/src/components/collapsible/collapsible.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Collapsible.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/navigation.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Icon
 ---
 
 # Collapsible
 
-> 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/{color-picker.md → components/color-picker.md}

@@ -3,13 +3,6 @@ title: ColorPicker
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/colorPicker/ColorPicker.tsx
-css_path: packages/d4gger-design-system/src/styles/components/color-picker.css
-props_path: packages/d4gger-design-system/src/components/colorPicker/colorPicker.props.ts
-test_path: packages/d4gger-design-system/src/test/components/ColorPicker.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:
   - Popover
   - Icon
@@ -18,7 +11,7 @@ depends_on:
 
 # ColorPicker
 
-> 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/{color-swatch.md → components/color-swatch.md}

@@ -3,22 +3,17 @@ 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## 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.
+A compact, pressable swatch that paints a single color value and reports its checked state to assistive tech. Role: a display chip for one color, used as a selectable option inside pickers (ColorPicker presets) — it is not a picker itself. Selection is a redundant ring + check cue (never color alone): the ring marks the container, the check's ink follows the fill's luminance (black on light fills, white on dark). 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
 
@@ -78,14 +73,14 @@ Every CSS value the component paints is a `var(--dsx-*)` token. The swatch itsel
 |---|---|---|
 | 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 (checked) | `var(--dsx-color-on-surface)` | 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. |
+| Check glyph | `var(--dsx-raw-black)` on light fills, `var(--dsx-raw-white)` on dark fills (relative-luminance switch, 0.5 threshold) | Visual confirmation that the swatch is selected. |
 | Transition | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Hover and active motion. |
 
 Rules:
@@ -152,6 +147,10 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 - 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"`.
 
+**Composition story (variant picker):**
+
+- Renders single-select swatches with name labels (Pink / Red / Blue pattern): each option is a `ColorSwatch size="lg"` over a name `Text`, `checked` following shared selection state. This is the component's home context — a variant-option chip, not a standalone control.
+
 **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.
@@ -230,7 +229,7 @@ The package does not yet publish a Penpot asset for ColorSwatch. Recipe is visua
 |---|---|---|---|---|
 | `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 |
+| `checked` | consumer `color` | `--dsx-color-on-surface` | luminance-based Check (`--dsx-raw-black` / `--dsx-raw-white`) | `--dsx-color-primary-alpha` ring |
 
 ### Variant model
 

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

@@ -2,14 +2,7 @@
 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
+archetype: composite
 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)
@@ -20,7 +13,7 @@ depends_on:
 
 # 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -35,13 +28,14 @@ A search-first option picker for large option sets. The user types into an inlin
 | 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.Trigger` | `PopoverTrigger` (a `<button>`) | `dsx-combobox__trigger`, a single-line `dsx-combobox__trigger-value` slot, plus a trailing `dsx-combobox__icon` chevron. Writes `data-invalid="true"` when `invalid` is set and the resolved `data-size`. | The button that toggles the menu. Long values ellipsize without moving the chevron; the value wrapper mirrors its rendered text into `title` (MutationObserver-synced) so ellipsized selections stay discoverable on hover. `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.Content` | `PopoverContent` wrapping `motion.div` + `Command` | `dsx-combobox__content` on the popover content, `dsx-combobox__command` on the inner Command shell. Writes the resolved `data-size` and `data-variant`; the motion div animates opacity and a small Y offset. | The floating menu. It aligns to the trigger start edge and mirrors the trigger width at minimum, growing to fit long option content up to the available viewport width. 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.Item` | `CommandItem` | `dsx-combobox__item`, a single-line `dsx-combobox__item-text` slot, plus a nonshrinking `dsx-combobox__item-icon` check when selected. Writes `data-selected="true"` and `aria-selected` when `selected` is true. | A single option in the filtered list. Long labels ellipsize without displacing the selected check. 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. |
+| `Combobox.ItemMedia` | plain `<div>` | `dsx-combobox__item-media` | Optional leading media slot inside `Combobox.Item` (avatar, checkbox, icon). Fixed `size-lg` box, centered, non-shrinking; the row `gap` separates it from the text. |
 | `Combobox.Group` | `CommandGroup` | `dsx-combobox__group` | Optional grouping for related options. |
 
 ## Props contract
@@ -51,8 +45,8 @@ A search-first option picker for large option sets. The user types into an inlin
 | 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 |
+| `variant` | `'solid' \| 'soft' \| 'outline' \| 'ghost' \| 'vision'` | `'solid'` | no | Visual style of the trigger. Writes `data-variant` on the root. `vision` additionally restyles the panel (direction-3 reference copy: 12px radius, 40px rows, neutral wash). | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control density. Writes `data-size` on the root, trigger, and portalled content; trigger height and trigger typography resolve through the matching density and body-type tokens. The panel (search input, list rhythm, option height and typography) renders one spec at every size. | 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 |
@@ -68,6 +62,7 @@ A search-first option picker for large option sets. The user types into an inlin
 |---|---|---|---|---|---|
 | `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 |
+| `size` | `'sm' \| 'md' \| 'lg'` | inherited from root | no | Trigger-only size override. Writes the resolved `data-size` on the trigger. | no |
 | (Radix `PopoverTrigger` props) | n/a | n/a | no | All other Popover trigger props are forwarded. | no |
 
 **`Combobox.Content` props:**
@@ -76,6 +71,7 @@ A search-first option picker for large option sets. The user types into an inlin
 |---|---|---|---|---|---|
 | `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 |
+| `size` | `'sm' \| 'md' \| 'lg'` | inherited from root | no | Content-only density override. Writes the resolved `data-size` on the portalled panel. | 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`.
@@ -94,7 +90,8 @@ 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.
+- The internal presentation context carries the root `size` and `variant` into portalled content so its width, density, and `vision` styling do not depend on ancestor selectors that cannot cross a portal.
+- Trigger and content geometry are token-driven. The content mirrors the trigger width at minimum (`min-width: --radix-popover-trigger-width`), growing to fit long option content up to the available viewport width.
 - `selected` on `Combobox.Item` is the only slot-level boolean that drives a `data-*` attribute.
 
 ## CSS class contract
@@ -107,10 +104,10 @@ Rules that apply to this row:
 |---|---|---|---|
 | `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` |
+| `data-variant` | `solid`, `soft`, `outline`, `ghost`, `vision` | Trigger variants resolve from the root attribute; portalled content writes its own attribute for `vision` panel styling. | `combobox.css` |
+| `data-size` | `sm`, `md`, `lg` | Written on root, trigger, and content; drives density height, padding, and body typography. | `combobox.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | Root attribute drives trigger radius. | `combobox.css` |
+| `data-accent-color` | any token name | Root attribute drives trigger accent roles. | `combobox.css` |
 
 **Slot classes:**
 
@@ -126,6 +123,7 @@ Rules that apply to this row:
 | `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.ItemMedia` | `dsx-combobox__item-media` | `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` |
@@ -154,17 +152,17 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | 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 height | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Default density-aware control height. |
 | Trigger icon color | `var(--dsx-color-on-surface-variant)` | Trailing chevron. |
-| Content background | `var(--dsx-color-surface-overlay)` | Floating menu surface. |
+| 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-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. |
+| Content radius | `var(--dsx-rounded-lg)` | Floating menu corner roundness shared with the menu family. |
+| Content width | `max-content` / `var(--radix-popover-trigger-width)` / `min(--radix-popover-content-available-width, 40rem)` | Mirror-at-minimum with grow-to-fit; past 40rem rows wrap via `data-overflow`. |
+| 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 surface. |
 | 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 padding | `var(--dsx-space-sm)` | 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. |
@@ -233,7 +231,7 @@ Rules:
 
 **Variant story:**
 
-- Renders one `Combobox` per `variant` value (`solid`, `soft`, `outline`, `ghost`). Asserts the matching `data-variant` attribute is set on the root.
+- Renders one `Combobox` per `variant` value (`solid`, `soft`, `outline`, `ghost`, `vision`). Asserts the matching `data-variant` attribute is set on the root and that `vision` reaches the portalled content.
 
 **Size story:**
 
@@ -277,6 +275,7 @@ Rules:
 - `@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.
+- `_internal/floatingLayer`: `useFloatingLayerHost` tells `Combobox.Content` whether it renders inside a modal-tier host (`Popover.Content` / `Dialog.Content`); when nested, the content adds `dsx-menu__nested` so the panel paints above its host. The signal is read at content level, so a standalone `Combobox` never self-escalates through its own inner `Popover` (see the shared nested floating tier contract in `menu.md`).
 
 **Used by:**
 
@@ -285,7 +284,7 @@ Rules:
 
 **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 Combobox: the open and presentation contexts, the `data-*` attribute contract on root/trigger/content, 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.
 
@@ -336,9 +335,10 @@ The package does not yet publish a Penpot asset for Combobox. Recipe is visual r
 | 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 | fill | `--dsx-color-panel-translucent` | Color | `fills` |
 | Content | stroke | `--dsx-color-outline` | Color | `strokes` |
-| Content | radius | `--dsx-rounded-md` | Radius | `radius` |
+| Content | radius | `--dsx-rounded-lg` | Radius | `radius` |
+| Content | shadow | `--dsx-menu-content-elevation` (menu tier, step 3) | Effect | `shadow` |
 | 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` |
@@ -355,12 +355,12 @@ The package does not yet publish a Penpot asset for Combobox. Recipe is visual r
 
 ### Variant model
 
-- `variant`: `solid`, `soft`, `outline`, `ghost`. Default `solid`.
+- `variant`: `solid`, `soft`, `outline`, `ghost`, `vision`. 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.
+- Total members: 5 × 3 × 5 × N × 2 = the matrix fans out from `size` in the authoring board; the rest are CSS-only hooks.
 
 ### Validation checklist
 

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

@@ -3,13 +3,6 @@ title: Command
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/command/Command.tsx
-css_path: packages/d4gger-design-system/src/styles/components/command.css
-props_path: packages/d4gger-design-system/src/components/command/command.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Command.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:
   - Input
   - Dialog
@@ -18,7 +11,7 @@ depends_on:
 
 # Command
 
-> Source of truth: the package source at `package_path`. The spec 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
 
@@ -35,7 +28,7 @@ A search-and-act command palette, cmdk-backed, that lets the user type to filter
 | `Command` | `cmdk.Command` | DS composite + class `dsx-command` | Root palette. Hosts input, list, groups, items, separator, and shortcut. |
 | `CommandDialog` | `Dialog` + `Command` | DS composite | Wraps `Command` in a `Dialog` with a `DialogContent`. Manages open state and the global keyboard shortcut. |
 | `CommandInput` | `cmdk.Input` wrapped in `<div>` | DS composite + class `dsx-command__input` | Search input. Wrapper carries `dsx-command__input-wrapper` and a search icon. |
-| `CommandList` | `cmdk.List` | DS composite + class `dsx-command__list dsx-scroll-area` | Scrollable list of groups and items. |
+| `CommandList` | `cmdk.List` | DS composite + class `dsx-command__list` | Scrollable list of groups and items (native overflow; never the ScrollArea class — its `overflow: hidden` clipped list tails). |
 | `CommandGroup` | `cmdk.Group` | DS composite + class `dsx-command__group` | Grouped section with optional heading. Writes `data-section` when a string heading is present. |
 | `CommandItem` | `cmdk.Item` | DS composite + class `dsx-command__item` | Selectable row. |
 | `CommandSeparator` | `cmdk.Separator` | DS composite + class `dsx-command__separator dsx-separator` | Divider between groups. |
@@ -61,6 +54,8 @@ A search-and-act command palette, cmdk-backed, that lets the user type to filter
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `shortcut` | `string \| false` | `'meta+k'` | no | Global keyboard shortcut. Pass `false` to disable the listener. | no |
+| `title` | `string` | `'Command menu'` | no | Accessible dialog title, rendered via a `VisuallyHidden`-wrapped `DialogTitle`. Same V-1 class of fix as `SearchBar` (2026-07-03): previously no title path existed at all, so every open palette failed the Radix `DialogContent requires a DialogTitle` requirement. | no |
+| `description` | `string` | `undefined` | no | Optional accessible dialog description, rendered via a `VisuallyHidden`-wrapped `DialogDescription` when set. | no |
 | `open` | `boolean` | `undefined` | no | Controlled open state. | no |
 | `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Fires on every open transition. | no |
 | `children` | `React.ReactNode` | `undefined` | no | Slot content. | no |
@@ -138,7 +133,7 @@ Rules:
 | `CommandInput` (wrapper) | `dsx-command__input-wrapper` | `command.css` |
 | `CommandInput` (icon) | `dsx-command__input-icon` | `command.css` |
 | `CommandInput` (input) | `dsx-command__input dsx-input` | `command.css` |
-| `CommandList` | `dsx-command__list dsx-scroll-area` | `command.css` |
+| `CommandList` | `dsx-command__list` | `command.css` |
 | `CommandGroup` | `dsx-command__group` | `command.css` |
 | `CommandItem` | `dsx-command__item` | `command.css` |
 | `CommandSeparator` | `dsx-command__separator dsx-separator` | `command.css` |
@@ -158,7 +153,7 @@ Rules:
 
 | Property | Token | Role |
 |---|---|---|
-| Root background | `var(--dsx-color-surface-overlay)` | Palette surface. |
+| Root background | `var(--dsx-color-panel-translucent)` | Palette surface. |
 | Root border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Edge. |
 | Root border radius | `var(--dsx-rounded-lg)` | Rounded corners (aligned to the dropdown-menu/context-menu/menubar panel recipe). |
 | Root shadow | `var(--dsx-shadow-elevation-3)` | Depth (aligned to the shared popup-family elevation). |
@@ -348,7 +343,7 @@ The palette has no mount or exit motion. Item selection and hover animate throug
 
 | Shape | Property | Token | Token type | Penpot property name |
 |---|---|---|---|---|
-| `<Root Board>` | fill | `var(--dsx-color-surface-overlay)` | Color | `fills` |
+| `<Root Board>` | fill | `var(--dsx-color-panel-translucent)` | Color | `fills` |
 | `<Root Board>` | radius | `var(--dsx-rounded-md)` | Radius | `borderRadius` |
 | `<Root Board>` | shadow | `var(--dsx-shadow-elevation-2)` | Shadow | `effects` |
 | `<Input field>` | typography | `var(--dsx-typography-body-medium-*)` | Typography | `typography` |

package/dist/docs/{comment-thread.md → components/comment-thread.md}

@@ -3,8 +3,6 @@ title: CommentThread
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/commentThread/CommentThread.tsx
-css_path: packages/d4gger-design-system/src/styles/components/comment-thread.css
 ---
 
 # CommentThread