@d4gger/design-system 3.0.0 → 4.0.0

package/dist/docs/components/link.md

@@ -8,247 +8,69 @@ depends_on: []
 
 # Link
 
-> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+> Source of truth: the package source at `package_path`. The spec mirrors source in the same change.
 
 ## 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 (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.
+A native inline anchor with readable accent foreground, explicit underline policy and a single-value font-size scale. Apps own destination, routing, target and rel. `asChild` supplies a consumer host.
 
 ## Anatomy & slots
 
-**Parent:** `Link` (no compound; flat polymorphic export).
-
-**Slots:**
-
-No slots: flat export. The component renders a single `<a>` host element (or the consumer's host element when `as` or `asChild` is set) with the `dsx-link` root class, the `underline` modifier class, and any `tone` modifier class.
+Single `<a>` root with `dsx-link`; no compound slots. Native anchor attributes and refs are forwarded. `asChild` uses Radix Slot.
 
 ## Props contract
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `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` | `'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 |
-| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
-| `children` | `React.ReactNode` | `undefined` | no | Link body. | no |
-
-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 `['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`.
+| `underline` | `'auto' \| 'always' \| 'hover' \| 'none'` | `'auto'` | no | Writes `dsx-link--{underline}`; see affordance policy below. | no |
+| `tone` | `'default' \| 'muted' \| 'inverse'` | `'default'` | no | Non-default tones write `dsx-link--{tone}`. | no |
+| `color` | `'rift' \| 'warp' \| 'ray' \| string` | `undefined` | no | Writes `data-accent-color`; the global token layer resolves recognized accents, including astral and spark. Unknown strings retain the ambient tokens. | no |
+| `size` | `'1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'` | `undefined` | no | Writes `data-size` and applies the existing role-derived font-size mapping. | no |
+| `highContrast` | `boolean` | `false` | no | Writes `data-high-contrast="true"` and uses high-contrast foreground. | no |
+| `asChild` | `boolean` | `false` | no | Slot the consumer host. | no |
+| `className` | `string` | `undefined` | no | Additional classes. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Forwarded style. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Accessible link content. | no |
+
+`href`, `target`, `rel`, `download`, `id` and `aria-*` are native anchor props. There is no routing or external-link prop and no `as` prop.
 
 ## CSS class contract
 
-**Root class:** `dsx-link`
-
-**Modifier classes** (driven by the `underline` and `tone` prop defs and the `data-*` attributes):
-
-| Attribute | Allowed values | Class | CSS file |
-|---|---|---|---|
-| (class) | `auto`, `always`, `hover`, `none` | `dsx-link--{underline}` | `link.css` |
-| (class) | `muted`, `inverse` | `dsx-link--muted`, `dsx-link--inverse` | `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` |
+Root: `dsx-link`. Modifier classes: `dsx-link--auto`, `--always`, `--hover`, `--none`, `--muted`, `--inverse`. Attributes: `data-size`, `data-accent-color`, `data-high-contrast`.
 
-**Slot classes:** none.
+The root uses native inline flow; multiline links share line boxes with surrounding text. `overflow-wrap: anywhere` allows long identifiers to wrap. SVG children align vertically with a token gutter. Layout primitives can still position a Link as a flex/grid child.
 
-**Responsive behavior:**
+Underline policy:
 
-- `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.
+- `auto`: no underline at desktop rest; underline on hover, focus-visible or pressed. On devices without hover it is underlined at rest.
+- `always`: underline at rest and through interaction.
+- `hover`: no underline at rest; underline on hover, focus-visible or pressed.
+- `none`: no underline through interaction; focus ring remains visible.
 
-**Reduced motion:**
-
-- The component transitions `color` over `var(--dsx-motion-duration-fast, 150ms) var(--dsx-motion-easing-standard, ease)`. The transition is a color change only; it is not gated by `prefers-reduced-motion` in the source CSS. The default fast duration is short enough that the transition is acceptable for most reduced-motion users.
+Underlines use `currentColor`, including muted, inverse and high-contrast tones. High contrast preserves the inverse foreground on an inverse surface. Thickness and offset preserve the existing font-relative browser heuristics.
 
 ## Token mapping
 
-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 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. |
-| Text decoration color | `var(--dsx-color-primary)` (or `var(--dsx-color-accent-9)` on accent, or `var(--dsx-color-high-contrast)` on high-contrast) | Underline color. |
-| Gap | `var(--dsx-space-xs)` | Inner gap for icon-plus-label layouts. |
-| Border radius (focus) | `var(--dsx-rounded-sm)` | Focus ring roundness. |
-| Outline (focus) | `2px solid var(--dsx-effect-ring-focus)` | Focus ring width. |
-| Outline offset (focus) | `var(--dsx-focus-ring-offset, 2px)` | Focus ring offset. |
-| Motion duration | `var(--dsx-motion-duration-fast, 150ms)` | Color transition. |
-| Motion easing | `var(--dsx-motion-easing-standard, ease)` | Color transition. |
-
-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 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.
+| Default foreground | `--dsx-color-accent-indicator` | Readable text, independently scoped through all five accents. |
+| Muted / inverse / high contrast | `--dsx-color-on-surface-variant` / `--dsx-color-on-inverse-background` / `--dsx-color-high-contrast` | Existing tone and contrast roles. |
+| Icon gutter / focus radius | `--dsx-space-xs` / `--dsx-rounded-sm` | Inline icon and focus geometry. |
+| Focus outline / offset | `--dsx-border-width-lg` + `--dsx-effect-ring-focus` / `--dsx-space-0-5` | Visible 2px keyboard outline, 2px offset. |
+| Size 1–9 | label-small, label-medium, body-medium, body-large, label-large, headline-medium, headline-large, display-medium, display-large font-size tokens | Existing mapping preserved; omitted size inherits context. |
 
 ## Motion contract
 
-| Region | Token | Default | Reduced |
-|---|---|---|---|
-| Color transition | `var(--dsx-motion-duration-fast) var(--dsx-motion-easing-standard)` | `150ms ease` | (no explicit reduced override in the source CSS) |
-
-Rules:
-
-- The color transition is a token-driven property. A future `prefers-reduced-motion` override would either zero the duration or remove the transition entirely; the spec leaves that decision to a future spec change.
+Color transitions use `--dsx-motion-duration-fast` and `--dsx-motion-easing-standard`. `prefers-reduced-motion: reduce` removes the transition. Modality queries are not viewport breakpoints; no responsive prop or width query is added.
 
 ## Accessibility
 
-**Roles:**
-
-- The component renders an `<a>` by default (or the consumer's host element when `as` / `asChild` is set). The semantic role of a link is preserved.
-
-**Keyboard:**
-
-- Links are focusable. `Tab` moves focus to and from the link. `Enter` activates the link. The browser's focus ring renders through `dsx-link:focus-visible`.
-
-**Focus:**
-
-- Visible focus ring via `2px solid var(--dsx-effect-ring-focus)` with `outline-offset: var(--dsx-focus-ring-offset, 2px)`. The ring is rendered only on `:focus-visible` so mouse-driven focus does not show it.
-
-**Reduced motion:**
-
-- The color transition is short (150ms). Apps that need a strict reduced-motion fallback should layer a global rule that disables the transition inside `@media (prefers-reduced-motion: reduce)`.
-
-**Color and meaning:**
-
-- The `color`, `tone`, and `underline` props are visual modifiers. The link's href and label carry the meaning.
-
-**Naming:**
-
-- Every link needs an accessible name. The default render uses the body text as the accessible content. Consumers should supply `aria-label` when the body is an icon or another non-text node.
+Body prose should use `underline="always"` where link color does not have a 3:1 luminance distinction from surrounding text; the live paragraph demonstrates that policy. A named anchor with href receives native Tab/Enter behavior. Focus-visible always paints the outline. Touch and keyboard affordances do not depend on hover. Inline prose links use the WCAG 2.5.8 inline exception. When a link is blockified by flex/grid layout, its minimum inline/block size is a physical 24px (`size-md / density-scale`); density must not shrink the floor. Standalone icon actions should use the appropriate control component. Inverse tone requires an inverse surface. Apps supply accessible labels for icon-only content and their router host through `asChild`.
 
 ## Playground demo spec
 
-`Link` is registered in `apps/playground/lib/registry/typography.tsx` under the `link` key. The registry entry imports `linkPropDefs` and renders the component with a sample href. Per-component route: `/docs/link`.
-
-**Default story:**
-
-- Renders `Link` with a default href and body. Asserts the root class is `dsx-link` and the `underline` modifier is `dsx-link--auto`. Host element is `A` and the `href` attribute is forwarded.
-
-**Underline story:**
-
-- Renders Link with each `underline` value. Asserts the matching `dsx-link--{underline}` class.
-
-**Color story:**
-
-- 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`):
-
-- Renders Link with `asChild` wrapping a Next.js-style `<a>` element. Asserts the host element is `A` and the `dsx-link` class is preserved.
-
-**State story:**
-
-- Renders Link in muted, inverse, and high-contrast states. Asserts the matching modifier class or `data-high-contrast` attribute.
-
-**Token story:**
-
-- Renders inside a `Theme` wrapper with `accentColor="rift"` and `accentColor="warp"`. Asserts the `data-accent-color` attribute tracks the active accent.
-
-**A11y story:**
-
-- The default render passes the `vitest-axe` no-violations check. The focus-visible ring test is covered by the `:focus-visible` selector in the CSS.
-
-**Props exposed in the playground controls:**
-
-| Prop | Control | Default |
-|---|---|---|
-| `underline` | select | `auto` |
-| `tone` | select | `default` |
-| `color` | select | (none) |
-| `size` | select | (none) |
-| `highContrast` | boolean | `false` |
-| `asChild` | boolean | `false` |
+`/docs/link`, typography registry. Matrix render forwards all props; controls expose underline, tone, color, size and highContrast. The live example has real local hash navigation, all four underline policies, muted/inverse/high-contrast references, all five accent strings and a slotted native anchor. Tab/Enter navigates to the labelled destination. The nine size values remain available in the matrix.
 
 ## Wiring notes
 
-**Composes from:**
-
-- `@radix-ui/react-slot` for `asChild`.
-- `_internal/helpers/extractProps` for the prop def bag.
-- `_internal/props/{asChild,highContrast}.prop` for the shared prop defs.
-- `_internal/cn` (via `classNames`) for class merging.
-- No DS component composition. Link is a leaf primitive.
-
-**Used by:**
-
-- The Playground typography registry, in-product navigation, in-line references, footer links, and any app surface that needs a styled anchor.
-
-**State boundaries:**
-
-- Owned by Link: the root class, the `underline` and `tone` modifier classes, the `data-accent-color`, `data-size`, and `data-high-contrast` attributes, the focus-visible ring, and the prop def bag.
-- Owned by the consumer: the href, target, rel, the body content, the host element when `as` / `asChild` is set, the click navigation behavior, and any extra `className` / `style` applied through prop forwarding.
-
-**Boundary rules:**
-
-- App-owned data: the destination, the link copy, the open-in-new-tab and rel behavior (`target="_blank"` requires `rel="noopener noreferrer"` for security), and the routing strategy.
-- DS-owned visuals: the `dsx-link` root class, the `underline` and `tone` modifier classes, the accent color, the focus ring, and the prop def bag.
-
-## Penpot build recipe
-
-> Optional. Penpot is a visual reference, not a code authority. The Link recipe tracks the `underline`, `tone`, `color`, `size`, and `highContrast` contract.
-
-The package does not yet publish a Penpot asset for Link. The recipe is visual reference only and tracks the CSS contract.
-
-### Root board
-
-- **Name**: `Primitives / Link`.
-- **Dimensions**: `auto × auto` (inline).
-- **Layout**: `Flex` (inline).
-- **Sizing**: `horizontalSizing = 'auto'`, `verticalSizing = 'auto'`.
-
-### Layer tree
-
-```
-<Root Board: Link>
-  └── <Text: link body (anchor)>
-```
-
-### Token bindings (Penpot properties)
-
-| Shape | Property | Token | Token type | Penpot property name |
-|---|---|---|---|---|
-| Root | text fill | `--dsx-color-primary` (default) | Color | `fills` |
-| Root (accent) | text fill | `--dsx-color-accent-9` | Color | `fills` (state) |
-| Root (muted) | text fill | `--dsx-color-on-surface-variant` | Color | `fills` (state) |
-| Root (inverse) | text fill | `--dsx-color-on-inverse-background` | Color | `fills` (state) |
-| Root (always) | text decoration | `--dsx-color-primary` | Color | `textDecoration` |
-| Root (focus-visible) | outline | `--dsx-effect-ring-focus` | Color | `outline` |
-
-### State transformations
-
-| State | Root text fill | Text decoration |
-|---|---|---|
-| `default` | `--dsx-color-primary` | (none on `auto`) |
-| `muted` | `--dsx-color-on-surface-variant` | (none) |
-| `inverse` | `--dsx-color-on-inverse-background` | (none) |
-| `highContrast` | `--dsx-color-high-contrast` | (none) |
-| `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` |
-
-### Variant model
-
-- `underline`: `auto`, `always`, `hover`, `none`. Default `auto`.
-- `tone`: `default`, `muted`, `inverse`. Default `default`.
-- `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.
-
-### Validation checklist
-
-- [ ] 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 rift, warp, and ray.
+Radix Slot implements `asChild`; `extractProps` consumes `linkPropDefs`; classnames merges the root and modifiers. No DS component composition inside Link. The token layer owns accent rescoping; Link consumes semantic roles. Apps own link content, destination and navigation.

package/dist/docs/components/marquee.md

@@ -24,7 +24,7 @@ A horizontally scrolling content strip that animates a duplicated child track ac
 |---|---|---|---|
 | `Marquee` (root) | `<div>` | DS primitive + class | Wrapper that owns the `--dsx-marquee-duration`, `--dsx-marquee-direction`, and `--dsx-marquee-edge-fade-width` CSS variables plus the `data-pause-on-hover` and optional `data-edge-fade` attributes. |
 | internal track | `<div class="dsx-marquee__track">` | internal layout | Flex row that runs the `dsx-marquee-scroll` keyframe. |
-| internal content (x2) | `<div class="dsx-marquee__content">` | internal layout | The original `children` and an `aria-hidden="true"` clone. The duplication is what makes the loop seamless. |
+| internal content (x2) | `<div class="dsx-marquee__content">` | internal layout | The original `children` and an `aria-hidden="true"`, inert clone. The duplication is what makes the loop seamless. |
 
 The track and content nodes are internal layout, not public slots. The two `dsx-marquee__content` rows are siblings inside the track.
 
@@ -130,7 +130,7 @@ Rules:
 
 **Focus:**
 
-- Focusable children inside the strip remain focusable. The scroll animation does not move focus. The edge mask clears on `:focus-within` so focus indicators are not clipped. Consumers that include interactive children should ensure those children are not announced twice; the `aria-hidden="true"` clone handles the announcement side.
+- Focusable children inside the strip remain focusable. The scroll animation does not move focus. The edge mask clears on `:focus-within` so focus indicators are not clipped. Consumers that include interactive children should ensure those children are not announced twice; the duplicate is both `aria-hidden` and inert, so it cannot add duplicate keyboard stops. Focus within the original pauses animation regardless of `pauseOnHover`.
 
 **Reduced motion:**
 

package/dist/docs/components/menu.md

@@ -166,7 +166,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with three docum
 | Content transform origin | `var(--radix-dropdown-menu-content-transform-origin)` | Radix-provided anchor (not a token). |
 | Item gap | `var(--dsx-space-sm)` | Gap between item content. |
 | Item padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Inner gutter. |
-| Item radius | `var(--dsx-rounded-sm)` | Rounded highlight surface. |
+| Item radius | `0` (square); menu first/last/only-child edge rules restore frame-concentric corners | Stacked items read as one joined block instead of floating pills — checked washes, hover washes, and focus rings share one flush geometry. |
 | Item typography | `var(--dsx-typography-body-medium-*` | Body ramp. |
 | Item color | `var(--dsx-color-on-surface)` | Resting text. |
 | Item highlight background | `var(--dsx-effect-hover-ghost)` | Hover / keyboard-focus highlight. |
@@ -175,6 +175,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with three docum
 | Separator margin | `var(--dsx-space-xs)` calc(-1) | Inset margin. |
 | Separator background | `var(--dsx-color-outline-variant)` | Divider color. |
 | Overlay z-index | `calc(var(--dsx-z-index-dropdown) - 1)` | Just under the content. |
+| Nested content z-index | `calc(var(--dsx-z-index-modal, 90) + 2)` | Menu-tier content nested inside a modal-tier host (carries `dsx-menu__nested`). |
 | Animation duration | `var(--dsx-motion-duration-fast)` | Open / close keyframes. |
 | Animation easing (in) | `var(--dsx-motion-easing-emphasized)` | Open easing. |
 | Animation easing (out) | `var(--dsx-motion-easing-in)` | Close easing. |
@@ -187,6 +188,7 @@ Rules:
 - `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, NavigationMenu trigger/link/viewport) live in `_internal/baseMenu.css` rather than `menu.css`. The public menu surfaces import `baseMenu.css` to inherit those rules.
+- **Nested floating tier (shared layering contract).** Menu-tier content (`Select`, `Combobox`, `DropdownMenu`/`ContextMenu`/`Menubar` via `MenuContent`) paints at the dropdown tier (50); modal-tier hosts (`Popover.Content` at `modal + 1`, `Dialog.Content` at `modal` — both body-portaled, with Radix copying the content `z-index` onto its wrapper) sit above it, so a menu opened inside one of those hosts paints behind its own host. Hosts provide `_internal/floatingLayer` `FloatingLayerHostContext` from their content; menu contents consume it and add `dsx-menu__nested`, resolved to `modal + 2` by `_internal/baseMenu.css`. A flat bump of `--dsx-z-index-dropdown` is rejected: a nested menu must clear 91 while a standalone page menu must stay below the modal overlay (80) so an open Dialog still masks page content — one static value cannot do both. Standalone menus never carry the class. The signal is provided at content level (not root) so `Combobox` — itself a `Popover` — never self-escalates. `AlertDialog.Content` inherits the host behavior through `Dialog.Content`. `Drawer` (vaul, own overlay tier) is out of scope.
 
 ## Motion contract
 
@@ -272,6 +274,7 @@ The `test_path` is `packages/d4gger-design-system/src/test/components/menu-migra
 - `_internal/usePrefersReducedMotion`: gates the framer-motion preset.
 - `framer-motion` (re-exported from `@d4gger/design-system/motion`): `motion` and `AnimatePresence` for the content animation.
 - `_internal/baseMenu.css`: shared item hover, focus, selected, and disabled rules. The public menu surfaces import `baseMenu.css` to inherit those rules; the `Menu` CSS file does not import it directly.
+- `_internal/floatingLayer`: `FloatingLayerHostContext` / `useFloatingLayerHost` for the nested floating tier. `MenuContent` consumes it and adds `dsx-menu__nested` when rendered inside a modal-tier host (see the Token mapping contract above).
 
 **Used by:**
 

package/dist/docs/components/metric.md

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

package/dist/docs/components/notification-center.md

@@ -29,15 +29,15 @@ An inbox-style notification surface that groups header, list, and footer regions
 | `NotificationCenter.List` | `<div>` (or `Slot` host) | `dsx-notification-center__list` | Vertical list of items. Capped at `max-height: 400px` with `overflow-y: auto`. |
 | `NotificationCenter.Footer` | `<div>` (or `Slot` host) | `dsx-notification-center__footer` | Footer row (typically a "View all" link or button). |
 | `NotificationCenter.Item` | `<div>` (or `Slot` host) | `dsx-notification-center__item` (with `--unread` modifier when `unread` is true) | A single notification row. The CSS file ships helper classes `dsx-notification-center__item-title`, `dsx-notification-center__item-description`, and `dsx-notification-center__item-time` for the typical layout. |
-| `NotificationCenter.Trigger` | `IconButton` + `Badge` fragment | `dsx-notification-center__trigger` and `dsx-notification-center__badge` | Bell-style trigger. Wraps an `IconButton` (size `sm`, variant `ghost`, default `aria-label="Notifications"`) and conditionally renders a `Badge` with the unread count (capped at `'99+'`). The trigger is rendered as a React fragment so it can be placed anywhere. |
+| `NotificationCenter.Trigger` | `IconButton` containing Icon + Badge | `dsx-notification-center__trigger` and `dsx-notification-center__badge` | Bell-style trigger (size `sm`, variant `ghost`) with an accessible unread-count name. The badge sits at the bell's upper trailing corner (capped at `'99+'`); the host reserves the count's width and asChild preserves child/ref composition. |
 
 **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-panel-translucent)` background, and a `var(--dsx-shadow-card-md)` shadow.
+- In the `popover` variant (the default), the root is sized `width: var(--dsx-sheet-width-sm), max-width: 100%`, 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.
+- `NotificationCenter.Trigger` is an `inline-flex` button with intrinsic width and a 44px minimum width/height (`size-xl + space-xs`). The 16px badge is raised by 8px at the bell's trailing corner, with a 4px horizontal overlap and 8px host padding. Normal flow reserves the badge width; increasing counts grow toward the trailing edge rather than covering the bell. The badge uses rounded-full and label-small typography.
 
 ## Props contract
 
@@ -101,7 +101,7 @@ The trigger is a thin wrapper around `IconButton`; it forwards all of `IconButto
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. The `popover` variant uses a fixed 320px width; on small screens the consumer is expected to swap in a different layout (e.g. a full-screen Sheet) and render the same items in `NotificationCenter` with the `sidebar` variant.
+- The component does not write width media queries. The popover variant prefers `--dsx-sheet-width-sm` (320px) and caps to its parent width. Header actions wrap intrinsically; the list shrinks and scrolls. Use sidebar to fill a containing panel.
 
 **Reduced motion:**
 
@@ -113,7 +113,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Property | Token | Role |
 |---|---|---|
-| Popover width | `320px` | Popover variant width |
+| Popover width | `var(--dsx-sheet-width-sm)` with max-width=100% | Preferred width, parent-contained |
 | 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-panel-translucent)` | Popover surface |
@@ -138,10 +138,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Item time type ramp | `var(--dsx-typography-label-small-*)` | Item time text |
 | Footer padding | `var(--dsx-space-sm)` | Footer gutter |
 | Footer border-top | `var(--dsx-border-width-sm) solid var(--dsx-color-outline-variant)` | Footer separator |
-| Trigger position | `relative` | Anchors the badge |
-| Badge position | `absolute` with `-var(--dsx-space-xs)` offsets | Badge placement |
-| Badge min-width | `var(--dsx-size-xs)` | Badge min width |
-| Badge height | `var(--dsx-size-xs)` | Badge height |
+| Trigger width / minimum dimensions | `auto` / `calc(var(--dsx-size-xl) + var(--dsx-space-xs))` | Count expands the 44px button |
+| Trigger gap / inline padding | `0` / `var(--dsx-space-sm)` | Count corner containment |
+| Badge placement | relative, raised by space-sm, negative space-xs inline margin | Upper trailing corner; reserves count width |
+| Badge min-width | `var(--dsx-size-sm)` | Badge min width |
+| Badge height | `var(--dsx-size-sm)` | Badge height |
 | Badge radius | `var(--dsx-rounded-full)` | Badge roundness |
 | Badge type ramp | `var(--dsx-typography-label-small-*)` | Badge text |
 
@@ -159,7 +160,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 
 - The root renders as a `<div>` without an explicit `role`. The canonical pattern is to wrap the panel in a `Popover` or `Sheet`; the wrapping surface is responsible for the modal / non-modal role and focus management.
 - `NotificationCenter.List` is a plain `<div>`. If the consumer wants to expose the list as an `aria-live` region (e.g. for incoming notifications), they can add the `aria-live` and `aria-relevant` attributes manually.
-- `NotificationCenter.Trigger` renders an `IconButton` with `role="button"` and a default `aria-label` of `'Notifications'`. The accompanying badge is announced through the `aria-label` (`Notifications: 5 unread`, or similar — the consumer is responsible for composing the full accessible name when the count is non-zero).
+- `NotificationCenter.Trigger` renders an IconButton named “Notifications” at zero, or “Notifications, N unread” when positive. An explicit aria-label overrides this fallback. The visual badge is aria-hidden; it stays at the bell's upper trailing corner inside the trigger host.
 
 **Keyboard:**
 
@@ -171,7 +172,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 **Focus:**
 
 - The component does not render a focus ring on items or panels. Interactive content provides its own ring.
-- The trigger button gets the standard `IconButton` focus ring.
+- The trigger button gets the standard `IconButton` focus ring and a minimum 44px target containing both the bell and count.
 
 **Reduced motion:**
 
@@ -180,7 +181,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 **Color and meaning:**
 
 - Unread state is communicated by both the left border accent and the background lift. The text is unchanged; consumers can add an `aria-label="Unread"` to make the state screen-reader-accessible.
-- The trigger badge is a red `Badge` (`variant="error"`). The label is the numeric count.
+- The trigger badge is an accent `Badge` (`variant="primary"`), using accent-track and accent-contrast from the inherited Theme. The label is the numeric count.
 
 **Naming:**
 
@@ -210,7 +211,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 
 **Token story:**
 
-- Renders the default panel inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the unread item border tracks `--dsx-color-primary` and is not affected by the accent token.
+- Renders the default panel inside a `Theme` wrapper with `accentColor="astral"` and `accentColor="spark"`. Asserts the unread item border tracks `--dsx-color-primary` and is not affected by the accent token.
 
 **A11y story:**
 
@@ -228,7 +229,7 @@ The component has no motion. The panel itself is static; transitions on open / c
 **Composes from:**
 
 - `IconButton` (`src/components/iconButton`): the trigger renders a small ghost `IconButton`. The trigger forwards all `IconButton` props and defaults `aria-label="Notifications"`.
-- `Badge` (`src/components/badge`): the trigger badge is a `Badge` with `variant="error"`, `size="sm"`. The count is rendered as plain text and is capped at `'99+'` for counts greater than 99.
+- `Badge` (`src/components/badge`): the trigger badge is a `Badge` with `variant="primary"`, `size="sm"`. The count is rendered as plain text and is capped at `'99+'` for counts greater than 99.
 - `@radix-ui/react-slot`: enables `asChild` on the root and on the named slots.
 
 **Used by:**
@@ -244,3 +245,12 @@ The component has no motion. The panel itself is static; transitions on open / c
 
 - App-owned data: notification text, timestamps, action handlers, and the unread count source.
 - DS-owned visuals: token bindings, slot classes, unread state styling, and the trigger badge geometry.
+
+## Overlay review fixture
+
+`/docs/notification-center` shows native button rows that mark themselves read,
+Mark all read, Reset inbox, a real Popover and trigger counts 0/1/5/150. Item
+button hosts have width=100%, inherited typography, start-aligned wrapping text,
+and hover/focus/pressed feedback. The list is min-height=0 and flexes; header
+and footer remain nonshrinking. Payload, routing and read persistence are
+consumer-owned. Trigger asChild preserves host/ref/click composition.

package/dist/docs/components/page-header.md

@@ -119,6 +119,8 @@ Rules:
 
 ## Playground demo spec
 
+The live example uses a compact named icon action so the title remains readable in a 320px review frame, plus a title-only header. Header height and title ellipsis behavior remain canonical.
+
 `PageHeader` is registered in `apps/playground/lib/registry/display.tsx` under the `page-header` key.
 
 **Default story:**