@d4gger/design-system 3.0.1 → 4.0.0

package/dist/docs/components/sonner.md

@@ -65,7 +65,7 @@ The CSS file also targets `[data-sonner-toaster]` and `[data-sonner-toast]` dire
 **Responsive behavior:**
 
 - The component does not write `@media` rules. None of its prop defs are `responsive: true`.
-- The component's CSS file is breakpoint-agnostic, but the toaster layout shifts to a full-width style under `max-width: 640px` so mobile viewports receive a sensible default.
+- The package stylesheet uses an intrinsic viewport width cap at every width; it has no width media queries. The adapter retains its own positioning rules and mobileOffset API.
 
 **Reduced motion:**
 
@@ -81,32 +81,33 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Toaster z-index | `var(--dsx-z-index-toast)` | Toast stack. |
 | Toaster gap | `var(--dsx-space-md)` | Space between toasts. |
 | Toaster padding | `var(--dsx-space-md)` | Inner gutter. |
-| Toast padding block | `var(--dsx-space-sm)` | Toast vertical padding. |
+| Toast padding block | `var(--dsx-space-md)` | Toast vertical padding. |
 | Toast padding inline | `var(--dsx-space-md)` | Toast horizontal padding. |
 | Toast background | `var(--dsx-color-surface)` | Resting toast surface. |
 | Toast radius | `var(--dsx-rounded-md)` | Toast corner roundness. |
 | Toast border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Toast edge. |
 | Toast shadow | `var(--dsx-shadow-elevation-5)` | Spotlight: below dialogs, above all menus (B4 Q3). |
-| Toast gap | `var(--dsx-space-md)` | Gap between icon, title, description, and buttons. |
+| Toast gap | `var(--dsx-space-sm)` | Gap between icon, body and close; action row below. |
 | Success border | `var(--dsx-color-success)` | Success variant edge. |
 | Error background | `var(--dsx-color-error-container)` | Error variant surface. |
 | Error border | `var(--dsx-color-error)` | Error variant edge. |
 | Error text | `var(--dsx-color-on-error-container)` | Error variant text. |
-| Warning border | `var(--dsx-color-tertiary)` | Warning variant edge. |
-| Info border | `var(--dsx-color-secondary)` | Info variant edge. |
+| Warning border | `var(--dsx-color-warning)` | Warning variant edge. |
+| Info border | `var(--dsx-color-info)` | Info variant edge. |
 | Title typography | `var(--dsx-typography-label-large-*)` | Toast title. |
+| Title line-height | `var(--dsx-size-md)` | First line centred with the 24px icon/Close boxes. |
 | Title text | `var(--dsx-color-on-surface)` | Default title color. |
 | Description typography | `var(--dsx-typography-body-medium-*)` | Toast description. |
 | Description text | `var(--dsx-color-on-surface-variant)` | Default description color. |
 | Action, cancel, close | `var(--dsx-color-on-surface-variant)` | Default button text. |
-| Action, cancel, close padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Button padding. |
+| Action / cancel padding and height | `var(--dsx-space-xs) var(--dsx-space-sm)`, minimum `--dsx-size-lg` | Labelled controls below the message. |
+| Close dimensions / padding | `--dsx-size-md`, `0` | 24px box at the trailing top edge. |
 | Action, cancel, close radius | `var(--dsx-rounded-sm)` | Button corner roundness. |
 | Action, cancel, close hover background | `var(--dsx-color-high-contrast-container)` | Hover affordance. |
 | Action, cancel, close hover text | `var(--dsx-color-high-contrast)` | Hover affordance. |
 | Error title, description, close text | `var(--dsx-color-on-error-container)` | Error variant text. |
-| Mobile width | `calc(100vw - var(--dsx-size-md))` | Mobile max width. |
-| Mobile padding | `var(--dsx-space-sm)` | Mobile padding. |
-| Mobile inset | `var(--dsx-space-3)` | Mobile offset. |
+
+The first row places an optional icon, a shrinkable message body and a trailing Close in separate columns. The title line-height uses size-md (24px), aligning its first line with the centres of the 24px icon and Close boxes, including wrapped titles. Action and cancel controls occupy a second row below the message, preserving readable label widths. Without an icon, the message starts in the first column.
 
 ## Motion contract
 
@@ -131,7 +132,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Focus:**
 
-- Visible focus ring via the host application's focus styles. The DS does not add a custom focus ring; apps that need a custom ring can target the action, cancel, and close buttons from the host.
+- Action, cancel and close controls have the package focus ring and a minimum 24px control box. Actions retain their intrinsic label width; the text column shrinks and wraps within the available toast width.
 
 **Reduced motion:**
 
@@ -165,7 +166,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the toaster host renders inside the wrapper and the variant borders continue to render with the package tokens.
+- Renders inside a `Theme` wrapper with `accentColor="rift"`, `accentColor="astral"`, and `accentColor="spark"`. Asserts the toaster host renders inside the wrapper and the variant borders continue to render with the package tokens.
 
 **Props exposed in the playground controls:**
 
@@ -186,7 +187,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Used by:**
 
-- `NotificationCenter`: composes `Sonner` plus `Toast`, `Card`, and `DataList` for the inbox-style notification surface. The pattern-level `NotificationCenter` is the intended product composition; `Sonner` itself is a leaf surface.
+- Consumers compose transient notifications with `Sonner`; `NotificationCenter` is a separate inbox surface and does not render this adapter internally.
 
 **State boundaries:**
 
@@ -228,8 +229,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Success toast | stroke | `var(--dsx-color-success)` | Color | `strokes` |
 | Error toast | fill | `var(--dsx-color-error-container)` | Color | `fills` |
 | Error toast | stroke | `var(--dsx-color-error)` | Color | `strokes` |
-| Warning toast | stroke | `var(--dsx-color-tertiary)` | Color | `strokes` |
-| Info toast | stroke | `var(--dsx-color-secondary)` | Color | `strokes` |
+| Warning toast | stroke | `var(--dsx-color-warning)` | Color | `strokes` |
+| Info toast | stroke | `var(--dsx-color-info)` | Color | `strokes` |
 | Title | text fill | `var(--dsx-color-on-surface)` | Color | `fills` |
 | Description | text fill | `var(--dsx-color-on-surface-variant)` | Color | `fills` |
 | Error title, description | text fill | `var(--dsx-color-on-error-container)` | Color | `fills` |
@@ -241,8 +242,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | `default` | `var(--dsx-color-surface)` | `var(--dsx-color-outline)` | `var(--dsx-color-on-surface)` |
 | `success` | `var(--dsx-color-surface)` | `var(--dsx-color-success)` | `var(--dsx-color-on-surface)` |
 | `error` | `var(--dsx-color-error-container)` | `var(--dsx-color-error)` | `var(--dsx-color-on-error-container)` |
-| `warning` | `var(--dsx-color-surface)` | `var(--dsx-color-tertiary)` | `var(--dsx-color-on-surface)` |
-| `info` | `var(--dsx-color-surface)` | `var(--dsx-color-secondary)` | `var(--dsx-color-on-surface)` |
+| `warning` | `var(--dsx-color-surface)` | `var(--dsx-color-warning)` | `var(--dsx-color-on-surface)` |
+| `info` | `var(--dsx-color-surface)` | `var(--dsx-color-info)` | `var(--dsx-color-on-surface)` |
 
 ### Variant model
 
@@ -257,3 +258,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 - [ ] 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.
+
+## Overlay review fixture
+
+`/docs/sonner` owns one Toaster in its live example; matrix buttons use that
+host rather than mounting duplicates. One action emits one notification.
+Save draft with undo updates visible feedback through its action callback.
+The adapter retains its preferred width, capped by viewport minus
+dialog-viewport-gap. Package padding remains space-md at every width.

package/dist/docs/components/stepper.md

@@ -38,7 +38,7 @@ A multi-step wizard or progress indicator that pairs a numbered indicator with a
 
 - The root is a flex container. In `orientation="horizontal"` (the default) it is a `flex-direction: row` with `align-items: center`. In `orientation="vertical"` it is a `flex-direction: column` with `align-items: flex-start`.
 - `Stepper.Item` is a flex container. In horizontal orientation the item itself flips to `flex-direction: column` so the indicator sits above the label / description. In vertical orientation the item stays in a `flex-direction: row` and is `width: 100%` so the indicator, label, description, and content lay out side by side.
-- `Stepper.Indicator` is a circular `var(--dsx-size-md)` badge with a 1px outline. It uses the `label-medium` type ramp. State colors (complete, current, error, disabled) are applied via the parent `Item`'s modifier class.
+- `Stepper.Indicator` is a circular `var(--dsx-stepper-indicator-size)` badge with a 1px outline. It uses the `label-medium` type ramp. State colors (complete, current, error, disabled) are applied via the parent `Item`'s modifier class.
 - `Stepper.Separator` is the connector. In horizontal orientation it is a `flex: 1` bar that fills the available space; in vertical orientation it is a `var(--dsx-border-width-lg)` wide, `var(--dsx-space-lg)` tall bar offset to the right of the indicator.
 
 ## Props contract
@@ -107,36 +107,11 @@ These slots accept only `asChild` plus the standard HTML attribute surface for t
 
 ## Token mapping
 
-Every CSS value the component paints is a `var(--dsx-*)` token.
+Indicator diameter is a component-local size variable: sm → `var(--dsx-size-md)` (24px), md → `var(--dsx-size-lg)` (32px), lg → `var(--dsx-size-xl)` (40px). The same variable anchors both orientations’ connectors. Labels/descriptions wrap within their column.
 
-| Property | Token | Role |
-|---|---|---|
-| Item gap | `var(--dsx-space-sm)` | Gap between indicator and label / description |
-| Indicator size | `var(--dsx-size-md)` | Indicator width and height |
-| Indicator border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Indicator edge |
-| Indicator background | `var(--dsx-color-surface)` | Indicator surface |
-| Indicator radius | `var(--dsx-rounded-full)` | Circular indicator |
-| Indicator type ramp | `var(--dsx-typography-label-medium-*)` | Indicator number |
-| Indicator text color | `var(--dsx-color-on-surface-variant)` | Indicator text |
-| Complete indicator | `var(--dsx-color-success)` (border + background), `var(--dsx-color-on-success)` (text) | Success palette |
-| Current indicator | `var(--dsx-color-primary)` (border + background), `var(--dsx-color-on-primary)` (text) | Primary palette |
-| Error indicator | `var(--dsx-color-error)` (border + background), `var(--dsx-color-on-error)` (text) | Error palette |
-| Disabled item | `var(--dsx-opacity-disabled)` | Disabled opacity |
-| Label type ramp | `var(--dsx-typography-label-large-*)` | Label text |
-| Label color | `var(--dsx-color-on-surface)` | Default label color |
-| Pending / disabled label | `var(--dsx-color-on-surface-variant)` | Pending / disabled label color |
-| Description color | `var(--dsx-color-on-surface-variant)` | Description text |
-| Description type ramp | `var(--dsx-typography-body-medium-*)` | Description text |
-| Separator height | `var(--dsx-border-width-lg)` | Default connector thickness |
-| Separator background | `var(--dsx-color-outline-variant)` | Default connector color |
-| Separator radius | `var(--dsx-rounded-full)` | Connector roundness |
-| Separator min-width | `var(--dsx-space-md)` | Min horizontal connector length |
-| Horizontal separator offset | `margin-top: calc(var(--dsx-size-md) / 2 - var(--dsx-border-width-lg) / 2)`, `margin-left: var(--dsx-space-sm)`, `margin-right: var(--dsx-space-sm)` | Alignment with the indicator centerline |
-| Vertical separator width | `var(--dsx-border-width-lg)` | Vertical connector thickness |
-| Vertical separator height | `var(--dsx-space-lg)` | Vertical connector length |
-| Vertical separator offset | `flex: 0`, `margin-left: calc(var(--dsx-size-md) / 2 - var(--dsx-border-width-lg) / 2)`, `min-height: var(--dsx-space-lg)` | Centered alignment with the indicator centerline |
-| Complete-separator color | `var(--dsx-color-primary)` | Connector after a complete step |
-| Content margin-top | `var(--dsx-space-lg)` | Panel offset |
+Horizontal items share equal widths; each non-final item draws a connector from the indicator edge to the next item. Vertical items draw a connector from the indicator bottom through the item padding. `Stepper.Separator` remains a supported DOM slot and is visually hidden in both shipped orientations.
+
+Indicators retain state tokens: complete uses success/on-success; current uses primary/on-primary; error uses error/on-error; pending uses surface/outline/on-surface-variant. Disabled opacity uses opacity-disabled. Connector thickness uses border-width-lg, resting color outline-variant, completed color primary. Labels and descriptions use label-large/body-medium typography. Item gap uses space-sm; horizontal column gap uses space-lg.
 
 ## Motion contract
 
@@ -183,9 +158,9 @@ The component has no motion. State transitions (complete / current / pending / e
 The vertical `Stepper` layout previously had two visual defects:
 
 1. The `.dsx-stepper--vertical .dsx-stepper__separator` override did not reset the base `flex: 1`, causing the separator to grow along the main axis in vertical orientation.
-2. The `margin-left` was `calc(var(--dsx-size-md) / 2)` without subtracting half the separator width, offsetting the connector from the indicator centerline.
+2. The `margin-left` was `calc(var(--dsx-stepper-indicator-size) / 2)` without subtracting half the separator width, offsetting the connector from the indicator centerline.
 
-Both issues are now fixed: the vertical override sets `flex: 0` and uses `margin-left: calc(var(--dsx-size-md) / 2 - var(--dsx-border-width-lg) / 2)` to center the connector under the indicator.
+Both issues are now fixed: the vertical override sets `flex: 0` and uses `margin-left: calc(var(--dsx-stepper-indicator-size) / 2 - var(--dsx-border-width-lg) / 2)` to center the connector under the indicator.
 
 ## Playground demo spec
 
@@ -229,7 +204,7 @@ Both issues are now fixed: the vertical override sets `flex: 0` and uses `margin
 **Used by:**
 
 - App-level onboarding flows, multi-step forms, and wizard navigation. The roster explicitly calls out that `Stepper` is a composite, not a pattern, and that it must compose primitive `Indicator + Separator + Label` parts rather than a parallel visual shell.
-- Timeline (rail recipe consumer, CSS contract only — no component dependency): Timeline reuses the vertical rail geometry (dot-column centering calc, marker-bottom anchor, size-aware offsets, active-state recolor) for its left rail and centered alternate spine, while keeping its own Item/Marker/Content/Connector API, its own event states, and its own (non-progressbar) semantics. The vertical rail rules in `stepper.css` are the layout engine of record; keep them in sync with `timeline.css`.
+- Timeline (rail recipe consumer, CSS contract only — no component dependency): Timeline reuses the vertical rail geometry (dot-column centering calc, marker-bottom anchor, size-aware offsets, active-state recolor) for its left rail and centered alternate spine, while keeping its own Item/Marker/Content/Connector API, its own event states, and its own (non-progressbar) semantics. The components share the rail recipe but own their size variables independently.
 
 **State boundaries:**
 

package/dist/docs/components/strong.md

@@ -105,7 +105,7 @@ Rules:
 
 ## Playground demo spec
 
-`Strong` is registered in `apps/playground/lib/registry/typography.tsx` under the `strong` key. The registry entry imports `strongPropDefs` and renders the component with a sample strong span. Per-component route: `/docs/strong`.
+`Strong` is registered in `apps/playground/lib/registry/typography.tsx` under the `strong` key. The registry entry imports `strongPropDefs` and renders the component with a sample strong span. Per-component route: `/docs/strong`. The live example uses English and Russian sentence context plus a slotted span.
 
 **Default story:**
 

package/dist/docs/components/tab-nav.md

@@ -23,10 +23,10 @@ A simpler horizontal tab bar for routing, where each tab is a real `<a>` element
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
 | `TabNav` (root) | `<nav>` | DS primitive + class | Wrapper that owns the `data-variant` and `data-size` attributes. |
-| `TabNav.List` | `<ul>` | DS primitive + class | Horizontal list of `TabNav.Link` items. Sets `role="tablist"`. |
-| `TabNav.Link` | `<li><a>` | DS primitive + class | The active link is wrapped in a list item. Sets `role="tab"`, `aria-selected`, and `tabIndex`. |
+| `TabNav.List` | `<ul>` | DS primitive + class | Wrapping native list of route links. |
+| `TabNav.Link` | `<li><a>` | DS primitive + class | The active link is wrapped in a list item. Uses native anchor semantics and `aria-current="page"` on the active route. |
 
-The list item wrapper (`<li class="dsx-tab-nav__list-item">`) is internal layout, not a public slot. The link host is the only element that carries the link's accessible name and `aria-selected` state.
+The list item wrapper (`<li class="dsx-tab-nav__list-item">`) is internal layout, not a public slot. The link host is the only element that carries the link's accessible name and `aria-current` state.
 
 ## Props contract
 
@@ -54,7 +54,7 @@ The list item wrapper (`<li class="dsx-tab-nav__list-item">`) is internal layout
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `active` | `boolean` | `false` | no | Marks the link as the current route. Drives `data-active="true"`, `aria-selected="true"`, and a focusable `tabIndex` (`0` for active, `-1` for inactive). | no |
+| `active` | `boolean` | `false` | no | Marks the link as the current route. Drives `data-active="true"` and `aria-current="page"`. All anchors with an href stay keyboard reachable. | no |
 | `asChild` | `boolean` | `false` | no | Renders the link through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. The component does not wire `asChild` through `extractProps`; the link consumes it directly. | no |
 | `href` | `string` | `undefined` | no | Standard anchor `href` for the navigation target. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-tab-nav__link`. | no |
@@ -66,7 +66,7 @@ Rules that apply to this row:
 - The root extends `React.HTMLAttributes<HTMLElement>` rather than `ComponentPropsWithoutRef<'nav'>`. Any standard HTML attribute (`id`, `aria-*`, `onClick`, etc.) is forwarded to the host.
 - `variant` and `size` are wired through `extractProps` only as far as needed to write the `data-*` attributes. The component then spreads the remaining extracted props onto the host. The prop def bag does not include a `className` mapping, so the size/variant class is only written as a `data-*` attribute, not as a BEM-style modifier class.
 - `asChild` on the root and the link is consumed directly (not through `extractProps`). When `asChild={true}`, the rendered element comes from `Slot` and the consumer owns the host.
-- The root does not manage keyboard roving focus. Active link gets `tabIndex={0}`; inactive links get `tabIndex={-1}`. The consumer (or a future enhancement) must add `onKeyDown` handling for `ArrowLeft` and `ArrowRight` to move focus across the list (see Anomalies).
+- All route anchors use native Tab navigation; Enter follows the href. The component does not implement tab-panel roving focus.
 
 ## CSS class contract
 
@@ -90,7 +90,7 @@ Rules that apply to this row:
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`.
+- The component does not use width breakpoints. `size` is single-value only; the prop def is not `responsive: true`.
 
 **Reduced motion:**
 
@@ -108,11 +108,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with `150ms` and
 | Gap (list) | `var(--dsx-space-xs)` | Spacing between links. |
 | List bullet | `none` | Reset. |
 | List padding/margin | `0` | Reset. |
-| List border (default) | `var(--dsx-border-width-md)` + `var(--dsx-color-outline-variant)` (bottom) | Default list separator. |
+| List border (default) | `var(--dsx-boundary-divider-width)` + `var(--dsx-color-outline-variant)` (bottom) | Default list separator. |
 | List background (pills) | `var(--dsx-color-surface-raised)` | Pill background. |
 | List padding (pills) | `var(--dsx-space-xs)` | Pill gutter. |
 | List radius (pills) | `var(--dsx-rounded-full)` | Pill shape. |
-| List border (underline) | `var(--dsx-border-width-md)` + `var(--dsx-color-outline-variant)` (bottom) | Underline variant separator. |
+| List border (underline) | `none` | Indicator-only variant. |
 | Link padding (md) | `var(--dsx-space-sm)` + `var(--dsx-space-md)` | Link hit area. |
 | Link padding (sm) | `var(--dsx-space-xs)` + `var(--dsx-space-sm)` | Compact hit area. |
 | Link padding (lg) | `var(--dsx-space-md)` + `var(--dsx-space-lg)` | Large hit area. |
@@ -121,11 +121,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with `150ms` and
 | Link color (default) | `var(--dsx-color-on-surface-variant)` | Resting text. |
 | Link color (hover) | `var(--dsx-color-on-surface)` | Hover text. |
 | Link background (hover) | `var(--dsx-effect-hover-ghost)` | Hover surface. |
-| Link color (active, default / underline) | `var(--dsx-color-primary)` | Active text. |
-| Link color (active, pills) | `var(--dsx-color-on-primary)` | Active text inside the pill. |
-| Link background (active, pills) | `var(--dsx-color-primary)` | Active pill. |
-| Indicator (default) | `var(--dsx-border-width-md)` + `var(--dsx-color-primary)` + `var(--dsx-rounded-full)` | Underline indicator. |
-| Indicator (underline) | `2px` (hard-coded) + `var(--dsx-color-primary)` + `var(--dsx-rounded-full)` | Underline variant indicator. The `2px` height is a CSS hard-code. |
+| Link color (active, default / underline) | `var(--dsx-color-accent-indicator)` | Active text. |
+| Link color (active, pills) | `var(--dsx-color-accent-contrast)` | Active text inside the pill. |
+| Link background (active, pills) | `var(--dsx-color-accent-track)` | Active pill. |
+| Indicator (default) | `var(--dsx-boundary-selected-width)` + `var(--dsx-color-accent-indicator)` + `var(--dsx-rounded-full)` | Underline indicator. |
+| Indicator (underline) | `var(--dsx-boundary-selected-width)` + `var(--dsx-color-accent-indicator)` + `var(--dsx-rounded-full)` | Underline variant indicator.  |
 | Link typography | `var(--dsx-typography-label-large-font-family/size/weight)`, sans-serif fallback | Default link text. |
 | Link typography (sm) | `var(--dsx-typography-label-medium-font-size)` | Compact link text. |
 | Link typography (lg) | `var(--dsx-typography-label-large-font-size)` | Large link text. |
@@ -134,7 +134,6 @@ Every CSS value the component paints is a `var(--dsx-*)` token, with `150ms` and
 
 Rules:
 
-- The `2px` indicator height in the `underline` variant is a CSS hard-code, not a token. The `default` variant uses `var(--dsx-border-width-md)`. This is a small inconsistency in the source CSS; both should be token-driven in a future cleanup (see Anomalies).
 - Alpha is reserved for effect tokens; the hover surface uses `var(--dsx-effect-hover-ghost)`.
 
 ## Motion contract
@@ -150,77 +149,15 @@ Rules:
 
 ## Accessibility
 
-**Roles:**
+The root is a navigation landmark. The list retains native list semantics; each href is a native link. `active` reflects `aria-current="page"`. Every link is reachable with Tab and activated with Enter. Arrow keys retain browser behavior.
 
-- Root: `nav` (semantic landmark when `asChild` is false). The list declares `role="tablist"`. Each link declares `role="tab"` and `aria-selected="true" | "false"`.
+Links show `var(--dsx-shadow-focus-ring)` on keyboard focus. The selected route also has a visible underline or pill. Consumers supply meaningful link text and an `aria-label` when several navigation landmarks occur on a page. Reduced motion disables color/background transitions.
 
-**Keyboard:**
-
-| Key | Action |
-|---|---|
-| `Tab` | Moves focus into and out of the tab list. Active link is the only focusable item. |
-| `Enter`, `Space` | Activates the focused link. |
-| `ArrowLeft`, `ArrowRight` | (Expected) Move focus across the tab list per the WAI-ARIA tabs pattern. The current source does NOT implement roving focus; consumers must add `onKeyDown` handling. |
-
-**Focus:**
-
-- Visible focus ring via `var(--dsx-shadow-focus-ring)` on `.dsx-tab-nav__link:focus-visible`.
-- Roving tab index: active link is `tabIndex={0}`; inactive links are `tabIndex={-1}`. The component does not move focus on `ArrowLeft` / `ArrowRight` itself (see Anomalies).
-
-**Reduced motion:**
-
-- The CSS transitions are disabled under `prefers-reduced-motion: reduce`. No runtime guard is needed.
-
-**Color and meaning:**
-
-- The active tab is communicated by `aria-selected="true"`, the indicator color (`--dsx-color-primary`), and the pill background in the `pills` variant. Color is not the only signal.
-
-**Naming:**
-
-- The link label is the accessible name. The root does not require an `aria-label`, but consumers that have multiple `<nav>` landmarks on the page should add `aria-label` to disambiguate (e.g. `Primary`, `Settings`).
+Every preview uses an application-owned hash navigation example with active page content, native href links and Back/Forward synchronization. No tab-panel roles or package router state are introduced.
 
 ## Playground demo spec
 
-The demo file at `demo_path` exposes the component to the playground. The playground lives at `apps/playground/app/` (Next.js app router, no per-component routes today). The `demo_path` recorded here is the current playground root; the spec assumes a single shared page that renders all components. Per-component routes are an aspirational target and not yet present in the repo.
-
-**Default story:**
-
-- Renders `TabNav` with `TabNav.List` and three `TabNav.Link` items, the first marked `active={true}`. Asserts the root class is `dsx-tab-nav`, `data-variant` is `default`, `data-size` is `md`, the list has `role="tablist"`, and the active link has `aria-selected="true"` and `tabIndex={0}`.
-
-**Variant story** (one per variant):
-
-- Renders TabNav with `variant="default"`, `variant="pills"`, and `variant="underline"`. Asserts the matching `data-variant` attribute on the root and the matching CSS treatment (underline indicator, pill background, etc.).
-
-**Size story:**
-
-- Renders TabNav with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute and the matching link padding.
-
-**Composition story:**
-
-- Renders TabNav with a `TabNav.List` containing three `TabNav.Link` items. Asserts each slot renders the right element with the right class and the inactive links carry `aria-selected="false"` and `tabIndex={-1}`.
-
-**State story:**
-
-- Renders the link in `default`, `hover` (`:hover` pseudo-class; no `data-*` attribute), and `focus` (`:focus-visible`; no `data-*` attribute). Asserts the focus ring is visible and `tabIndex` updates as `active` toggles.
-
-**Token story:**
-
-- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. The active indicator color tracks `data-accent-color` (it should resolve to the current `primary` token at runtime).
-
-**A11y story:**
-
-- Uses `vitest-axe` against the rendered default tab nav. Asserts there are no axe violations and that the active link carries `aria-selected="true"`. Arrow-key navigation is documented as a known gap (see Anomalies).
-
-**Props exposed in the playground controls:**
-
-| Prop | Control | Default |
-|---|---|---|
-| `variant` (root) | select | `default` |
-| `size` (root) | select | `md` |
-| `asChild` (root) | boolean | `false` |
-| `active` (link) | boolean | `false` |
-| `asChild` (link) | boolean | `false` |
-| `href` (link) | text | `#` |
+The variant and size matrix uses the same application-owned workspace navigation as the live gallery. Every link has a unique actual hash destination and active aria-current="page" state. Clicking Members/Settings changes the content and URL; Back/Forward, including return to the initial empty hash, restore the current example page. Default, pills and underline variants use identical page content. The package remains a native link surface; routing stays with the application.
 
 ## Wiring notes
 
@@ -235,13 +172,13 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 **State boundaries:**
 
-- Owned by TabNav: the root class, the `data-variant` and `data-size` attributes, the list `role="tablist"`, the link `role="tab"`, the `aria-selected` reflection, the `tabIndex` roving pattern, the focus ring, and the color/background transitions.
+- Owned by TabNav: the root class, the `data-variant` and `data-size` attributes, native list/link semantics, the `aria-current="page"` reflection, the focus ring, and the color/background transitions.
 - Owned by the consumer: the route data, the active-link detection (route matching), the keyboard roving focus implementation (until the source adds it), the host element when `asChild` is set, and the `<a href>` target.
 
 **Boundary rules:**
 
 - App-owned data: the route table, the active-route matcher, the navigation history, and any analytics on tab clicks.
-- DS-owned visuals: token bindings (`--dsx-space-{xs,sm,md,lg}`, `--dsx-color-{surface-raised,on-surface-variant,on-surface,on-primary,primary,outline-variant}`, `--dsx-border-width-md`, `--dsx-rounded-{md,full}`, `--dsx-typography-label-{large,medium}-*`, `--dsx-shadow-focus-ring`, `--dsx-effect-hover-ghost`, `--dsx-motion-duration-fast`, `--dsx-motion-easing-standard`), the `dsx-tab-nav` root class, the `dsx-tab-nav__list`, `dsx-tab-nav__list-item`, and `dsx-tab-nav__link` slot classes, and the variant CSS blocks.
+- DS-owned visuals: token bindings (`--dsx-space-{xs,sm,md,lg}`, `--dsx-color-{surface-raised,on-surface-variant,on-surface,on-primary,primary,outline-variant}`, `--dsx-boundary-selected-width`, `--dsx-rounded-{md,full}`, `--dsx-typography-label-{large,medium}-*`, `--dsx-shadow-focus-ring`, `--dsx-effect-hover-ghost`, `--dsx-motion-duration-fast`, `--dsx-motion-easing-standard`), the `dsx-tab-nav` root class, the `dsx-tab-nav__list`, `dsx-tab-nav__list-item`, and `dsx-tab-nav__link` slot classes, and the variant CSS blocks.
 
 ## Penpot build recipe
 
@@ -261,13 +198,13 @@ The package does not yet publish a Penpot asset for TabNav. Recipe is visual ref
 ```
 <Root Board: TabNav / default / md>
   └── <Frame: dsx-tab-nav>
-        └── <Frame: dsx-tab-nav__list (ul, role=tablist)>
+        └── <Frame: dsx-tab-nav__list (ul)>
               ├── <Frame: dsx-tab-nav__list-item (li)>
-              │     └── <Frame: dsx-tab-nav__link (a, role=tab, aria-selected=true, data-active=true)>
+              │     └── <Frame: dsx-tab-nav__link (a, aria-current=page, data-active=true)>
               ├── <Frame: dsx-tab-nav__list-item (li)>
-              │     └── <Frame: dsx-tab-nav__link (a, role=tab, aria-selected=false)>
+              │     └── <Frame: dsx-tab-nav__link (a)>
               └── <Frame: dsx-tab-nav__list-item (li)>
-                    └── <Frame: dsx-tab-nav__link (a, role=tab, aria-selected=false)>
+                    └── <Frame: dsx-tab-nav__link (a)>
 ```
 
 ### Token bindings (Penpot properties)
@@ -275,19 +212,19 @@ The package does not yet publish a Penpot asset for TabNav. Recipe is visual ref
 | Shape | Property | Token | Token type | Penpot property name |
 |---|---|---|---|---|
 | Root | (none) | n/a | n/a | n/a |
-| List (default / underline) | stroke (bottom) | `--dsx-color-outline-variant` | Color | `strokes` |
+| List (default) | stroke (bottom) | `--dsx-color-outline-variant` | Color | `strokes` |
 | List (pills) | fill | `--dsx-color-surface-raised` | Color | `fills` |
 | List (pills) | radius | `--dsx-rounded-full` | Radius | `radius` |
 | Link (resting) | text fill | `--dsx-color-on-surface-variant` | Color | `fills` |
 | Link (hover) | text fill | `--dsx-color-on-surface` | Color | `fills` (state) |
 | Link (hover) | background | `--dsx-effect-hover-ghost` | Effect | `fills` (state) |
-| Link (active, default / underline) | text fill | `--dsx-color-primary` | Color | `fills` (state) |
-| Link (active, pills) | text fill | `--dsx-color-on-primary` | Color | `fills` (state) |
-| Link (active, pills) | fill | `--dsx-color-primary` | Color | `fills` (state) |
-| Indicator (default) | fill | `--dsx-color-primary` | Color | `fills` (state) |
-| Indicator (default) | height | `--dsx-border-width-md` | Sizing | `size` |
-| Indicator (underline) | fill | `--dsx-color-primary` | Color | `fills` (state) |
-| Indicator (underline) | height | `2px` (hard-code) | Sizing | `size` |
+| Link (active, default / underline) | text fill | `--dsx-color-accent-indicator` | Color | `fills` (state) |
+| Link (active, pills) | text fill | `--dsx-color-accent-contrast` | Color | `fills` (state) |
+| Link (active, pills) | fill | `--dsx-color-accent-track` | Color | `fills` (state) |
+| Indicator (default) | fill | `--dsx-color-accent-indicator` | Color | `fills` (state) |
+| Indicator (default) | height | `--dsx-boundary-selected-width` | Sizing | `size` |
+| Indicator (underline) | fill | `--dsx-color-accent-indicator` | Color | `fills` (state) |
+| Indicator (underline) | height | `--dsx-boundary-selected-width` | Sizing | `size` |
 | Link (focus-visible) | shadow | `--dsx-shadow-focus-ring` | Effect | `shadow` (state) |
 
 ### State transformations
@@ -296,8 +233,8 @@ The package does not yet publish a Penpot asset for TabNav. Recipe is visual ref
 |---|---|---|---|
 | `default` (resting) | `--dsx-color-on-surface-variant` | transparent | none |
 | `hover` | `--dsx-color-on-surface` | `--dsx-effect-hover-ghost` | none |
-| `active` (default / underline) | `--dsx-color-primary` | transparent | `--dsx-color-primary` underline |
-| `active` (pills) | `--dsx-color-on-primary` | `--dsx-color-primary` | none |
+| `active` (default / underline) | `--dsx-color-accent-indicator` | transparent | `--dsx-color-accent-indicator` underline |
+| `active` (pills) | `--dsx-color-accent-contrast` | `--dsx-color-accent-indicator` | none |
 | `focus-visible` | (active or resting) | (active or resting) | `--dsx-shadow-focus-ring` ring |
 
 ### Variant model

package/dist/docs/components/table-of-contents.md

@@ -13,8 +13,14 @@ Article navigation over stable serialized heading IDs. `extractTableOfContentsHe
 
 ## API and behavior
 
-`items` contains `id`, `title`, and optional `level`. `activeId` and `onActiveIdChange` support control; `sticky` defaults true. Active links use `aria-current="location"`. Smooth scrolling is skipped for reduced motion, no-heading articles render no landmark, and the mobile layout is non-sticky.
+`items` contains `id`, `title`, and optional `level`. `activeId` and `onActiveIdChange` support control; `sticky` defaults true. Active links use `aria-current="location"`. Smooth scrolling is skipped for reduced motion, no-heading articles render no landmark, and sticky positioning applies at every width when `sticky` is true. Consumers choose placement through layout primitives; no component width breakpoint is used.
+
+Links provide a minimum 24px box and visible keyboard focus. Normal clicks scroll smoothly and push a history entry; reduced motion retains native anchor scrolling. Modified clicks retain native link behavior. The observer keeps intersection state across callbacks and selects the current visible heading or the last passed heading.
+
+The live example keeps navigation outside a bounded scrolling article. Application-owned activeId and onClickCapture handle that embedded scroll root; standalone window scroll-spy behavior remains in the package. The three heading targets exist, links retain native hash destinations, and the article is a keyboard-focusable region.
 
 ## Playground demo spec
 
-Show nested headings, active state, keyboard links, reduced-motion behavior, and an empty item list.
+Both the matrix and live example keep the TOC beside a bounded scrollable article on wide screens and above it on narrow screens. Existing activeId and onClickCapture props coordinate this embedded scroll root. Its three real headings can be reached by links or article scrolling; the article region is keyboard-focusable. The package's uncontrolled window observer remains unchanged.
+
+The embedded playground article uses natural section spacing; only the last section retains trailing scroll room so its heading can reach the viewport top.

package/dist/docs/components/tabs.md

@@ -84,7 +84,7 @@ The roster's `Parent / Slots` column lists `Tabs.Root`, `Tabs.List`, `Tabs.Trigg
 |---|---|---|---|---|---|
 | `asChild` | `boolean` | `false` | no | Renders the indicator through `Slot`. The active trigger's `getBoundingClientRect()` is used to position the indicator, so the `Slot` child must keep the same layout. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-tabs__indicator`. | no |
-| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style. The source sets `position: 'absolute'`, `bottom: 0`, `left: <position.left>`, `width: <position.width>`, and `transition: 'left 200ms ease, width 200ms ease'`. The consumer's `style` is merged after. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style. Measured inline geometry is left/width horizontally or left/top/height vertically. Position, paint and motion belong to CSS; consumer styles are merged after geometry. | no |
 
 ### `Tabs.ContentGroup`
 
@@ -97,7 +97,6 @@ The roster's `Parent / Slots` column lists `Tabs.Root`, `Tabs.List`, `Tabs.Trigg
 Rules:
 
 - The root, list, trigger, and content slots run through `extractProps` with the matching prop def bag.
-- `Tabs.Indicator` is not in the prop def bag; it manages its own positioning through a `useEffect` that reads the active trigger's `getBoundingClientRect()` relative to the list. The `transition` is hard-coded to `'left 200ms ease, width 200ms ease'` in the source.
 - The root throws an error (`Tabs compound components must be rendered within a Tabs root.`) if `Tabs.Indicator` is rendered outside a `Tabs.Root`, because the indicator reads from `TabsContext`.
 
 ## CSS class contract
@@ -131,11 +130,11 @@ Rules:
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`.
+- The component does not use width breakpoints. `size` is single-value only; the prop def is not `responsive: true`.
 
 **Reduced motion:**
 
-- The indicator transition (`left 200ms ease, width 200ms ease`) is hard-coded in the source. The CSS does not declare transitions for the trigger or the list. Consumers who need a hard gate can add a page-level `prefers-reduced-motion: reduce` rule that overrides the indicator transition.
+The indicator uses CSS motion-duration-normal and motion-easing-standard tokens. Component CSS disables its transition under reduced motion.
 
 ## Token mapping
 
@@ -144,8 +143,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token. The `tabs.css` f
 | Property | Token | Role |
 |---|---|---|
 | List display | `inline-flex` (CSS keyword) | Horizontal list layout. |
-| List border | `var(--dsx-border-width-md, var(--dsx-border-width-sm)) solid var(--dsx-control-separator-color)` | Default list bottom edge. |
-| List gap | `var(--dsx-space-xs)` | Gap between triggers. |
+| List border | `var(--dsx-boundary-divider-width) solid var(--dsx-control-separator-color)` | Default list bottom edge. |
+| List gap | `0` for default; `var(--dsx-space-xs)` for pills | Default underline tabs are contiguous. |
 | Pills list background | `var(--dsx-color-surface-raised)` | Pills variant surface. |
 | Pills list border | `0` (none) | Pills variant has no edge. |
 | Pills list border radius | `var(--dsx-rounded-full)` | Pills variant corner roundness. |
@@ -155,31 +154,24 @@ Every CSS value the component paints is a `var(--dsx-*)` token. The `tabs.css` f
 | Trigger color | `var(--dsx-color-on-surface-variant)` | Default trigger text. |
 | Trigger typography | `var(--dsx-typography-label-large-*)` | Trigger font family and size. |
 | Content group padding | `var(--dsx-space-md)` | Content group gutter. |
-| Indicator height | `2px` (CSS keyword) | Indicator thickness. |
-| Indicator background | `var(--dsx-color-accent)` | Active marker color. |
+| Indicator height | `var(--dsx-boundary-selected-width)` | Indicator thickness. |
+| Indicator background | `var(--dsx-color-accent-indicator)` | Active marker color. |
 | Indicator motion duration | `var(--dsx-motion-duration-normal)` | Indicator position transition. |
 | Indicator motion easing | `var(--dsx-motion-easing-standard)` | Indicator position easing. |
 
-Rules:
-
-- No raw color, spacing, radius, or motion values in `tabs.css` other than the indicator thickness (`2px`) and the indicator transition (`200ms ease`), which the source hard-codes.
-
 ## Motion contract
 
-| Region | Token | Default | Reduced |
-|---|---|---|---|
-| Indicator (left, width) | (hard-coded in source) `200ms ease` | 200ms ease | (CSS does not declare a reduced-motion override; the consumer app can gate the page-level `prefers-reduced-motion` rule) |
-| List / trigger / content (CSS) | `none` | `none` | `none` |
-
-Rules:
+| Region | Token | Reduced |
+|---|---|---|
+| Indicator left/width/top/height | `var(--dsx-motion-duration-normal)` and `var(--dsx-motion-easing-standard)` | Transition disabled |
 
-- The list and trigger have no CSS transitions. The indicator transition is hard-coded in the source; the CSS exposes a `var(--dsx-motion-duration-normal) var(--dsx-motion-easing-standard)` declaration for the indicator, but the source's inline `style` takes precedence.
+Indicator geometry follows the active DOM trigger on controlled or uncontrolled value changes, orientation changes, list scroll, and ResizeObserver notifications. Geometry is relative to the owning list. Vertical lists use a vertical marker and column triggers. Panel flex-basis is 50%, allowing intrinsic wrapping below the list when the two columns no longer fit. Root/list/trigger/content support their advertised `asChild` composition.
 
 ## Accessibility
 
 **Roles:**
 
-- `Tabs.Root` is `role="tablist"` (Radix).
+- `Tabs.List` is `role="tablist"` (Radix); the root is a non-semantic container.
 - `Tabs.Trigger` is `role="tab"` with `aria-selected` and `aria-controls` (Radix).
 - `Tabs.Content` is `role="tabpanel"` with `aria-labelledby` linked to the trigger (Radix).
 - `Tabs.Indicator` is decorative (`aria-hidden`).
@@ -199,11 +191,10 @@ Rules:
 
 **Focus:**
 
-- The CSS file does not declare a focus ring on the trigger; the shared tab list style in `_internal/baseTabs.css` paints the focus ring on `:focus-visible`. The ring stays visible on dark and light surfaces.
+- The trigger uses an inset canonical focus ring so a scrollable list does not clip it. The ring stays visible on dark and light surfaces.
 
 **Reduced motion:**
 
-- The indicator transition is hard-coded in the source. Consumers who need a hard gate can add a page-level `prefers-reduced-motion: reduce` rule.
 
 **Color and meaning:**
 
@@ -213,37 +204,13 @@ Rules:
 
 - Every trigger must have an accessible name from its children. Icon-only triggers need `aria-label`.
 
-## Playground demo spec
-
-**Default story:**
-
-- Renders `Tabs` with two triggers and two content panels. Asserts the first trigger has `data-state="active"` and `aria-selected="true"`, and the first content panel is visible.
-
-**Variant story:**
+Default tabs use an underline and transparent selected background; pills retain the solid accent fill. A static underline is provided when `Tabs.Indicator` is omitted. `ContentGroup` owns the 16px panel gap; child content has no additional top margin.
 
-- Renders `Tabs.List` with `variant="pills"`. Asserts `data-variant="pills"` on the list.
+The matrix exposes size, list variant and orientation with the same project panels as the live examples. Disabled settings and working activity panels are present in every composition.
 
-**State story:**
-
-- Clicks the second trigger and asserts the second trigger becomes `data-state="active"` while the first becomes `data-state="inactive"`. Renders a trigger with `disabled` and asserts `data-disabled` is present.
-
-**Composition story:**
-
-- Renders a `Tabs.ContentGroup` wrapping one `Tabs.Content`. Asserts the wrapper renders with `dsx-tabs__content-group` and `data-slot="tabs-content-group"`.
-
-**Token story:**
-
-- Renders `Tabs` inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`. The active trigger's indicator tracks `var(--dsx-color-accent)`, which is theme-aware.
-
-**A11y story:**
-
-- The `Tabs.test.tsx` suite covers the role contract via `screen.getByRole('tab', { name })` and the state transitions via `userEvent.click`. The registry does not need a separate `vitest-axe` check.
+## Playground demo spec
 
-**Props exposed in the playground controls:**
-
-| Prop | Control | Default |
-|---|---|---|
-| `size` | select | `md` |
+The matrix exposes root size, List variant (default/pills), and Radix orientation (horizontal/vertical). Each uses the same working project panels as the live examples: Overview, Activity, and disabled Settings. Default lists contain Tabs.Indicator; pills omit it. ContentGroup wraps the panels and applies the single gap. Arrow navigation changes the visible panel; disabled Settings is skipped.
 
 ## Wiring notes
 
@@ -266,3 +233,5 @@ Rules:
 
 - App-owned data: the tab registry, the panel content, the disabled reasons, and the deep-link policy.
 - DS-owned visuals: the `dsx-tabs` root class, the slot classes, the token bindings, and the `data-*` and ARIA attribute contract.
+
+Pills use accent-track with accent-contrast text. The default/vertical indicator uses accent-indicator, the foreground and stroke role.

package/dist/docs/components/text-field.md

@@ -128,6 +128,7 @@ Rules that apply to this row:
 
 - The component does not write `@media` rules. None of its prop defs are `responsive: true`. Density and radius are single-value only.
 - The component's CSS file is breakpoint-agnostic.
+- The inner input has `min-inline-size: 0`, so its intrinsic width yields to leading/trailing slots at 320px. Slot content remains visible inside the shell.
 
 **Reduced motion:**