@d4gger/design-system 2.7.0 → 3.0.1

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

@@ -3,13 +3,6 @@ title: Item
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/item/Item.tsx
-css_path: packages/d4gger-design-system/src/styles/components/item.css
-props_path: packages/d4gger-design-system/src/components/item/item.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Item.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:
   - Box
   - Text
@@ -18,7 +11,7 @@ depends_on:
 
 # Item
 
-> 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
 
@@ -32,7 +25,7 @@ A generic list-row surface for settings, notifications, or selectable summaries.
 
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
-| `Item` (root) | `<div>` (or `Slot` host) | Root + class | The row surface. Writes `dsx-item`, `data-variant`, `data-size`, and (when `interactive={true}`) `data-interactive="true"`. |
+| `Item` (root) | `<div>` (or `Slot` host) | Root + class | The row surface. Writes `dsx-item`, a size modifier, a non-default variant modifier, and (when `interactive={true}`) `data-interactive="true"`. |
 | `Item.Media` | `<div>` (or `Slot` host) | Slot class | Leading visual slot (icon, avatar, image). Writes `dsx-item__media`. |
 | `Item.Content` | `<div>` (or `Slot` host) | Slot class | Text + metadata wrapper. Writes `dsx-item__content`. |
 | `Item.Title` | `<h4>` (or `Slot` host) | Slot class | Row title. Writes `dsx-item__title`. |
@@ -47,8 +40,8 @@ The root is a flex row with `gap: var(--dsx-space-md)`. `Item.Media`, `Item.Cont
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` | no | Surface treatment; writes `data-variant`. | no |
-| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | no | Minimum height; writes `data-size`. `xs` and `sm` are row-density; `md` and `lg` are content-density. | no |
+| `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` | no | Surface treatment through modifier classes. | no |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | no | Minimum height and vertical padding through modifier classes. Padding increases from space-xs to space-sm, space-md, and space-lg. | no |
 | `interactive` | `boolean` | `false` | no | When `true`, adds `cursor: pointer` to the root; writes `data-interactive="true"`. The component does not add hover or focus styles; consumers that want a fully interactive row should wrap with their own Button or `asChild` onto a button. | no |
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot`; consumer supplies the host element. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-item`. | no |
@@ -64,19 +57,19 @@ Each slot also accepts the standard HTML attributes for its host element.
 
 Rules:
 
-- The component does not emit `data-radius`, `data-accent-color`, or `data-high-contrast`. The contract calls for `data-variant`, `data-size`, and `data-interactive` only.
-- `data-interactive` is emitted only when `interactive={true}`. The CSS does not currently hook it, but the prop is part of the public contract.
+- The component does not emit `data-radius`, `data-accent-color`, or `data-high-contrast`. Variant and size use classes; `data-interactive` is the only owned state attribute.
+- `data-interactive` is emitted only when `interactive={true}`. The CSS hooks it to apply the pointer cursor.
 
 ## CSS class contract
 
 **Root class:** `dsx-item`
 
-**Modifier classes** (driven by `data-*` attributes written by the component):
+**Modifier classes** (written directly by the component):
 
-| Attribute | Allowed values | Class | CSS file |
+| Prop | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-variant` | `default`, `outline`, `muted` | `.dsx-item[data-variant='outline']`, `.dsx-item[data-variant='muted']` | `item.css` |
-| `data-size` | `xs`, `sm`, `md`, `lg` | `.dsx-item[data-size='xs']`, `.dsx-item[data-size='sm']`, `.dsx-item[data-size='md']`, `.dsx-item[data-size='lg']` | `item.css` |
+| `variant` | `default`, `outline`, `muted` | `.dsx-item--outline`, `.dsx-item--muted` | `item.css` |
+| `size` | `xs`, `sm`, `md`, `lg` | `.dsx-item--xs`, `.dsx-item--sm`, `.dsx-item--md`, `.dsx-item--lg` | `item.css` |
 | `data-interactive` | `true` | `.dsx-item[data-interactive='true']` | `item.css` |
 
 **Slot classes:**
@@ -94,6 +87,8 @@ Rules:
 
 - The component does not write `@media` rules. `size` and `variant` are single-value only.
 
+- Content can shrink and long labels wrap. Root and trailing actions wrap intrinsically when their combined width exceeds the row, keeping commands reachable without a breakpoint.
+
 **Reduced motion:**
 
 - The component is static. No motion is applied.
@@ -116,7 +111,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Interactive cursor | `pointer` | Pointer cursor when `interactive={true}` |
 | Min-height (xs) | `var(--dsx-size-lg)` | xs row min-height |
 | Min-height (sm) | `var(--dsx-size-xl)` | sm row min-height |
-| Min-height (md, lg) | `var(--dsx-size-2xl)` | md/lg row min-height |
+| Min-height (md) | `var(--dsx-size-2xl)` | md row min-height |
+| Min-height (lg) | `var(--dsx-size-3xl)` | lg row min-height |
 | Media dimensions | `var(--dsx-size-xl)` | Media slot dimensions |
 | Content display | `grid` | Title + description layout |
 | Content gap | `var(--dsx-space-xs)` | Space between Title and Description |
@@ -168,11 +164,11 @@ The component is static.
 
 **Variant story:**
 
-- Renders three items with `variant="default"`, `variant="outline"`, and `variant="muted"`. Asserts the matching `data-variant` attribute.
+- Renders three items with `variant="default"`, `variant="outline"`, and `variant="muted"`. Asserts the matching non-default variant class.
 
 **Size story:**
 
-- Renders four items with `size="xs"`, `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute.
+- Renders four items with `size="xs"`, `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching size class and measures distinct rendered heights for identical content.
 
 **State story:**
 
@@ -214,10 +210,12 @@ The component is static.
 
 **State boundaries:**
 
-- Owned by Item: the `data-variant`, `data-size`, and `data-interactive` attributes, the flex row layout, and the `dsx-item__*` slot classes.
+- Owned by Item: the variant/size classes and `data-interactive` attribute, the flex row layout, and the `dsx-item__*` slot classes.
 - Owned by the consumer: the row content, the interactive behavior, the surrounding list semantics, and the heading level on `Item.Title`.
 
 **Boundary rules:**
 
 - App-owned data: the row content, the action handlers, the selection state, and the surrounding list semantics.
 - DS-owned visuals: token bindings, slot classes, variant surfaces, and the size min-height.
+
+The playground size comparison uses identical content and aligns row starts, avoiding flex stretch that would make all sizes inherit the largest sibling height. Both the variant gallery and the live example show the density scale.

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

@@ -3,19 +3,12 @@ title: Kbd
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/kbd/Kbd.tsx
-css_path: packages/d4gger-design-system/src/styles/components/kbd.css
-props_path: packages/d4gger-design-system/src/components/kbd/kbd.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Kbd.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: []
 ---
 
 # Kbd
 
-> 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
 
@@ -77,7 +70,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Box shadow | `inset 0 calc(-1 * var(--dsx-border-width-sm)) 0 var(--dsx-color-outline-variant), var(--dsx-effect-shadow-1)` | Bottom edge depth + elevation |
 | Font family | `var(--dsx-typography-label-small-font-family), sans-serif` | Label typeface |
 | Font weight | `var(--dsx-typography-label-small-font-weight)` | Label weight |
-| Line height | `var(--dsx-typography-kbd-line-height)` | Key cap line height |
+| Line height | `var(--dsx-typography-label-small-line-height)` | Key cap line height (shared with the label-small ramp; no kbd-specific typography node) |
 | Min width | `var(--dsx-kbd-min-width, 1.75em)` | Minimum key cap width |
 | Padding (sm) | `var(--dsx-kbd-padding-block-sm) var(--dsx-kbd-padding-inline-sm)` | Small key cap padding |
 | Font size (sm) | `var(--dsx-kbd-font-size-sm)` | Small key cap font size |
@@ -141,7 +134,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Kbd does not track `data-accent-color`; the story documents that the key cap surface is visually unchanged across accents.
+- Renders inside a `Theme` wrapper with `accentColor="rift"` and `accentColor="warp"`. Kbd does not track `data-accent-color`; the story documents that the key cap surface is visually unchanged across accents.
 
 **A11y story:**
 

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

@@ -3,20 +3,13 @@ title: Label
 status: canonical
 category: Primitives
 archetype: radix-wrapper
-package_path: packages/d4gger-design-system/src/components/label/Label.tsx
-css_path: packages/d4gger-design-system/src/styles/components/label.css
-props_path: packages/d4gger-design-system/src/components/label/label.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Label.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:
   - '@radix-ui/react-label (Root)'
 ---
 
 # Label
 
-> 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/{layout-props.md → components/layout-props.md}

@@ -3,13 +3,6 @@ title: Layout (props)
 status: canonical
 category: Foundations
 archetype: utility
-package_path: packages/d4gger-design-system/src/layout/layout.props.ts
-css_path: packages/d4gger-design-system/src/styles/components/box.css
-props_path: packages/d4gger-design-system/src/layout/layout.props.ts
-test_path: packages/d4gger-design-system/src/test/props/Layout.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:
   - Box
   - Shared
@@ -17,7 +10,7 @@ depends_on:
 
 # Layout (props)
 
-> 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
 
@@ -69,7 +62,7 @@ Rules:
 | Custom property group | Token | Consumer CSS file |
 |---|---|---|
 | `--dsx-box-display`, `--dsx-box-position`, `--dsx-box-inset`, `--dsx-box-z-index`, `--dsx-box-min-*`, `--dsx-box-max-*`, `--dsx-box-margin`, `--dsx-box-padding`, `--dsx-box-gap`, `--dsx-box-align-self`, `--dsx-box-justify-self`, `--dsx-box-flex*`, `--dsx-box-order`, `--dsx-box-grid-*` | (see [Box](./box.md)) | `box.css` |
-| `--dsx-flex-direction`, `--dsx-flex-align`, `--dsx-flex-justify`, `--dsx-flex-wrap` | (see [Flex](./flex.md)) | `flex.css` |
+| `--dsx-flex-direction`, `--dsx-flex-align`, `--dsx-flex-justify`, `--dsx-flex-wrap` | (see [Flex](./flex.md)) | `flex.css` (consumed with `row` / `stretch` / `flex-start` / `nowrap` fallbacks; written via `FLEX_PROP_DEFS` by `extractLayoutProps` consumers such as `Container`) |
 | `--dsx-grid-columns`, `--dsx-grid-rows`, `--dsx-grid-areas`, `--dsx-grid-auto-flow`, `--dsx-grid-align`, `--dsx-grid-justify`, `--dsx-grid-align-content`, `--dsx-grid-justify-items`, `--dsx-grid-justify-content` | (see [Grid](./grid.md)) | `grid.css` |
 | `--dsx-container-max-width`, `--dsx-container-inset` | (see [Container](./container.md)) | `container.css` |
 | `--dsx-section-space` | (see [Section](./section.md)) | `section.css` |

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

@@ -3,23 +3,16 @@ title: Link
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/link/Link.tsx
-css_path: packages/d4gger-design-system/src/styles/components/link.css
-props_path: packages/d4gger-design-system/src/components/link/link.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Link.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: []
 ---
 
 # Link
 
-> 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 styled anchor element that renders an `<a>` (or the consumer's host element) with token-aligned typography, an `underline` policy, a `tone` color override, an optional `color` accent (amber, silver, or bronze), an optional responsive `size` scale, a `highContrast` toggle, and the shared `asChild` infra. Internal versus external routing is a consumer choice: the component renders an `<a>` and forwards `href`, `target`, `rel`, and every other native anchor attribute through prop forwarding.
+A styled anchor element that renders an `<a>` (or the consumer's host element) with token-aligned typography, an `underline` policy, a `tone` color override, an optional `color` accent (rift, warp, or ray), an optional single-value `size` scale, a `highContrast` toggle, and the shared `asChild` infra. Internal versus external routing is a consumer choice: the component renders an `<a>` and forwards `href`, `target`, `rel`, and every other native anchor attribute through prop forwarding.
 
 ## Anatomy & slots
 
@@ -33,10 +26,10 @@ No slots: flat export. The component renders a single `<a>` host element (or the
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `underline` | `'auto' \| 'always' \| 'hover' \| 'none'` | `'auto'` | no | Underline policy. Writes the `dsx-link--{underline}` modifier class. `auto` shows the underline on hover (and on focus-visible by browser default); `always` shows it unconditionally; `hover` never shows it; `none` removes it for both `a` and `button` hosts. | no |
+| `underline` | `'auto' \| 'always' \| 'hover' \| 'none'` | `'auto'` | no | Underline policy. Writes the `dsx-link--{underline}` modifier class. `auto` is unstyled at rest, underline on hover (same hover treatment as `hover`); `always` shows it unconditionally; `hover` is unstyled at rest, underline on hover; `none` removes it for both `a` and `button` hosts. | no |
 | `tone` | `'default' \| 'muted' \| 'inverse'` | `'default'` | no | Tone modifier. Writes `dsx-link--{tone}` for `muted` and `inverse`. | no |
-| `color` | `'amber' \| 'silver' \| 'bronze' \| string` | `undefined` | no | Accent color. The three canonical values are amber, silver, and bronze; the prop also accepts a free-form string. Writes the `data-accent-color` attribute. | no |
-| `size` | `'1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'` | `undefined` | no | Responsive size scale. Writes the `data-size` attribute. Accepts a responsive value (`{ initial, sm, md, lg, xl, 2xl }`). | yes |
+| `color` | `'rift' \| 'warp' \| 'ray' \| string` | `undefined` | no | Accent color. The three canonical values are rift, warp, and ray; the prop also accepts a free-form string. Writes the `data-accent-color` attribute. | no |
+| `size` | `'1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'` | `undefined` | no | Single-value size scale. Writes the `data-size` attribute. Not responsive: the source writes the value directly with no base-value resolution. | no |
 | `highContrast` | `boolean` | `false` | no | When `true`, writes `data-high-contrast="true"`. | no |
 | `asChild` | `boolean` | `false` | no | Renders the host through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-link`. | no |
@@ -48,7 +41,7 @@ Rules that apply to this row:
 - `Link` extends `Omit<ComponentPropsWithoutRef<'a'>, 'color'>` because `color` is redefined by the prop def bag.
 - `underline`, `tone`, `color`, `size`, `highContrast`, and `asChild` flow through `extractProps` and the prop def bag. The component forwards every other native anchor attribute (`href`, `target`, `rel`, `download`, `aria-*`, etc.) when `asChild` is `false`.
 - `data-accent-color` is written when `color` is set. `data-size` is written when `size` is set. `data-high-contrast` is written when `highContrast` is truthy.
-- The `color` prop in the prop def has `type: 'enum | string'` and a `values` list of `['amber', 'silver', 'bronze']`. The runtime accepts any string; the canonical values are the accent palette.
+- The `color` prop in the prop def has `type: 'enum | string'` and a `values` list of `['rift', 'warp', 'ray']`. The runtime accepts any string; the canonical values are the accent palette.
 - Internal versus external routing is not a prop. Apps wrap `Link` in their router's link primitive (or use `asChild` with the router's link) when they need client-side navigation; `Link` itself renders a native anchor and forwards `href`.
 
 ## CSS class contract
@@ -61,7 +54,7 @@ Rules that apply to this row:
 |---|---|---|---|
 | (class) | `auto`, `always`, `hover`, `none` | `dsx-link--{underline}` | `link.css` |
 | (class) | `muted`, `inverse` | `dsx-link--muted`, `dsx-link--inverse` | `link.css` |
-| `data-accent-color` | `amber`, `silver`, `bronze` (or any custom string) | `.dsx-link[data-accent-color='amber']`, `.dsx-link[data-accent-color='silver']`, `.dsx-link[data-accent-color='bronze']` | `link.css` |
+| `data-accent-color` | `rift`, `warp`, `ray` (or any custom string) | `.dsx-link[data-accent-color='rift']`, `.dsx-link[data-accent-color='warp']`, `.dsx-link[data-accent-color='ray']` | `link.css` |
 | `data-size` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9` | (CSS contract for size) | n/a |
 | `data-high-contrast` | `true` | `.dsx-link[data-high-contrast='true']` | `link.css` |
 
@@ -69,7 +62,7 @@ Rules that apply to this row:
 
 **Responsive behavior:**
 
-- `size` is `responsive: true` in the prop def bag. The component writes `data-size` for the base value; the responsive class application is left to downstream CSS or the consumer.
+- `size` is single-value only (`responsive` is unset in the prop def bag and the source writes `data-size` directly). Unlike Heading/Text, Link has no responsive class pipeline for size — no breakpoint-prefixed size classes exist in the CSS.
 
 **Reduced motion:**
 
@@ -82,7 +75,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Property | Token | Role |
 |---|---|---|
 | Color (default) | `var(--dsx-color-primary)` | Default link color. |
-| Color (accent override) | `var(--dsx-color-accent-9)` | Override for amber, silver, and bronze. |
+| Color (accent override) | `var(--dsx-color-accent-9)` | Override for rift, warp, and ray. |
 | Color (muted) | `var(--dsx-color-on-surface-variant)` | Muted tone. |
 | Color (inverse) | `var(--dsx-color-on-inverse-background)` | Inverse-context color. |
 | Color (high-contrast) | `var(--dsx-color-high-contrast)` | High-contrast shift. |
@@ -96,7 +89,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 Rules:
 
-- Tokens come from `DESIGN.md` and the generated `tokens.css`. The accent override is the only place a brand color is used directly; the default link color tracks `var(--dsx-color-primary)` so it follows `data-accent-color` for amber, silver, and bronze.
+- Tokens come from `DESIGN.md` and the generated `tokens.css`. The accent override is the only place a brand color is used directly; the default link color tracks `var(--dsx-color-primary)` so it follows `data-accent-color` for rift, warp, and ray.
 - The text-decoration thickness and offset use the browser-native heuristics `min(2px, max(1px, 0.05em))` and `calc(0.025em + 2px)`. These are CSS values, not tokens; the spec records them as the canonical underline rhythm.
 
 ## Motion contract
@@ -149,7 +142,7 @@ Rules:
 
 **Color story:**
 
-- Renders Link with each `color` value. Asserts the `data-accent-color` attribute on the root. The test `renders data-accent-color for silver and bronze` documents amber, silver, and bronze.
+- Renders Link with each `color` value. Asserts the `data-accent-color` attribute on the root. The test `renders data-accent-color for warp and ray` documents rift, warp, and ray.
 
 **Composition story** (for `asChild`):
 
@@ -161,7 +154,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the `data-accent-color` attribute tracks the active accent.
+- Renders inside a `Theme` wrapper with `accentColor="rift"` and `accentColor="warp"`. Asserts the `data-accent-color` attribute tracks the active accent.
 
 **A11y story:**
 
@@ -241,7 +234,7 @@ The package does not yet publish a Penpot asset for Link. The recipe is visual r
 | `muted` | `--dsx-color-on-surface-variant` | (none) |
 | `inverse` | `--dsx-color-on-inverse-background` | (none) |
 | `highContrast` | `--dsx-color-high-contrast` | (none) |
-| `accent=amber` | `--dsx-color-accent-9` | `--dsx-color-accent-9` on `always` |
+| `accent=rift` | `--dsx-color-accent-9` | `--dsx-color-accent-9` on `always` |
 | `always` | (per tone) | `underline` solid `--dsx-color-primary` |
 | `hover` (auto) | (per tone) | `underline` solid `--dsx-color-primary` |
 
@@ -249,7 +242,7 @@ The package does not yet publish a Penpot asset for Link. The recipe is visual r
 
 - `underline`: `auto`, `always`, `hover`, `none`. Default `auto`.
 - `tone`: `default`, `muted`, `inverse`. Default `default`.
-- `color`: `amber`, `silver`, `bronze`, or a free-form string. Default unset.
+- `color`: `rift`, `warp`, `ray`, or a free-form string. Default unset.
 - `size`, `highContrast` documented in the spec body.
 - Total members: underline × tone × color = 4 × 3 × 4 = 48, plus the high-contrast toggle.
 
@@ -258,4 +251,4 @@ The package does not yet publish a Penpot asset for Link. 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.
-- [ ] The accent override is the only place a brand color is used directly; the default link color tracks `data-accent-color` for amber, silver, and bronze.
+- [ ] The accent override is the only place a brand color is used directly; the default link color tracks `data-accent-color` for rift, warp, and ray.

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

@@ -3,17 +3,12 @@ title: Marquee
 status: canonical
 category: Components
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/marquee/Marquee.tsx
-css_path: packages/d4gger-design-system/src/styles/components/marquee.css
-props_path: packages/d4gger-design-system/src/components/marquee/marquee.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Marquee.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on: []
 ---
 
 # Marquee
 
-> 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
 
@@ -29,7 +24,7 @@ A horizontally scrolling content strip that animates a duplicated child track ac
 |---|---|---|---|
 | `Marquee` (root) | `<div>` | DS primitive + class | Wrapper that owns the `--dsx-marquee-duration`, `--dsx-marquee-direction`, and `--dsx-marquee-edge-fade-width` CSS variables plus the `data-pause-on-hover` and optional `data-edge-fade` attributes. |
 | internal track | `<div class="dsx-marquee__track">` | internal layout | Flex row that runs the `dsx-marquee-scroll` keyframe. |
-| internal content (x2) | `<div class="dsx-marquee__content">` | internal layout | The original `children` and an `aria-hidden="true"` clone. The duplication is what makes the loop seamless. |
+| internal content (x2) | `<div class="dsx-marquee__content">` | internal layout | The original `children` and an `aria-hidden="true"`, inert clone. The duplication is what makes the loop seamless. |
 
 The track and content nodes are internal layout, not public slots. The two `dsx-marquee__content` rows are siblings inside the track.
 
@@ -135,7 +130,7 @@ Rules:
 
 **Focus:**
 
-- Focusable children inside the strip remain focusable. The scroll animation does not move focus. The edge mask clears on `:focus-within` so focus indicators are not clipped. Consumers that include interactive children should ensure those children are not announced twice; the `aria-hidden="true"` clone handles the announcement side.
+- Focusable children inside the strip remain focusable. The scroll animation does not move focus. The edge mask clears on `:focus-within` so focus indicators are not clipped. Consumers that include interactive children should ensure those children are not announced twice; the duplicate is both `aria-hidden` and inert, so it cannot add duplicate keyboard stops. Focus within the original pauses animation regardless of `pauseOnHover`.
 
 **Reduced motion:**
 

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

@@ -3,22 +3,14 @@ title: Menu
 status: canonical
 category: Components
 archetype: utility
-package_path: packages/d4gger-design-system/src/components/menu/Menu.tsx
-css_path: packages/d4gger-design-system/src/styles/components/menu.css
-props_path: packages/d4gger-design-system/src/components/menu/menu.props.ts
-test_path: packages/d4gger-design-system/src/test/components/menu-migration.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - "@radix-ui/react-dropdown-menu (the underlying Radix primitive; `MenuRoot`, `MenuTrigger`, `MenuItem`, and `MenuSeparator` proxy to it)"
-  - _internal/BaseDialog (PortalThemeBoundary + PortalThemeWrapper for portal theme mirroring; the abstraction does not have its own visual surface but it must mirror the wrapper's `data-dsx-*` attribute contract into the portal)
-  - _internal/motion (MOTION_TRANSITIONS.menu for the content open / close animation, MOTION_TRANSITIONS.reduced for `prefers-reduced-motion: reduce`)
-  - _internal/usePrefersReducedMotion (gates the content motion)
   - framer-motion (motion + AnimatePresence for the content open / close)
 ---
 
 # Menu
 
-> 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
 
@@ -137,7 +129,7 @@ Rules that apply to this row:
 |---|---|---|---|
 | `data-size` | `sm`, `md`, `lg` | (no CSS rule declared in `menu.css` today; the public menu surfaces add their own size overrides) | `menu.css` |
 | `data-state` | `open`, `closed` | `.dsx-menu[data-state='open']`, `.dsx-menu__content[data-state='open']` (in animation), `.dsx-menu[data-state='closed']`, `.dsx-menu__content[data-state='closed']` (out animation) | `menu.css` |
-| `data-highlighted` | (presence, written by Radix) | `.dsx-menu__item[data-highlighted]` (hover background; the broader hover state for all menu items lives in `_internal/baseMenu.css`) | `menu.css` (+ `_internal/baseMenu.css`) |
+| `data-highlighted` | (presence, written by Radix) | hover wash owned solely by `_internal/baseMenu.css` (`menu.css` declares no competing rule, so the shared 32% wash always wins) | `_internal/baseMenu.css` |
 | `data-disabled` | (presence, written by Radix) | `.dsx-menu__item[data-disabled]` (opacity fade, pointer-events off) | `menu.css` |
 | `data-destructive` | `'true'` | (no CSS rule in `menu.css`; the public menu surfaces add their own destructive variant) | n/a |
 | `data-inset` | `'true'` | (no CSS rule in `menu.css`; the public menu surfaces add their own inset padding) | n/a |
@@ -174,7 +166,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with three docum
 | Content transform origin | `var(--radix-dropdown-menu-content-transform-origin)` | Radix-provided anchor (not a token). |
 | Item gap | `var(--dsx-space-sm)` | Gap between item content. |
 | Item padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Inner gutter. |
-| Item radius | `var(--dsx-rounded-sm)` | Rounded highlight surface. |
+| Item radius | `0` (square); menu first/last/only-child edge rules restore frame-concentric corners | Stacked items read as one joined block instead of floating pills — checked washes, hover washes, and focus rings share one flush geometry. |
 | Item typography | `var(--dsx-typography-body-medium-*` | Body ramp. |
 | Item color | `var(--dsx-color-on-surface)` | Resting text. |
 | Item highlight background | `var(--dsx-effect-hover-ghost)` | Hover / keyboard-focus highlight. |
@@ -183,6 +175,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with three docum
 | Separator margin | `var(--dsx-space-xs)` calc(-1) | Inset margin. |
 | Separator background | `var(--dsx-color-outline-variant)` | Divider color. |
 | Overlay z-index | `calc(var(--dsx-z-index-dropdown) - 1)` | Just under the content. |
+| Nested content z-index | `calc(var(--dsx-z-index-modal, 90) + 2)` | Menu-tier content nested inside a modal-tier host (carries `dsx-menu__nested`). |
 | Animation duration | `var(--dsx-motion-duration-fast)` | Open / close keyframes. |
 | Animation easing (in) | `var(--dsx-motion-easing-emphasized)` | Open easing. |
 | Animation easing (out) | `var(--dsx-motion-easing-in)` | Close easing. |
@@ -192,9 +185,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with three docum
 Rules:
 
 - Tokens come from `DESIGN.md` and the generated `tokens.css`. The `1px` separator height is hard-coded to match the body `1px` baseline.
-- `menu.css` no longer declares `background`, `border`, `border-radius`, `padding`, `min-width`, or `box-shadow` on `.dsx-menu`/`.dsx-menu__content`. Those properties are owned solely by the public surface CSS (`dropdown-menu.css`, `context-menu.css`, `menubar.css`), which already agreed on the same recipe (`--dsx-color-surface-overlay`, `--dsx-rounded-lg`, `--dsx-size-menu-min-width`, `--dsx-shadow-elevation-3`-via-`baseMenu.css`). Previously `menu.css` was imported last in `components.css` and, at equal selector specificity, silently overrode that recipe with a stale one (`surface-raised`, `rounded-md`, hard-coded `8rem`, `shadow-md`/elevation-2) for `DropdownMenu` and `ContextMenu` only — `Menubar` was unaffected because `MenubarContent` never carried the `dsx-menu` class, which is why the three surfaces looked subtly different despite sharing a spec.
+- `menu.css` no longer declares `background`, `border`, `border-radius`, `padding`, `min-width`, or `box-shadow` on `.dsx-menu`/`.dsx-menu__content`. Those properties are owned solely by the public surface CSS (`dropdown-menu.css`, `context-menu.css`, `menubar.css`), which already agreed on the same recipe (`--dsx-color-panel-translucent`, `--dsx-rounded-lg`, `--dsx-size-menu-min-width`, `--dsx-shadow-elevation-3`-via-`baseMenu.css`). Previously `menu.css` was imported last in `components.css` and, at equal selector specificity, silently overrode that recipe with a stale one (`surface-raised`, `rounded-md`, hard-coded `8rem`, `shadow-md`/elevation-2) for `DropdownMenu` and `ContextMenu` only — `Menubar` was unaffected because `MenubarContent` never carried the `dsx-menu` class, which is why the three surfaces looked subtly different despite sharing a spec.
 - The Radix CSS variables (`--radix-dropdown-menu-content-available-height`, `--radix-dropdown-menu-content-transform-origin`) are provided by Radix at runtime and are not design tokens. They are the boundary between the Radix positioning layer and the package's visual layer; the spec keeps them explicit so consumers do not treat them as themable.
-- Item hover, focus, selected, and disabled states that are shared across the menu family (DropdownMenu, ContextMenu, Menubar) live in `_internal/baseMenu.css` rather than `menu.css`. The public menu surfaces import `baseMenu.css` to inherit those rules.
+- Item hover, focus, selected, and disabled states that are shared across the menu family (DropdownMenu, ContextMenu, Menubar, NavigationMenu trigger/link/viewport) live in `_internal/baseMenu.css` rather than `menu.css`. The public menu surfaces import `baseMenu.css` to inherit those rules.
+- **Nested floating tier (shared layering contract).** Menu-tier content (`Select`, `Combobox`, `DropdownMenu`/`ContextMenu`/`Menubar` via `MenuContent`) paints at the dropdown tier (50); modal-tier hosts (`Popover.Content` at `modal + 1`, `Dialog.Content` at `modal` — both body-portaled, with Radix copying the content `z-index` onto its wrapper) sit above it, so a menu opened inside one of those hosts paints behind its own host. Hosts provide `_internal/floatingLayer` `FloatingLayerHostContext` from their content; menu contents consume it and add `dsx-menu__nested`, resolved to `modal + 2` by `_internal/baseMenu.css`. A flat bump of `--dsx-z-index-dropdown` is rejected: a nested menu must clear 91 while a standalone page menu must stay below the modal overlay (80) so an open Dialog still masks page content — one static value cannot do both. Standalone menus never carry the class. The signal is provided at content level (not root) so `Combobox` — itself a `Popover` — never self-escalates. `AlertDialog.Content` inherits the host behavior through `Dialog.Content`. `Drawer` (vaul, own overlay tier) is out of scope.
 
 ## Motion contract
 
@@ -234,7 +228,8 @@ Rules:
 
 **Focus:**
 
-- Visible focus ring via the `_internal/baseMenu.css` rule `:where(:focus-visible) { box-shadow: var(--dsx-shadow-focus-ring) }`. The ring must remain visible on dark and light surfaces.
+- Visible focus ring via the `_internal/baseMenu.css` rule `:where(:focus-visible) { box-shadow: inset 0 0 0 2px var(--dsx-effect-ring-focus) }`. Inset so it never touches the menu frame. The ring must remain visible on dark and light surfaces.
+- Exception: highlighted + keyboard-focused items use an on-surface ring (later rule in the same file). On vivid accents the accent ring drowns in the accent wash (same hue — spark reads as "lost outlines"); the wash still carries the accent, the ring carries visibility.
 - Focus management for overlay menus: focus is trapped inside the menu while it is open; focus returns to the trigger on close. This is the standard Radix behavior.
 
 **Reduced motion:**
@@ -279,12 +274,14 @@ The `test_path` is `packages/d4gger-design-system/src/test/components/menu-migra
 - `_internal/usePrefersReducedMotion`: gates the framer-motion preset.
 - `framer-motion` (re-exported from `@d4gger/design-system/motion`): `motion` and `AnimatePresence` for the content animation.
 - `_internal/baseMenu.css`: shared item hover, focus, selected, and disabled rules. The public menu surfaces import `baseMenu.css` to inherit those rules; the `Menu` CSS file does not import it directly.
+- `_internal/floatingLayer`: `FloatingLayerHostContext` / `useFloatingLayerHost` for the nested floating tier. `MenuContent` consumes it and adds `dsx-menu__nested` when rendered inside a modal-tier host (see the Token mapping contract above).
 
 **Used by:**
 
 - `DropdownMenu` (canonical public surface): consumes `MenuRoot`, `MenuPortal`, `MenuContent`, `MenuItem`, `MenuSeparator`. Swaps `item`, `separator`, and `content` to `DropdownMenuPrimitive.*` and adds `dsx-dropdown-menu__*` classes.
 - `ContextMenu` (canonical public surface): same pattern, with `ContextMenuPrimitive.*` swaps.
 - `Menubar` (canonical public surface): same pattern, with `MenubarPrimitive.*` swaps; also passes `forceMount` on the content to keep submenus mounted.
+- `NavigationMenu` (canonical public surface): CSS-level only — it wraps a different Radix primitive (`@radix-ui/react-navigation-menu`) so it cannot consume the `Menu*` runtime wrappers, but its trigger / link / viewport states ride `_internal/baseMenu.css` (Q4 fold, 2026-09-19). Top-level bar-tab geometry stays nav-local; direct-link content panels use the dropdown-family panel gutter, edge-aware row radius, and body typography, with no pointer diamond. The bar does not create a backdrop root, leaving the nested viewport free to render the same glass treatment as portaled dropdown content; accessible root measurement anchors the viewport to the active trigger and flips it above when block-end space is insufficient (2026-09-20).
 
 `Menu` does not have other consumers. The `Menu` abstraction is internal and is not exported from `src/components/index.ts`. Apps should not import the named exports directly.
 
@@ -307,7 +304,7 @@ The `test_path` is `packages/d4gger-design-system/src/test/components/menu-migra
 - **`data-size` is not CSS-backed in `menu.css`.** The attribute is written on the content; the public menu surfaces add their own size overrides (for example, `dsx-dropdown-menu__content[data-size='sm']` if needed). The CSS file does not declare any size rules today.
 - **No `Menu` accessor is exposed via `Object.assign`.** Sibling compound components (`DropdownMenu`, `ContextMenu`, `Menubar`) attach their subcomponents via `Object.assign`. `Menu` does not. Consumers import the named exports directly.
 - **Separator height is hard-coded.** `height: 1px` is not a token; it matches the body `1px` baseline. A future revision should consider whether this belongs in the token set (for example, `--dsx-separator-height`).
-- **FIXED 2026-07-03 (visual triage V-1): `menu.css` was silently overriding the public surfaces' own recipe.** `.dsx-menu`/`.dsx-menu__content` used to declare `background: var(--dsx-color-surface-raised)`, `border-radius: var(--dsx-rounded-md)`, and `min-width: 8rem`, which — because `menu.css` imports last in `components.css` — won the cascade over `dropdown-menu.css`'s and `context-menu.css`'s own `surface-overlay`/`rounded-lg`/`--dsx-size-menu-min-width` recipe at equal specificity. This made `DropdownMenu` and `ContextMenu` render a duller, smaller-radius panel than `Menubar` (which was unaffected, since it never carries the `dsx-menu` class). Removed the conflicting declarations from `menu.css`; the per-surface CSS is now the single owner of panel visuals. See also the light-mode `--dsx-color-surface-overlay` token fix (was darker than `--dsx-color-background`, read as "muddy"; now lighter, so popovers read as lifted).
+- **FIXED 2026-07-03 (visual triage V-1): `menu.css` was silently overriding the public surfaces' own recipe.** `.dsx-menu`/`.dsx-menu__content` used to declare `background: var(--dsx-color-surface-raised)`, `border-radius: var(--dsx-rounded-md)`, and `min-width: 8rem`, which — because `menu.css` imports last in `components.css` — won the cascade over `dropdown-menu.css`'s and `context-menu.css`'s own `surface-overlay`/`rounded-lg`/`--dsx-size-menu-min-width` recipe at equal specificity. This made `DropdownMenu` and `ContextMenu` render a duller, smaller-radius panel than `Menubar` (which was unaffected, since it never carries the `dsx-menu` class). Removed the conflicting declarations from `menu.css`; the per-surface CSS is now the single owner of panel visuals. See also the light-mode `--dsx-color-panel-translucent` token fix (was darker than `--dsx-color-background`, read as "muddy"; now lighter, so popovers read as lifted).
 - **CSS keyframes are not gated by `prefers-reduced-motion`.** The `dsx-menu-in` and `dsx-menu-out` keyframes in `menu.css` are declared without a `prefers-reduced-motion: reduce` media query. The runtime prefers the framer-motion path, which is gated by `usePrefersReducedMotion`; the CSS keyframes only fire when a consumer force-mounts the content and bypasses `AnimatePresence`. The CSS keyframes should still be gated for full coverage.
 - **Roster says "utility" but the abstraction is closer to a `radix-wrapper` / `radix-compound`.** The roster's archetype column lists `Menu` as `utility` because it is internal and has no public visual surface. The runtime is a Radix compound (`MenuRoot` + `MenuTrigger` + `MenuContent` + `MenuItem` + `MenuSeparator` + `MenuPortal` + `MenuOverlay`) with a Radix dropdown-menu backend. The spec records the roster's `utility` archetype; the runtime shape is closer to `radix-compound` with an internal-only surface.
 

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

@@ -3,25 +3,15 @@ title: Menubar
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/menubar/Menubar.tsx
-css_path: packages/d4gger-design-system/src/styles/components/menubar.css
-props_path: packages/d4gger-design-system/src/components/menubar/menubar.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Menubar.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:
   - "@radix-ui/react-menubar (the underlying Radix primitive; `Menubar.Root` and the public subcomponents proxy to it)"
   - "@radix-ui/react-slot (powers `asChild` on the shortcut slot)"
-  - _internal/BaseDialog (PortalThemeBoundary + PortalThemeWrapper; mirrors the `data-dsx-*` attribute contract into the content and sub-content portals)
-  - _internal/motion (no `MOTION_TRANSITIONS` preset; the menubar content relies on Radix's default open / close transitions)
-  - _internal/helpers/extractProps (turns the prop defs on `Item`, `SubTrigger`, and `Shortcut` into merged class + style output)
   - Icon (the `chevron-right` glyph on the sub-trigger and the `check` / `minus` glyphs on checkbox items)
 ---
 
 # Menubar
 
-> 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
 
@@ -162,14 +152,14 @@ Every CSS value the component paints is a `var(--dsx-*)` token (the `menubar.css
 | Bar padding | `var(--dsx-space-xs)` | Internal bar gutter. |
 | Bar border radius | `var(--dsx-rounded-md)` | Bar corner roundness. |
 | Bar border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Bar edge ring. |
-| Bar background | `var(--dsx-color-surface-overlay)` | Bar surface. |
+| Bar background | `var(--dsx-color-panel-translucent)` | Bar surface. |
 | Trigger min-height | `var(--dsx-size-lg)` | Trigger touch target. |
 | Trigger padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Trigger gutter. |
 | Trigger border radius | `var(--dsx-rounded-md)` | Trigger corner roundness. |
 | Content min-width | `var(--dsx-size-menu-min-width)` | Dropdown minimum width. |
 | Content padding | `var(--dsx-space-xs)` | Content gutter. |
 | Content border radius | `var(--dsx-rounded-lg)` | Content corner roundness. |
-| Content background | `var(--dsx-color-surface-overlay)` | Dropdown surface. |
+| Content background | `var(--dsx-color-panel-translucent)` | Dropdown surface. |
 | Content border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Dropdown edge. |
 | Content z-index | `var(--dsx-z-index-dropdown)` | Stack above bar. |
 | Item min-height | `var(--dsx-size-lg)` | Item touch target. |

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

@@ -3,13 +3,6 @@ title: Metric
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/metric/Metric.tsx
-css_path: packages/d4gger-design-system/src/styles/components/metric.css
-props_path: packages/d4gger-design-system/src/components/metric/metric.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Metric.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:
   - Text
   - Icon
@@ -36,7 +29,7 @@ A surface-neutral metric anatomy for labels, tabular values, and semantic change
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Metric scale inherited by all slots. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Value typography scale inherited through context; label and delta retain their supporting type ramps. | no |
 | `asChild` | `boolean` | `false` | no | Uses the consumer host for the root. | no |
 | `className` | `string` | `undefined` | no | Appended root class. | no |
 
@@ -47,6 +40,7 @@ A surface-neutral metric anatomy for labels, tabular values, and semantic change
 - Root: `dsx-metric`; slots: `dsx-metric__label`, `dsx-metric__value`, `dsx-metric__delta`.
 - Root writes `data-size="sm|md|lg"`; Delta writes `data-tone="positive|negative|neutral"`.
 - The component is static and breakpoint-agnostic.
+- The root shrinks within the available width and wraps unbroken values or identifiers. Delta content can wrap without creating horizontal overflow. Consumers retain responsibility for meaningful number formatting.
 
 ## Token mapping
 
@@ -75,3 +69,5 @@ Show a default Metric, all three sizes, all three delta tones, a full compositio
 ## Wiring notes
 
 Metric owns anatomy, typography, tabular numerals, and delta presentation. Consumers own values, trend calculations, localization, and the surrounding Card or layout. `StatCard` composes this anatomy while preserving its legacy public contract.
+
+Playground appearance follows the global theme switcher. Accent demonstrations inherit that appearance; no forced light/dark example overrides it.