@d4gger/design-system 2.7.0 → 3.0.0

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

@@ -3,13 +3,6 @@ title: Chart
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/chart/Chart.tsx
-css_path: packages/d4gger-design-system/src/styles/components/chart.css
-props_path: packages/d4gger-design-system/src/components/chart/chart.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Chart.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/data.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - recharts
   - "@radix-ui/react-slot"
@@ -17,11 +10,11 @@ depends_on:
 
 # Chart
 
-> 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 token-aligned chart shell that exposes line, bar, and pie primitives on top of `recharts`. The package owns the chart shell, the class wiring, the chart palette tokens, and the responsive container. The adapter (`recharts`) owns the chart math, axis rendering, tooltips, and the legend. Apps own analytics semantics, custom tooltips, axis formatting, and any data joins beyond the default `ChartDatum` shape.
+A token-aligned chart family that exposes line, bar, pie, donut, radial, and area primitives on top of `recharts`. The package owns the chart shell, the class wiring, the chart palette tokens, and the responsive container. The adapter (`recharts`) owns the chart math, axis rendering, tooltips, and the legend. Apps own analytics semantics, custom tooltips, axis formatting, and any data joins beyond the documented shapes. The shell is a bare plot surface — no card chrome. Cards, stat headers, and dashboard composition live in app code (see the composition story).
 
 ## Anatomy & slots
 
@@ -32,20 +25,23 @@ A token-aligned chart shell that exposes line, bar, and pie primitives on top of
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
 | `Chart.Container` (alias `Chart`) | `<div>` (or `Slot` when `asChild`) | DS shell, `dsx-chart` | Root host. Carries `data-slot="chart-container"`. |
-| `Chart.Line` | `<div>` | `dsx-chart` with `data-chart-type="line"` | Hosts a Recharts `LineChart` inside a `ResponsiveContainer`. |
-| `Chart.Bar` | `<div>` | `dsx-chart` with `data-chart-type="bar"` | Hosts a Recharts `BarChart` inside a `ResponsiveContainer`. |
+| `Chart.Line` | `<div>` | `dsx-chart` with `data-chart-type="line"` | Hosts a Recharts `LineChart` inside a `ResponsiveContainer`. Accepts an optional `series` array for multi-series lines. |
+| `Chart.Bar` | `<div>` | `dsx-chart` with `data-chart-type="bar"` | Hosts a Recharts `BarChart` inside a `ResponsiveContainer`. Accepts an optional `series` array (grouped, or `stacked` for stacked bars). |
 | `Chart.Pie` | `<div>` | `dsx-chart` with `data-chart-type="pie"` | Hosts a Recharts `PieChart` inside a `ResponsiveContainer`. Pie data points are auto-mapped to the chart palette tokens. |
+| `Chart.Donut` | `<div>` | `dsx-chart` with `data-chart-type="donut"` | Ring variant of the pie with an optional center `label` slot (`dsx-chart__center-label`). |
+| `Chart.Radial` | `<div>` | `dsx-chart` with `data-chart-type="radial"` | Single-value progress ring (`value` / `max`) with an optional center `label` slot. |
+| `Chart.Area` | `<div>` | `dsx-chart` with `data-chart-type="area"` | Hosts a Recharts `AreaChart`. Accepts `series` like line/bar; `spark` strips axes, grid, legend, and tooltip for stat-card sparklines. |
 | `Chart.Empty` | `<div>` | `dsx-chart__empty` | DS-owned empty-state surface for the host. |
 | `Chart.Legend` | `<div>` | `dsx-chart__legend` | DS-owned legend container. |
 | `Chart.LegendItem` | `<span>` | `dsx-chart__legend-item` | DS-owned legend row. Accepts an optional `color` prop that writes `--dsx-chart-legend-color` to the inline style. |
 
 **Adapter host:**
 
-`Chart.Line`, `Chart.Bar`, and `Chart.Pie` wrap a Recharts `ResponsiveContainer` (`width="100%"`, `height={350}`). The container always renders a `CartesianGrid` (line and bar), `XAxis` keyed by `name`, `YAxis`, the Recharts `Tooltip`, and the Recharts `Legend`. The single data series is keyed by `value` and uses `var(--dsx-color-primary)` for fill or stroke. Pie slices cycle through `var(--dsx-chart-1)` through `var(--dsx-chart-5)` based on the slice index modulo 5.
+`Chart.Line`, `Chart.Bar`, and `Chart.Pie` wrap a Recharts `ResponsiveContainer` (`width="100%"`, `height="100%"` — the frame's aspect ratio owns the height, so the svg can never overflow the rounded shell). The container always renders a `CartesianGrid` (line and bar), `XAxis` keyed by `name`, `YAxis`, the Recharts `Tooltip`, and the Recharts `Legend`. The single data series is keyed by `value` and uses `var(--dsx-color-primary)` for fill or stroke. Pie slices cycle through `var(--dsx-chart-1)` through `var(--dsx-chart-5)` based on the slice index modulo 5. Line and bar charts reserve an inset margin so axis ticks never clip against the rounded shell, and both axes render without tick or axis lines with muted 12px ticks.
 
 **Compatibility exports:**
 
-The module also re-exports raw `BarChart`, `CartesianGrid`, `LineChart`, `PieChart`, `XAxis`, `YAxis`, `ResponsiveContainer`, `ChartTooltip` (alias of `RechartsTooltip`), `RechartsLegend`, `ChartContainer`, `ChartBar`, `ChartEmpty`, `ChartLegend`, `ChartLegendItem`, `ChartLine`, and `ChartPie`. These are package-authoring escape hatches for apps that need a non-tokenized Recharts surface. The `Chart` namespace plus its named subcomponents is the canonical surface for new app code.
+The module also re-exports raw `AreaChart`, `BarChart`, `CartesianGrid`, `LineChart`, `PieChart`, `RadialBarChart`, `XAxis`, `YAxis`, `ResponsiveContainer`, `ChartTooltip` (alias of `RechartsTooltip`), `RechartsLegend`, `ChartContainer`, `ChartArea`, `ChartBar`, `ChartDonut`, `ChartEmpty`, `ChartLegend`, `ChartLegendItem`, `ChartLine`, `ChartPie`, and `ChartRadial`. These are package-authoring escape hatches for apps that need a non-tokenized Recharts surface. The `Chart` namespace plus its named subcomponents is the canonical surface for new app code.
 
 ## Props contract
 
@@ -63,10 +59,40 @@ The container extends `React.HTMLAttributes<HTMLDivElement>` minus the `children
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `data` | `ChartDatum[]` | (required) | yes | Data series. Each entry is `{ id?: number \| string; name: string; value: number }`. The X axis is keyed by `name`; the single series is keyed by `value`. | no |
+| `data` | `ChartDatum[] \| ChartRow[]` | (required) | yes | Data series. Single-series entries are `{ id?: number \| string; name: string; value: number }`; multi-series rows add one numeric field per series key. The X axis is keyed by `name`. | no |
+| `series` | `{ dataKey: string; name?: string; fill?: string }[]` | `undefined` | no | Multi-series definition. Omitted = single `value` series. `name` feeds the legend (defaults to the dataKey); `fill` defaults to the palette cycle. | no |
+| `stacked` | `boolean` | `false` | no | Stacks bar series (bar only meaningful, accepted on both). | no |
+| `name` | `string` | `'value'` | no | Legend label for the single-series case. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-chart`. | no |
 
-These two slots also accept all `Chart.Container` HTML attributes and forward them to the host. Recharts internals (`Line`, `Bar`, axes, grid) are not exposed as props; the line and bar variants are intentionally fixed to a single series with `isAnimationActive={false}`.
+These two slots also accept all `Chart.Container` HTML attributes and forward them to the host. Recharts internals (axes, grid) are not exposed as props; animation stays disabled via `isAnimationActive={false}`.
+
+### `Chart.Donut` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `data` | `ChartDatum[]` | (required) | yes | Ring segments; fills cycle the palette like pie. | no |
+| `label` | `React.ReactNode` | `undefined` | no | Center label rendered in `dsx-chart__center-label` (e.g. a total with caption). | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-chart`. | no |
+
+### `Chart.Radial` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `number` | (required) | yes | Current value; clamped to `max`. | no |
+| `max` | `number` | `100` | no | Scale maximum. | no |
+| `label` | `React.ReactNode` | `undefined` | no | Center label rendered in `dsx-chart__center-label`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-chart`. | no |
+
+### `Chart.Area` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `data` | `ChartDatum[] \| ChartRow[]` | (required) | yes | Same shapes as line/bar. | no |
+| `series` | `{ dataKey: string; name?: string; fill?: string }[]` | `undefined` | no | Multi-series areas; omitted = single `value` area at 10% fill opacity. | no |
+| `name` | `string` | `'value'` | no | Legend label for the single-series case. | no |
+| `spark` | `boolean` | `false` | no | Strips axes, grid, legend, and tooltip and switches to a 3:1 strip for stat-card sparklines. Writes `data-spark`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-chart`. | no |
 
 ### `Chart.Pie` props
 
@@ -132,6 +158,7 @@ The type is exported as `ChartDatum` from the package barrel.
 | Slot | Class | CSS file |
 |---|---|---|
 | Container | `dsx-chart` | `chart.css` |
+| Center label (donut / radial) | `dsx-chart__center-label` | `chart.css` |
 | Empty | `dsx-chart__empty` | `chart.css` |
 | Legend | `dsx-chart__legend` | `chart.css` |
 | Legend item | `dsx-chart__legend-item` | `chart.css` |
@@ -216,11 +243,13 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Variant stories** (one per chart type):
 
-- Renders `Chart.Bar`, `Chart.Line`, and `Chart.Pie` with a sample `data` array. Asserts `data-chart-type` matches the variant on the host element.
+- Renders `Chart.Bar`, `Chart.Line`, `Chart.Pie`, `Chart.Donut`, `Chart.Radial`, and `Chart.Area` with sample data. Asserts `data-chart-type` matches the variant on the host element.
+- Renders `Chart.Bar` with two `series` and asserts two legend rows with the series names. Renders `Chart.Bar` with `stacked` and asserts a single stacked group per category.
+- Renders `Chart.Area` with `spark` and asserts axes, grid, legend, and tooltip are absent and `data-spark` is set.
 
 **Composition story:**
 
-- Renders `Chart.Legend` with two `Chart.LegendItem` rows, one with `color="var(--dsx-chart-1)"` and one with `color="var(--dsx-chart-3)"`. Asserts the inline `--dsx-chart-legend-color` custom property is set on each row and the swatch `::before` is visible.
+- Renders dashboard cards (`Card` + stat header + chart + `Chart.Legend`): a multi-series bar card, a donut card with center total, a radial progress card, and a sparkline stat card. Asserts each composition renders real chart content inside a titled card — never a bare chart where a dashboard meaning belongs.
 
 **State story:**
 
@@ -318,9 +347,9 @@ The `Chart.Container` exposes only `asChild` from its prop defs. `Chart.Line`, `
 
 ### Variant model
 
-- `data-chart-type`: `line`, `bar`, `pie`. Default `line`.
+- `data-chart-type`: `line`, `bar`, `pie`, `donut`, `radial`, `area`. No default (each slot writes its own).
 - `asChild`: `true`, `false`. Default `false`.
-- Total members: 6 (3 chart types × 2 `asChild` values).
+- Total members: 12 (6 chart types × 2 `asChild` values).
 
 ### Validation checklist
 

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
 

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 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)` | Overlay stacking. |
 | Search wrapper border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Bottom divider below the input. |
 | Input height | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Density-aware control height. |
 | List max-height | `var(--dsx-combobox-list-max-height)` | Scroll ceiling. |
-| List padding | `var(--dsx-space-xs)` | List inner gutter. |
+| List 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:**
 
@@ -285,7 +283,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 +334,9 @@ 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` |
 | 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 +353,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