@d4gger/design-system 2.7.0 → 3.0.0

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
 

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 |
@@ -192,9 +184,9 @@ 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.
 
 ## Motion contract
 
@@ -234,7 +226,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:**
@@ -285,6 +278,7 @@ The `test_path` is `packages/d4gger-design-system/src/test/components/menu-migra
 - `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 +301,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

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

@@ -3,20 +3,14 @@ title: NativeSelect
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/nativeSelect/NativeSelect.tsx
-css_path: packages/d4gger-design-system/src/styles/components/native-select.css
-props_path: packages/d4gger-design-system/src/components/nativeSelect/nativeSelect.props.ts
-test_path: packages/d4gger-design-system/src/test/components/NativeSelect.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
-  - "_internal/baseInput.css (shared shell, border, hover, focus, disabled, and autofill contract with the Input primitive family)"
   - Field (form-row wrapper; `NativeSelect` is the intended leaf inside a `Field.Root` for select form rows)
   - "@radix-ui/react-slot (asChild on the root only)"
 ---
 
 # NativeSelect
 
-> 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
 
@@ -30,7 +24,7 @@ A native browser `<select>` wrapper that pairs the platform's mobile-friendly op
 
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
-| `NativeSelect.Root` | `<select>` (or slotted host) | `dsx-native-select` + `data-size`, `data-variant`, `data-radius`, `data-error` | The native form control. Forwards the standard `ComponentPropsWithoutRef<'select'>` minus `size`. |
+| `NativeSelect.Root` | `<select>` (or slotted host) | `dsx-native-select` + `data-size`, `data-variant`, `data-error` | The native form control. Forwards the standard `ComponentPropsWithoutRef<'select'>` minus `size`. |
 | `NativeSelect.Option` | `<option>` | `dsx-native-select__option` | One option row. |
 | `NativeSelect.OptionGroup` | `<optgroup>` | `dsx-native-select__option-group` | Grouping wrapper around `Option`s. |
 
@@ -40,10 +34,9 @@ The roster lists `NativeSelect.Root`, `NativeSelect.Option`, and `NativeSelect.O
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height and font size. Drives `data-size` and the size-specific CSS overrides. Also emits the matching `dsx-native-select-size-{value}` class via the prop def's `className`. | no |
-| `variant` | `'default' \| 'filled'` | `'default'` | no | Surface treatment. `'default'` is the bordered resting state; `'filled'` removes the border and uses the raised surface. Drives `data-variant` and the matching modifier class. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height and font size. Drives `data-size` and the size-specific CSS overrides. | no |
+| `variant` | `'default' \| 'filled'` | `'default'` | no | Surface treatment. `'default'` is the bordered resting state; `'filled'` removes the border and uses the raised surface. Drives `data-variant`. | no |
 | `error` | `boolean` | `false` | no | Marks the control as invalid. Writes `data-error="true"`, sets `aria-invalid="true"`, and switches the border color to `var(--dsx-color-error)` when true. | no |
-| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner radius override. Writes `data-radius`. The CSS does not currently declare matching `[data-radius='...']` overrides — see the Anomalies section. | no |
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. Only the root is polymorphic; the option and option-group slots are always native elements. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-native-select`. | no |
 | `style` | `React.CSSProperties` | `undefined` | no | Inline style forwarded to the root. | no |
@@ -63,23 +56,20 @@ Rules that apply to this row:
 - `NativeSelectRootProps` extends `Omit<React.ComponentPropsWithoutRef<'select'>, 'size'>` because `size` is redefined by the prop bag.
 - `asChild` is the only polymorphic infra and applies to the root only.
 - `NativeSelectOptionProps` and `NativeSelectOptionGroupProps` are bare aliases of `React.ComponentPropsWithoutRef<'option'>` and `React.ComponentPropsWithoutRef<'optgroup'>`; there is no extra prop bag.
-- The size and variant prop defs declare a `className` (`dsx-native-select-size`, `dsx-native-select-variant`) that joins the root class through `extractProps`. The result is that the root carries both `dsx-native-select` and `dsx-native-select-{size|variant}-{value}` plus the attribute selector target. The `[data-size='...']` rules in the CSS and the `dsx-native-select-size-*` class rules are functionally redundant today; see Anomalies.
+- The size and variant prop defs are data-attribute-only. An earlier revision also emitted `dsx-native-select-size-*` / `dsx-native-select-variant-*` modifier classes; the duplicate encoding was removed and `data-size` / `data-variant` are the single owner per axis.
 
 ## CSS class contract
 
 **Root class:** `dsx-native-select`
 
-**Modifier classes** (driven by `data-*` attributes written by the component, plus the size and variant prop-def classes):
+**Modifier classes** (driven by `data-*` attributes written by the component):
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-size` | `sm`, `md`, `lg` | `.dsx-native-select[data-size='sm']`, `.dsx-native-select[data-size='lg']` (no `md` rule) | `native-select.css` |
-| `data-size` | `sm`, `md`, `lg` | `dsx-native-select-size-sm`, `dsx-native-select-size-md`, `dsx-native-select-size-lg` (also emitted by the prop def's `className`) | `native-select.css` |
+| `data-size` | `sm`, `md`, `lg` | `.dsx-native-select[data-size='sm']`, `.dsx-native-select[data-size='lg']` (no `md` rule — defaults already match `md`) | `native-select.css` |
 | `data-variant` | `default`, `filled` | `.dsx-native-select[data-variant='filled']` | `native-select.css` |
-| `data-variant` | `default`, `filled` | `dsx-native-select-variant-default`, `dsx-native-select-variant-filled` (also emitted by the prop def's `className`) | `native-select.css` |
 | `data-error` | `'true'` | `.dsx-native-select[data-error='true']` | `native-select.css` |
 | `aria-invalid` | `'true'` | `.dsx-native-select[aria-invalid='true']` | `native-select.css` |
-| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (no CSS rule declared today; reserved for a future radius override) | `native-select.css` |
 
 **Slot classes:**
 
@@ -100,7 +90,7 @@ Rules that apply to this row:
 
 ## Token mapping
 
-Every CSS value the component paints is a `var(--dsx-*)` token, with one documented exception (the caret SVG).
+Every CSS value the component paints is a `var(--dsx-*)` token, except the caret SVG strokes, which are theme-resolved bakes of `var(--dsx-color-on-surface-variant)` (a data URL cannot consume `var()`).
 
 | Property | Token | Role |
 |---|---|---|
@@ -131,7 +121,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with one documen
 | Cursor (disabled) | `var(--dsx-cursor-disabled, not-allowed)` | Disabled cursor. |
 | Caret position | `right var(--dsx-space-sm) center` | Caret placement. |
 | Caret size | `var(--dsx-size-md)` | Caret box. |
-| Caret stroke (hard-coded) | `#888` (encoded in the inline SVG data URL) | Caret stroke. Not a token; see Anomalies. |
+| Caret stroke (dark) | `#93a1b5` baked in the data-URL SVG | Theme-resolved value of `var(--dsx-color-on-surface-variant)` on dark. A data-URL background cannot consume `var()` (external resource, no access to element style), so the token value is baked per theme and the light override below swaps it. |
+| Caret stroke (light) | `#55657a` baked in the `[data-dsx-theme='light']` override | Theme-resolved value of `var(--dsx-color-on-surface-variant)` on light. |
 | Size `sm` | `var(--dsx-density-control-height-sm, var(--dsx-size-lg))` + body-small font | Small control. |
 | Size `lg` | `var(--dsx-density-control-height-lg, var(--dsx-size-2xl))` + body-large font | Large control. |
 | Motion | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Surface, border, shadow, and color transitions. |
@@ -139,7 +130,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with one documen
 Rules:
 
 - The component imports `baseInput.css` so the shell, border, hover, focus, disabled, and autofill rules are shared with the `Input`, `TextField`, and `TextArea` family. The `:hover` rule for `dsx-native-select` overrides the shared hover surface with `var(--dsx-color-outline-variant)` and `var(--dsx-color-surface-hover)`.
-- `appearance: none` is declared so the native browser chevron is hidden in favor of the inline SVG. The SVG is `data:image/svg+xml,...` encoded; the stroke color is hard-coded to `#888` (`%23888` in the URL). It is the only non-token color in the file; see Anomalies.
+- `appearance: none` is declared so the native browser chevron is hidden in favor of the inline SVG. The SVG stroke is the theme-resolved `var(--dsx-color-on-surface-variant)` value baked into the data URL (`#93a1b5` dark, `#55657a` under `[data-dsx-theme='light']`), because a data-URL background cannot read `var()`.
 - The `autofill` rule comes from `baseInput.css` and applies to the native select via the shared `:where()` selectors. The local CSS does not redeclare it.
 
 ## Motion contract
@@ -229,7 +220,6 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 | `size` | select | `md` |
 | `variant` | select | `default` |
 | `error` | boolean | `false` |
-| `radius` | select | (none) |
 | `disabled` | boolean | `false` |
 | `asChild` | boolean | `false` |
 
@@ -248,21 +238,21 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 **State boundaries:**
 
-- Owned by NativeSelect: the `data-size`, `data-variant`, `data-radius`, and `data-error` attributes, the `aria-invalid` reflection, the size and variant prop-def classes, and the platform `<select>` semantics (open / close, type-ahead, keyboard navigation).
+- Owned by NativeSelect: the `data-size`, `data-variant`, and `data-error` attributes, the `aria-invalid` reflection, and the platform `<select>` semantics (open / close, type-ahead, keyboard navigation).
 - Owned by the consumer: the value, `onChange`, `disabled`, `required`, `multiple`, the option list, the host element when `asChild` is set, and the form-row layout (label, description, error) that wraps the component.
 
 **Boundary rules:**
 
 - App-owned data: the option list, the selected value, the validation rules, the persistence strategy, and the surrounding form context.
-- DS-owned visuals: token bindings, the `dsx-native-select` and slot classes, the `data-size`, `data-variant`, `data-radius`, and `data-error` attributes, the `aria-invalid` reflection, and the size and variant modifier classes.
+- DS-owned visuals: token bindings, the `dsx-native-select` and slot classes, the `data-size`, `data-variant`, and `data-error` attributes, and the `aria-invalid` reflection.
 - The component does not own a `Field` integration. Wrap in `Field.Root` at the app level for label, description, and error wiring.
 
 ## Anomalies
 
 - **Roster vs. runtime shape.** Resolved: the roster now lists the compound slots that match the runtime. `NativeSelect.Root`, `NativeSelect.Option`, and `NativeSelect.OptionGroup` are attached via `Object.assign` and are exercised by `src/test/components/NativeSelect.test.tsx`.
-- **`data-radius` is not CSS-backed.** The attribute is written by the runtime and listed on the prop bag, but `native-select.css` has no `[data-radius='...']` rule. The contract is reserved; the visual treatment is a future addition.
-- **Size and variant have redundant rules.** The `size` and `variant` prop defs both declare a `className` (`dsx-native-select-size`, `dsx-native-select-variant`) and the runtime writes `data-size` and `data-variant`. `native-select.css` declares both `.dsx-native-select[data-size='...']` and `.dsx-native-select-size-...` rules for `sm` and `lg`, plus `.dsx-native-select[data-variant='filled']` and `.dsx-native-select-variant-filled`. The two encodings are functionally equivalent; pick one path when the spec stabilizes. The `md` size has no `[data-size='md']` or `dsx-native-select-size-md` rule because the default values already match `md`.
-- **Caret stroke is hard-coded to `#888`.** The inline SVG used as the dropdown caret is encoded with `%23888` for the stroke color. This is a visual choice (neutral mid-gray) but it is not a token. The caret does not follow the theme. A future revision should move the caret to a token (for example, `var(--dsx-color-on-surface-variant)`) and the encoding will need to be regenerated, or replaced by a CSS-only caret (border rotation).
+- **`data-radius` removed.** Resolved: the attribute had no CSS backing and no consumer use, so the `radius` prop and the `data-radius` write were deleted. Corner radius stays on the `var(--dsx-rounded-md)` default.
+- **Size and variant dual encoding removed.** Resolved: the `dsx-native-select-size-*` / `dsx-native-select-variant-*` modifier classes are deleted; `data-size` / `data-variant` are the single owner per axis.
+- **Caret stroke is theme-resolved.** Resolved: the inline SVG stroke is the baked `var(--dsx-color-on-surface-variant)` value per theme (`#93a1b5` dark, `#55657a` under `[data-dsx-theme='light']`). A data-URL background cannot consume `var()` directly, so resolved values are baked and documented in the token mapping.
 - **The option-menu background does not theme.** `NativeSelect` writes `appearance: none`, so on platforms that respect the override the rendered dropdown list uses the OS default. The component does not paint a custom popover; the consumer cannot theme the option list from the package.
 - **`[FUTURE]` tag in `design-system-index.md`.** The roster notes that `NativeSelect` was marked `[FUTURE]` and "revisit when mobile-native patterns become standard." The component is implemented and tested today; the future-tag note predates the current implementation and should be retired when the roster is refreshed.
 
@@ -304,7 +294,7 @@ The package does not yet publish a Penpot asset for NativeSelect. Recipe is visu
 | Shell (filled) | fill | `--dsx-color-surface-raised` | Color | `fills` (variant) |
 | Text | color | `--dsx-color-on-surface` | Color | `fills` |
 | Text | typography | `--dsx-typography-body-medium-*` | Typography | `typography` |
-| Caret | stroke | `#888` (hard-coded) | Color | `strokes` (see Anomalies) |
+| Caret | stroke | theme-resolved `on-surface-variant` bake | Color | `strokes` (see token mapping) |
 | Caret | size | `--dsx-size-md` | Sizing | `size` |
 
 ### State transformations
@@ -325,13 +315,11 @@ The package does not yet publish a Penpot asset for NativeSelect. Recipe is visu
 - `size`: `sm`, `md`, `lg`. Default `md`.
 - `variant`: `default`, `filled`. Default `default`.
 - `error`: `true`, `false`. Default `false`.
-- `radius`: `none`, `sm`, `md`, `lg`, `full`. Default `md` (from the root).
-- Total members: 3 × 2 × 2 × 5 = 60.
+- Total members: 3 × 2 × 2 = 12.
 
 ### Validation checklist
 
 - [ ] Token bindings resolve at the values `DESIGN.md` describes.
 - [ ] Component is promoted to Main Component under `Components`.
 - [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
-- [ ] Caret stroke is documented as hard-coded `#888`; the spec marks it as a tokenization target.
-- [ ] `data-radius` slot exists in Penpot but resolves to no visual change today; document the reservation.
+- [ ] Caret stroke matches the theme-resolved `on-surface-variant` value per theme; the spec marks the bake as intentional (data URLs cannot read `var()`).