@d4gger/design-system 2.7.0 → 3.0.0

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
 

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

@@ -3,22 +3,14 @@ title: Pagination
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/pagination/Pagination.tsx
-css_path: packages/d4gger-design-system/src/styles/components/pagination.css
-props_path: packages/d4gger-design-system/src/components/pagination/pagination.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Pagination.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-slot (powers `asChild` on the root, list, item, link, and ellipsis slots)"
-  - _internal/helpers/extractProps (turns the prop defs on `Pagination`, `Pagination.List`, `Pagination.Item`, `Pagination.Link`, and `Pagination.Ellipsis` into merged class + style output)
   - Icon (the `chevron-left` / `chevron-right` glyphs on `Previous` / `Next`; the `dots-horizontal` glyph on `Ellipsis`)
 ---
 
 # Pagination
 
-> 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/{password-input.md → components/password-input.md}

@@ -3,23 +3,17 @@ title: PasswordInput
 status: canonical
 category: Components
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/passwordInput/PasswordInput.tsx
-css_path: packages/d4gger-design-system/src/styles/components/password-input.css
-props_path: packages/d4gger-design-system/src/components/passwordInput/passwordInput.props.ts
-test_path: packages/d4gger-design-system/src/test/components/PasswordInput.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - Input (the inner `<input>` reuses the body-medium typography and the disabled / autofill contract from `baseInput.css`; the runtime does not import the `Input` component, but the visual treatment is aligned with the `Input` shell)
   - IconButton (the visibility toggle is a native `<button>` styled to match the `IconButton` primitive at the same size; the TSX does not import `IconButton`)
   - Icon (lucide-react `Eye`, `EyeOff`)
-  - "_internal/baseInput.css (shared placeholder color, disabled cursor, autofill, and the `dsx-input-shell` styling reused on the inner shell)"
   - Field (form-row wrapper; `PasswordInput` is the intended leaf inside a `Field.Root` for password form rows)
   - "@radix-ui/react-slot"
 ---
 
 # PasswordInput
 
-> 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
 
@@ -87,8 +81,8 @@ Rules that apply to this row:
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | `data-size` | `sm`, `md`, `lg` | `dsx-password-input--sm`, `dsx-password-input--md`, `dsx-password-input--lg` (applied in TSX, not via `extractProps`); no CSS rule for `[data-size='...']` | `password-input.css` |
-| `data-variant` | `surface`, `classic`, `ghost` | (no CSS rule declared today; reserved) | `password-input.css` |
-| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (no CSS rule declared today; reserved) | `password-input.css` |
+| `data-variant` | `surface`, `classic`, `ghost` | Classic paints raised fill + elevation; ghost is transparent until focus. | `password-input.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | Shell border-radius follows the matching `var(--dsx-rounded-*)` token. | `password-input.css` |
 
 **Slot classes:**
 
@@ -276,8 +270,8 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 ## Anomalies
 
 - **`density` prop writes `data-size`, not `data-density`.** The prop is named `density` on the bag, but the runtime writes `data-size="sm"\|"md"\|"lg"`. The CSS consumes the modifier class `dsx-password-input--{value}` (added in the TSX), not the `data-size` attribute. The naming split is intentional in the source but the attribute name is misleading for consumers that inspect the DOM. A future revision should align the attribute name with the prop name (or rename the prop to `size`).
-- **`data-variant` is not CSS-backed.** `variant` is declared on the prop bag with `surface`, `classic`, and `ghost` values, but `password-input.css` has no `[data-variant='...']` rules. All three variants render with the same shell treatment today; the contract is reserved.
-- **`data-radius` is not CSS-backed.** The attribute is written by the runtime and listed on the prop bag, but `password-input.css` has no `[data-radius='...']` rule. The shell uses the default `var(--dsx-rounded-md)` from `baseInput.css`. The contract is reserved.
+- **`data-variant` is CSS-backed.** `classic` paints raised fill + elevation, `ghost` is transparent until focus — see `password-input.css`.
+- **`data-radius` is CSS-backed.** The shell border-radius follows the matching `var(--dsx-rounded-*)` token.
 - **Toggle button is not in the tab order.** `tabIndex={-1}` is hard-coded in the TSX. The intent is to keep the natural tab order between fields, but keyboard users that need to toggle visibility (and screen reader users that reach the toggle) cannot focus the button without a script. A future revision should expose `toggleTabIndex` (or remove the `tabIndex={-1}`) so the toggle is reachable by default.
 - **Roster reconciled to primitive.** The roster originally listed `PasswordInput` as `composite` with `Composed From: Input, IconButton`. The runtime is a single forwardRef without `Object.assign`; the inner input and toggle are implementation details, not named slots. The roster was updated to `primitive` and the `Composed From` column was cleared. The spec follows that classification.
 - **The roster's `Composed From` column lists `Input` and `IconButton`, but the TSX does not import either.** The alignment is via shared CSS classes and tokens, not via React composition. The `depends_on` block at the top of this spec records both relationships.

package/dist/docs/components/phone-input.md

@@ -0,0 +1,74 @@
+---
+title: PhoneInput
+status: canonical
+category: Components
+archetype: composite
+depends_on:
+  - Label (the label slot renders through the `Label` primitive for accessible `<label htmlFor>` association)
+  - Text (the helper and error text slots render through the `Text` primitive at the `label-small` ramp)
+  - "libphonenumber-js (optional peer: country list, dial codes, as-you-type formatting, E.164 parsing)"
+  - "@radix-ui/react-slot"
+---
+
+# PhoneInput
+
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+
+## Purpose
+
+An international phone-number entry control. A custom country dropdown feeds the dial prefix into a national `<input>` powered by the `react-phone-number-input/input` engine (parsing, as-you-type formatting, smart caret — no CSS taken from the lib); the component value is always an E.164 string (`+15551234567`) or `undefined` when empty. Country switching re-parses the current value under the new prefix. No flag assets: countries render as text codes (`US +1`), no emoji. Use `PhoneInput` for any phone collection; for plain numeric entry use `NumberInput`.
+
+## Anatomy & slots
+
+**Parent:** `PhoneInput` (flat export, no compound subcomponents).
+
+No slots: the component renders a root `<div>` (`dsx-phone-input` + density/variant/invalid modifiers, `data-size`/`data-variant`), a `Label`, a shell `<div>` hosting the country dropdown (`dsx-phone-input__country`: button + searchable listbox, divider stretches full shell height via `align-self: stretch`) and the engine-driven national `<input type="tel" inputMode="tel" autoComplete="tel">` (`dsx-phone-input__input`), plus helper/error text.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `value` | `string` (E.164) | `undefined` | no | Controlled value. When set, the component is controlled. | no |
+| `defaultValue` | `string` (E.164) | `undefined` | no | Initial value for uncontrolled mode. The initial country is detected from it. | no |
+| `onChange` | `(value: string \| undefined) => void` | `undefined` | no | Called with the E.164 value on every change; `undefined` when the field is cleared. | no |
+| `defaultCountry` | `CountryCode` | `'US'` | no | Fallback country when the value carries no detectable prefix. | no |
+| `countries` | `readonly CountryCode[]` | all `getCountries()` | no | Allowed country list for the select, sorted by English region name. | no |
+| `label` | `string` | `undefined` | no | Optional label string bound via `htmlFor`. | no |
+| `helperText` | `string` | `undefined` | no | Optional helper text, hidden when invalid. | no |
+| `errorText` | `string` | `undefined` | no | Optional error message, shown only when `invalid` is `true`. | no |
+| `id` | `string` | `undefined` | no | Input id for the label association. | no |
+| `invalid` | `boolean` | `false` | no | Error state: modifier class + `aria-invalid` on the input + error text swap. | no |
+| `density` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height. Writes `data-size`. | no |
+| `variant` | `'surface' \| 'classic' \| 'soft'` | `'surface'` | no | Shell treatment; classic is raised fill + elevation (family rule). | no |
+| `placeholder` | `string` | `undefined` | no | National-input placeholder. | no |
+| `disabled` | `boolean` | `false` | no | Disables select and input. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot`. | no |
+
+Rules:
+
+- The national display is owned by the engine (`react-phone-number-input/input` with `smartCaret`): parsing, as-you-type formatting, and caret behavior come from the lib, exactly the input-otp playbook. Our code owns the shell, the dropdown, validation display, and the E.164 contract.
+- Typing stores `parsed.number` (E.164) whenever the text parses; clearing the field stores `undefined`.
+- Country options render as SVG flag + text code (`US +1`) with full region names in the searchable list; flags come from the optional `@d4gger/design-system/flags.css` entrypoint (`country-flag-icons` sprite, no emoji, no external requests). Without that import the codes still read — flags are progressive enhancement.
+- The country-block divider bleeds into the shell padding per density (negative-margin contract in `phone-input.css`) so it runs edge to edge at every size.
+- The `countries` prop restricts the list; the select falls back to `defaultCountry` when the active country is not in the list.
+
+## CSS class contract
+
+**Root class:** `dsx-phone-input`
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `dsx-phone-input--sm/md/lg` (shell heights) | `phone-input.css` |
+| `data-variant` | `surface`, `classic`, `soft` | `dsx-phone-input--{variant}` | `phone-input.css` |
+
+**Slot classes:** `dsx-phone-input__label`, `dsx-phone-input__shell`, `dsx-phone-input__country`, `dsx-phone-input__input`, `dsx-phone-input__error`, `dsx-phone-input__helper`. Invalid root modifier: `dsx-phone-input--invalid`.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token. Shell, border, focus, disabled, and autofill contracts come from `_internal/baseInput.css`; classic/soft follow the input-family rule (raised fill + `var(--dsx-shadow-elevation-2)`).
+
+## Accessibility
+
+- The country `<select>` carries `aria-label="Country code"`; the national input is labelled by `label`/`id` like `TextField`.
+- `aria-invalid` is set on the national input when `invalid` is `true`.
+- The select is a native control: full keyboard and screen-reader support with no extra code.

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

@@ -3,13 +3,6 @@ title: Pills
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/pills/Pills.tsx
-css_path: packages/d4gger-design-system/src/styles/components/pills.css
-props_path: packages/d4gger-design-system/src/components/pills/pills.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Pills.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:
   - Badge
   - Button
@@ -18,7 +11,7 @@ depends_on:
 
 # Pills
 
-> 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
 
@@ -43,8 +36,8 @@ The compound is split across two prop-def bags: `pillsPropDefs` for the root and
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'solid' \| 'soft' \| 'outline'` | `'solid'` | no | Cluster variant. The root's `data-variant` is informational; the visible variant is set per `Pill` via its own `variant` prop. | no |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Cluster size. The root's `data-size` is informational; the visible size is set per `Pill` via its own `size` prop. | no |
+| `variant` | `'solid' \| 'soft' \| 'outline'` | `'solid'` | no | Cluster variant. Cascades to every `Pill` via context (`solid`→`default`, `soft`→`soft`, `outline`→`outline`); a per-pill `variant` overrides it. The root's own `data-variant` carries no CSS. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Cluster size. Cascades to every `Pill` via context; a per-pill `size` overrides it. | no |
 | `color` | `string` | `undefined` | no | Free-form accent override; writes `data-accent-color` when provided. | no |
 | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner radius token; writes `data-radius` when provided. The default is the CSS's `var(--dsx-rounded-full)`. | no |
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot`; consumer supplies the host element. | no |
@@ -54,9 +47,10 @@ The compound is split across two prop-def bags: `pillsPropDefs` for the root and
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'ghost' \| 'link'` | `'default'` | no | Per-pill variant. Emits one of the modifier classes `dsx-pill--default`, `dsx-pill--secondary`, `dsx-pill--destructive`, `dsx-pill--outline`, `dsx-pill--ghost`, `dsx-pill--link`. | no |
+| `variant` | `'default' \| 'secondary' \| 'soft' \| 'destructive' \| 'outline' \| 'ghost' \| 'link'` | `'default'` | no | Per-pill variant. Emits one of the modifier classes `dsx-pill--default`, `dsx-pill--secondary`, `dsx-pill--soft` (accent-3 tint + indicator text, the family soft recipe), `dsx-pill--destructive`, `dsx-pill--outline`, `dsx-pill--ghost`, `dsx-pill--link`. Inherits the root cluster variant when omitted. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Per-pill size. Emits one of the modifier classes `dsx-pill--sm`, `dsx-pill--md`, `dsx-pill--lg`. | no |
 | `removable` | `boolean` | `false` | no | When `true`, renders a trailing remove button with `aria-label="Remove"`. | no |
+| `tone` | `'success' \| 'warning' \| 'error' \| 'info'` | `undefined` | no | Status tone. Writes `data-tone`; paints the container tint + on-container ink (directions-panel language, shared with badge / callout / toast). Overrides the variant fill. | no |
 | `onRemove` | `() => void` | `undefined` | no | Click handler for the remove button. Only meaningful when `removable={true}`. | no |
 | `asChild` | `boolean` | `false` | no | Renders the pill through `Slot`; consumer supplies the host element. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-pill`. | no |
@@ -71,7 +65,7 @@ Each pill also accepts the standard HTML attributes for its host element. The `c
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-variant` | `solid`, `soft`, `outline` | (no rule in `pills.css`; attribute is informational) | n/a |
+| `data-variant` | `solid`, `soft`, `outline` | (no rule in `pills.css`; the value cascades to pills via context) | n/a |
 | `data-size` | `sm`, `md`, `lg` | (no rule in `pills.css`; attribute is informational) | n/a |
 | `data-accent-color` | any string | (no rule in `pills.css`; attribute is forwarded) | n/a |
 | `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (no rule in `pills.css`; attribute is forwarded) | n/a |

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

@@ -3,19 +3,12 @@ title: Popover
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/popover/Popover.tsx
-css_path: packages/d4gger-design-system/src/styles/components/popover.css
-props_path: packages/d4gger-design-system/src/components/popover/popover.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Popover.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: []
 ---
 
 # Popover
 
-> 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
 
@@ -142,7 +135,8 @@ Rules:
 | Title typography | `var(--dsx-typography-headline-medium-*)` | Title. |
 | Description typography | `var(--dsx-typography-body-medium-*)` | Description. |
 | Description color | `var(--dsx-color-on-surface-variant)` | Body copy. |
-| Positioner z-index | `var(--dsx-z-index-popover, 50)` | Stacking. |
+| Content z-index | `calc(var(--dsx-z-index-modal, 90) + 1)` | Keeps portaled content above both sticky chrome and a modal-tier surface that owns its trigger. |
+| Positioner z-index | `var(--dsx-z-index-popover, 60)` | Stacking for an explicitly composed positioner. |
 | Close button size | `var(--dsx-size-lg)` | Square tap target. |
 | Close button radius | `var(--dsx-rounded-full)` | Round close. |
 | Motion duration | `var(--dsx-motion-duration-*)` | Mount and exit. |
@@ -285,7 +279,7 @@ Rules:
 
 | Shape | Property | Token | Token type | Penpot property name |
 |---|---|---|---|---|
-| `<Content frame>` | fill | `var(--dsx-color-surface-overlay)` | Color | `fills` |
+| `<Content frame>` | fill | `var(--dsx-color-panel-translucent)` | Color | `fills` |
 | `<Content frame>` | radius | `var(--dsx-rounded-lg)` | Radius | `borderRadius` |
 | `<Content frame>` | spacing | `var(--dsx-space-md)` | Spacing | `padding` |
 | `<Title text>` | typography | `var(--dsx-typography-headline-medium-*)` | Typography | `typography` |
@@ -296,8 +290,8 @@ Rules:
 
 | State | Content fill | Content shadow |
 |---|---|---|
-| `default` | `var(--dsx-color-surface-overlay)` | `var(--dsx-shadow-elevation-2)` |
-| `open` | `var(--dsx-color-surface-overlay)` | `var(--dsx-shadow-elevation-3)` |
+| `default` | `var(--dsx-color-panel-translucent)` | `var(--dsx-shadow-elevation-2)` |
+| `open` | `var(--dsx-color-panel-translucent)` | `var(--dsx-shadow-elevation-3)` |
 
 ### Variant model
 

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

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

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