@d4gger/design-system 2.7.0 → 3.0.1

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()`).

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

@@ -3,22 +3,14 @@ title: NavigationMenu
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/navigationMenu/NavigationMenu.tsx
-css_path: packages/d4gger-design-system/src/styles/components/navigation-menu.css
-props_path: packages/d4gger-design-system/src/components/navigationMenu/navigationMenu.props.ts
-test_path: packages/d4gger-design-system/src/test/components/NavigationMenu.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-navigation-menu (the underlying Radix primitive; `NavigationMenu.Root`, `List`, `Item`, `Trigger`, `Content`, `Link`, `Indicator`, `Viewport` proxy to it)"
-  - _internal/helpers/extractProps (turns the `Link` prop def into merged class + style output)
   - Icon (the `chevron-down` glyph on the trigger)
 ---
 
 # NavigationMenu
 
-> 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
 
@@ -26,20 +18,20 @@ A horizontal top-level site navigation surface that supports link lists plus con
 
 ## Anatomy & slots
 
-**Parent:** `NavigationMenu` (alias of `NavigationMenu.Root`). The root renders a `NavigationMenuViewport` automatically so the consumer does not need to mount it.
+**Parent:** `NavigationMenu` (alias of `NavigationMenu.Root`). The root renders a `NavigationMenuViewport` automatically and measures the active trigger, so the consumer does not need to mount or position the panel.
 
 **Slots:**
 
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
-| `NavigationMenu.Root` | Radix `NavigationMenu.Root` | `dsx-navigation-menu` + `data-size` (`sm` \| `md` \| `lg`) | The horizontal bar plus the auto-mounted viewport. |
+| `NavigationMenu.Root` | Radix `NavigationMenu.Root` | `dsx-navigation-menu` + `data-size` (`sm` \| `md` \| `lg`) | The horizontal bar plus the auto-mounted, active-trigger-positioned viewport. |
 | `NavigationMenu.List` | Radix `NavigationMenu.List` | `dsx-navigation-menu__list` | The horizontal list of items. |
 | `NavigationMenu.Item` | Radix `NavigationMenu.Item` | (no class) | A single top-level nav item. |
 | `NavigationMenu.Trigger` | Radix `NavigationMenu.Trigger` | `dsx-navigation-menu__trigger` + `dsx-navigation-menu__chevron` | The button that opens the content panel. |
 | `NavigationMenu.Content` | Radix `NavigationMenu.Content` | `dsx-navigation-menu__content` | The panel that appears in the viewport. |
 | `NavigationMenu.Link` | Radix `NavigationMenu.Link` | `dsx-navigation-menu__link` + optional `data-active` | A direct link (no panel). |
-| `NavigationMenu.Indicator` | Radix `NavigationMenu.Indicator` | `dsx-navigation-menu__indicator` | The animated highlight under the active trigger. |
-| `NavigationMenu.Viewport` | Radix `NavigationMenu.Viewport` | `dsx-navigation-menu__viewport` | The shared panel container. Auto-mounted by the root. |
+| `NavigationMenu.Indicator` | Radix `NavigationMenu.Indicator` | `dsx-navigation-menu__indicator` | Compatibility proxy for the Radix part. It has no default visual; the trigger chevron is the sole open-state affordance. |
+| `NavigationMenu.Viewport` | Radix `NavigationMenu.Viewport` | `dsx-navigation-menu__viewport` | The shared panel container. Auto-mounted by the root and positioned at the active trigger's start edge. |
 
 The roster's `Parent / Slots` column lists `NavigationMenu.Root`, `NavigationMenu.List`, `NavigationMenu.Item`, `NavigationMenu.Trigger`, `NavigationMenu.Content`, `NavigationMenu.Link`, `NavigationMenu.Indicator`, `NavigationMenu.Viewport`. The source exports all of them through `Object.assign`. The spec records the full set so the public surface is unambiguous.
 
@@ -62,7 +54,7 @@ The roster's `Parent / Slots` column lists `NavigationMenu.Root`, `NavigationMen
 
 ### `NavigationMenu.List`, `NavigationMenu.Item`, `NavigationMenu.Trigger`, `NavigationMenu.Content`, `NavigationMenu.Indicator`, `NavigationMenu.Viewport`
 
-Each proxies the corresponding Radix prop bag. `Trigger` and `Content` accept the Radix `align`, `side`, and `sideOffset` props verbatim. `List` accepts the Radix `asChild` and `className` props. The remaining slots forward the Radix data and ARIA props.
+Each proxies the corresponding Radix prop bag. Unlike Popper-based `DropdownMenu.Content`, Radix NavigationMenu content does not expose `align`, `side`, or `sideOffset`; the root owns active-trigger anchoring and viewport collision placement. `List` accepts the Radix `asChild` and `className` props. The remaining slots forward the Radix data and ARIA props.
 
 ### `NavigationMenu.Link`
 
@@ -77,7 +69,7 @@ Each proxies the corresponding Radix prop bag. `Trigger` and `Content` accept th
 Rules:
 
 - `NavigationMenu.Link` runs through `extractProps` with the `navigationMenuLinkPropDefs` bag; the rest of the slots forward the Radix prop bag as-is.
-- The root auto-mounts `NavigationMenuViewport`. Consumers do not need to render it; the auto-mount is what makes the content panel appear under the bar.
+- The root auto-mounts `NavigationMenuViewport`, measures the open trigger and viewport, and writes the collision-aware physical offset plus `data-position="top|bottom"`. Consumers do not need to render or position the viewport; the public `NavigationMenu.Indicator` remains a no-visual compatibility proxy.
 
 ## CSS class contract
 
@@ -88,15 +80,16 @@ Rules:
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | `data-size` | `sm`, `md`, `lg` | (sizing token bindings) | `navigation-menu.css` |
-| `data-active` | `true` | `.dsx-navigation-menu__link[data-active='true']` | `navigation-menu.css` |
-| `data-state` | `open`, `closed` (Radix-native) | `.dsx-navigation-menu__trigger[data-state='open']` | `navigation-menu.css` |
-| `data-disabled` | (Radix-native) | `.dsx-navigation-menu__trigger[data-disabled]` | `navigation-menu.css` |
+| `data-active` | `true` | shared hover/active wash (Q4 fold) | `_internal/baseMenu.css` |
+| `data-state` | `open`, `closed` (Radix-native) | shared open wash on trigger + viewport enter animation | `_internal/baseMenu.css` (wash) + `navigation-menu.css` (enter keyframes) |
+| `data-disabled` | (Radix-native) | shared disabled treatment on trigger | `_internal/baseMenu.css` |
+| `data-position` | `top`, `bottom` (root measurement) | viewport block-side placement | `navigation-menu.css` |
 
 **Modifier classes (prop-def-derived):**
 
 | Source prop | Class | CSS file |
 |---|---|---|
-| `active` (on `Link`) | `dsx-navigation-menu-link-active` | `navigation-menu.css` |
+| `active` (on `Link`) | `dsx-navigation-menu-link-active` (alias for `data-active`, kept for contract) | `_internal/baseMenu.css` |
 
 **Slot classes:**
 
@@ -128,34 +121,39 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Bar gap | `var(--dsx-space-xs)` | Gap between top-level items. |
 | 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 border | `var(--dsx-border-width-sm) solid var(--dsx-panel-border-color)` | Shared panel edge ring. |
+| Bar background | `var(--dsx-color-panel-translucent)` | Bar surface. |
 | List display | `flex` (CSS keyword) | Horizontal list. |
 | List gap | `var(--dsx-space-sm)` | Gap between items. |
-| Trigger / link min-height | `var(--dsx-size-lg)` | Touch target. |
-| Trigger / link padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Internal gutter. |
-| Trigger / link border radius | `var(--dsx-rounded-md)` | Corner roundness. |
+| Top-level trigger / link min-height | `var(--dsx-size-lg)` | Touch target. |
+| Top-level trigger / link padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Bar-tab gutter. |
+| Top-level trigger / link border radius | `var(--dsx-rounded-md)` | Bar-tab corner roundness. |
 | Trigger / link color | `var(--dsx-color-on-surface)` | Default text color. |
-| Trigger / link hover / open | `var(--dsx-color-high-contrast-container)` + `var(--dsx-color-high-contrast)` | Hover and open highlight. |
-| Focus ring | `var(--dsx-shadow-focus-ring)` | `:focus-visible` ring. |
-| Disabled opacity | `var(--dsx-opacity-disabled)` | Disabled item opacity. |
-| Content padding | `var(--dsx-space-md)` | Panel inner gutter. |
+| Trigger / link hover / open | `var(--dsx-effect-hover-emphasis-strong)` + `var(--dsx-color-on-surface)` | Hover and open highlight — shared with the menu family via `_internal/baseMenu.css` (Q4 fold). |
+| Link active (current page) | `color-mix(accent-3 50%)` + `var(--dsx-color-accent-indicator)` + `var(--dsx-shadow-active-inset-outline)` | Persistent active: deeper wash + indicator text + inset bottom bar (sidebar-active language); deliberately distinct from the transient hover wash. Nav-local rule. |
+| Focus ring | inset `var(--dsx-effect-ring-focus)` | `:focus-visible` ring — shared with the menu family via `_internal/baseMenu.css` (Q4 fold). |
+| Disabled | `var(--dsx-color-disabled-text)` + `var(--dsx-effect-disabled-layer)` | Disabled trigger treatment — shared with the menu family via `_internal/baseMenu.css` (Q4 fold). |
+| Content padding | `var(--dsx-space-xs)` | Dropdown-family panel gutter. |
+| Direct-link content minimum width | `var(--dsx-size-menu-min-width)` | Matches the compact menu-family floor. |
+| Direct submenu link padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Dropdown-family row gutter. |
+| Direct submenu link border radius | `var(--dsx-rounded-sm)`; edge links use the dropdown-family concentric `outer radius - gutter - border` recipe | Dropdown-family row corner roundness. |
+| Direct submenu link typography | `var(--dsx-typography-body-medium-*)` | Dropdown-family row type. |
 | Viewport z-index | `var(--dsx-z-index-dropdown)` | Stack above page. |
 | Viewport border radius | `var(--dsx-rounded-lg)` | Panel corner roundness. |
-| Viewport background | `var(--dsx-color-surface-overlay)` | Panel surface. |
-| Viewport border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Panel edge. |
-| Viewport shadow | `var(--dsx-shadow-elevation-4)` | Panel elevation. |
+| Viewport background | `var(--dsx-color-panel-translucent)` | Panel surface. |
+| Viewport border | `var(--dsx-border-width-sm) solid var(--dsx-panel-border-color)` | Shared panel edge. |
+| Viewport shadow | `var(--dsx-shadow-elevation-3)` (via `_internal/baseMenu.css`) | Panel elevation — shared with the menu family (Q4 fold). |
 | Viewport width | `min(calc(100vw - var(--dsx-dialog-viewport-gap)), var(--dsx-breakpoint-sm))` | Panel width cap. |
-| Indicator height | `var(--dsx-navigation-menu-indicator-size)` | Active marker height. |
-| Indicator size | `var(--dsx-navigation-menu-indicator-size)` | Active marker width. |
-| Indicator border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Active marker top + left edge. |
-| Indicator background | `var(--dsx-color-surface-overlay)` | Active marker fill. |
 | Motion duration | `var(--dsx-motion-duration-fast, 150ms)` | Trigger and viewport transitions. |
 | Motion easing | `var(--dsx-motion-easing-standard, ease)` | Trigger and viewport easing. |
 
 Rules:
 
 - No raw color, spacing, radius, or motion values in `navigation-menu.css`.
+- The root measures the open trigger and viewport before paint. It aligns the panel's logical start edge to that trigger, clamps the panel to the viewport gap, observes trigger/root/panel resizing, and flips above when the available block-end space is insufficient. The interactive viewport remains a direct, assistive-technology-visible child of the navigation root; it must never be nested under Radix's `aria-hidden` Indicator.
+- The top-level bar intentionally does not apply `backdrop-filter`: as the viewport's ancestor, that would create a nested backdrop root and prevent the submenu from sampling the page backdrop like a portaled DropdownMenu. The viewport owns the family glass filter, so its translucent background renders with the same visual density instead of exposing page dividers.
+- State visuals (hover / open / active wash, focus ring, disabled) are owned by `_internal/baseMenu.css`, not this file: Radix navigation-menu never writes `data-highlighted`, so the shared rule names `:hover` / `data-state='open'` / `data-active` directly. Top-level bar-tab geometry stays nav-local; a content panel made from direct `NavigationMenu.Link` children adopts the dropdown-family row geometry and typography (Q4, 2026-09-20).
+- `NavigationMenu.Indicator` remains exported for Radix API parity but carries no package visual. The open trigger's chevron is the only direction indicator, matching the rest of the dropdown family.
 - The viewport open animation (`dsx-navigation-menu-enter`) translates from `-1 * var(--dsx-space-xs)` to `0` over the standard fast duration. The keyframes are declared in `navigation-menu.css` and use only tokens.
 
 ## Motion contract
@@ -195,7 +193,7 @@ Rules:
 
 **Focus:**
 
-- The CSS file paints a `var(--dsx-shadow-focus-ring)` ring on `:focus-visible` for both the trigger and the link. The ring stays visible on dark and light surfaces.
+- The CSS file paints the shared inset `var(--dsx-effect-ring-focus)` ring on `:focus-visible` for both the trigger and the link (rule lives in `_internal/baseMenu.css`). The ring stays visible on dark and light surfaces.
 
 **Reduced motion:**
 

package/dist/docs/{notification-center.md → components/notification-center.md}

@@ -3,13 +3,6 @@ title: NotificationCenter
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/notificationCenter/NotificationCenter.tsx
-css_path: packages/d4gger-design-system/src/styles/components/notification-center.css
-props_path: packages/d4gger-design-system/src/components/notificationCenter/notificationCenter.props.ts
-test_path: packages/d4gger-design-system/src/test/components/NotificationCenter.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/overlay.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - IconButton
   - Badge
@@ -17,7 +10,7 @@ depends_on:
 
 # NotificationCenter
 
-> 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
 
@@ -41,7 +34,7 @@ An inbox-style notification surface that groups header, list, and footer regions
 **Internal layout:**
 
 - The root is a flex column. The header sits at the top, the list fills the middle, the footer sits at the bottom.
-- In the `popover` variant (the default), the root is sized `width: 320px`, has a `var(--dsx-rounded-lg)` radius, a 1px outline, an `var(--dsx-color-surface-overlay)` background, and a `var(--dsx-shadow-card-md)` shadow.
+- In the `popover` variant (the default), the root is sized `width: 320px`, has a `var(--dsx-rounded-lg)` radius, a 1px outline, an `var(--dsx-color-panel-translucent)` background, and a `var(--dsx-shadow-card-md)` shadow.
 - In the `sidebar` variant, the root is full-width / full-height with a flat `var(--dsx-color-surface)` background and no border or shadow.
 - `NotificationCenter.Item` rows have a `var(--dsx-space-md)` padding and a 1px bottom border. The last item drops the bottom border. The item background switches to `var(--dsx-color-surface-raised)` with a 1px primary left border when `unread` is true.
 - `NotificationCenter.Trigger` is a positioned `inline-flex` container. The badge is absolutely positioned in the top-right corner with a `-var(--dsx-space-xs)` offset, a `var(--dsx-rounded-full)` radius, and label-small typography.
@@ -123,7 +116,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Popover width | `320px` | Popover variant width |
 | Popover border-radius | `var(--dsx-rounded-lg)` | Popover roundness |
 | Popover border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Popover edge |
-| Popover background | `var(--dsx-color-surface-overlay)` | Popover surface |
+| Popover background | `var(--dsx-color-panel-translucent)` | Popover surface |
 | Popover shadow | `var(--dsx-shadow-card-md)` | Popover elevation |
 | Sidebar background | `var(--dsx-color-surface)` | Sidebar surface |
 | Header padding | `var(--dsx-space-md)` | Header gutter |

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

@@ -3,11 +3,6 @@ title: NumberInput
 status: canonical
 category: Components
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/numberInput/NumberInput.tsx
-css_path: packages/d4gger-design-system/src/styles/components/number-input.css
-props_path: packages/d4gger-design-system/src/components/numberInput/numberInput.props.ts
-test_path: packages/d4gger-design-system/src/test/components/NumberInput.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - Input (token-aligned input shell; the runtime host shares its visual treatment via `dsx-input-shell`)
   - IconButton (the increment and decrement steppers; in source they are native `<button>` elements styled to match the DS IconButton surface)
@@ -16,7 +11,7 @@ depends_on:
 
 # NumberInput
 
-> 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
 
@@ -39,9 +34,13 @@ The implementation is intentionally written in source rather than by composing t
 | `value` | `number` | `undefined` | no | Controlled value. When set, the component is controlled; `onChange` is the only path to update it. | no |
 | `defaultValue` | `number` | `undefined` | no | Initial value for the uncontrolled mode. The component seeds `useState` with this value. | no |
 | `onChange` | `(value: number \| undefined) => void` | `undefined` | no | Called with the parsed value on every change. Emits `undefined` when the input is empty or `-`. | no |
-| `min` | `number` | `undefined` | no | Lower bound. The down stepper is disabled when the current value is at or below `min`. | no |
-| `max` | `number` | `undefined` | no | Upper bound. The up stepper is disabled when the current value is at or above `max`. | no |
-| `step` | `number` | `1` | no | Increment and decrement amount. | no |
+| `min` | `number` | `undefined` | no | Lower bound. The down stepper is disabled when the current value is at or below `min`; typed values commit-clamp to `min` on blur/Enter. | no |
+| `max` | `number` | `undefined` | no | Upper bound. The up stepper is disabled when the current value is at or above `max`; typed values commit-clamp to `max` on blur/Enter. | no |
+| `step` | `number` | `1` | no | Increment and decrement amount for the steppers and plain ArrowUp/ArrowDown. | no |
+| `largeStep` | `number` | `step * 10` | no | Step amount while Shift is held — Shift+Arrow keys and Shift+click on the chevrons. Playground control offers 5/10/25. | no |
+| `smallStep` | `number` | `step / 10` | no | Step amount while Alt is held — Alt+Arrow keys and Alt+click on the chevrons (PageUp/PageDown also step by `largeStep` where Alt is intercepted by the environment). Playground control offers 0.1/0.5. | no |
+| `stepperLayout` | `'stacked' \| 'split'` | `'stacked'` | no | Stepper placement. `stacked` is the trailing up/down column; `split` flanks the value (decrement left, increment right, centered value) for touch-friendly quantity rows. Writes `data-stepper-layout` plus the `dsx-number-input--split` modifier class. | no |
+| `stepperIcon` | `'chevrons' \| 'minus-plus'` | `'chevrons'` | no | Stepper glyphs. `minus-plus` renders −/+ instead of chevrons in either layout. | no |
 | `variant` | `'surface' \| 'classic' \| 'ghost'` | `'surface'` | no | Visual treatment. `'classic'` adds an elevation shadow; `'ghost'` removes border and background until focused. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height and inner padding. Drives the `data-size` attribute and the size-specific CSS overrides. | no |
 | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Shell corner radius override. Drives the `data-radius` attribute and the corresponding CSS rules. | no |
@@ -130,7 +129,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Shell border (default) | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` + `var(--dsx-color-surface)` | Default surface. |
 | Shell radius | `var(--dsx-rounded-md)` (default) | Default corner radius. |
 | Shell radius (overrides) | `none`, `--dsx-rounded-sm\|md\|lg\|full` | Driven by `data-radius`. |
-| Shell elevation (`classic`) | `var(--dsx-effect-shadow-1)` | Classic variant shadow. |
+| Shell elevation (`classic`) | `var(--dsx-shadow-elevation-2)` | Classic variant shadow. |
 | Shell background (`ghost`) | `transparent` until focus-within, then `--dsx-color-surface` | Ghost variant. |
 | Autofill background | `var(--dsx-color-surface-field-autofill)` (via `baseInput.css`) | Browser autofill. |
 | Motion | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-in-out)` | Stepper and shell transitions. |
@@ -288,7 +287,7 @@ The package does not yet publish a Penpot asset for NumberInput. Recipe is visua
 | Shell | radius | `--dsx-rounded-md` | Radius | `radius` |
 | Shell (focus) | stroke | `--dsx-color-primary` | Color | `strokes` (state) |
 | Shell (focus) | shadow | `--dsx-shadow-focus-ring` | Effect | `shadow` (state) |
-| Shell (classic) | shadow | `--dsx-effect-shadow-1` | Effect | `shadow` (variant) |
+| Shell (classic) | shadow | `--dsx-shadow-elevation-2` | Effect | `shadow` (variant) |
 | Shell (ghost) | fill | `transparent` | Color | `fills` (variant) |
 | Stepper column | width | `--dsx-space-lg` | Sizing | `width` |
 | Stepper separator | stroke | `--dsx-color-outline` | Color | `strokes` |
@@ -306,7 +305,7 @@ The package does not yet publish a Penpot asset for NumberInput. Recipe is visua
 | `hover` | `--dsx-color-outline-variant` | `--dsx-color-surface-hover` | none | `transparent` |
 | `focus` | `--dsx-color-primary` | `--dsx-color-surface` | `--dsx-shadow-focus-ring` | `transparent` |
 | `disabled` | `--dsx-effect-disabled-layer` | `--dsx-effect-disabled-layer` | none | `transparent` (with `--dsx-opacity-disabled` fade) |
-| `classic` | `--dsx-color-outline` | `--dsx-color-surface` | `--dsx-effect-shadow-1` | `transparent` |
+| `classic` | `--dsx-color-outline` | `--dsx-color-surface-raised` | `--dsx-shadow-elevation-2` | `transparent` |
 | `ghost` (rest) | `transparent` | `transparent` | none | `transparent` |
 | `ghost` (focus) | `--dsx-color-primary` | `--dsx-color-surface` | `--dsx-shadow-focus-ring` | `transparent` |
 

package/dist/docs/{page-content.md → components/page-content.md}

@@ -3,13 +3,6 @@ title: PageContent
 status: canonical
 category: Components
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/pageContent/PageContent.tsx
-css_path: packages/d4gger-design-system/src/styles/components/page-content.css
-props_path: packages/d4gger-design-system/src/components/pageContent/pageContent.props.ts
-test_path: packages/d4gger-design-system/src/test/components/PageContent.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:
   - Sidebar
   - PageHeader
@@ -17,7 +10,7 @@ depends_on:
 
 # PageContent
 
-> 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/{page-header.md → components/page-header.md}

@@ -3,20 +3,13 @@ title: PageHeader
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/pageHeader/PageHeader.tsx
-css_path: packages/d4gger-design-system/src/styles/components/page-header.css
-props_path: packages/d4gger-design-system/src/components/pageHeader/pageHeader.props.ts
-test_path: packages/d4gger-design-system/src/test/components/PageHeader.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:
   - Sidebar
 ---
 
 # PageHeader
 
-> 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