@d4gger/design-system 3.0.1 → 4.0.1

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:**
 

package/dist/docs/components/text.md

@@ -12,7 +12,7 @@ depends_on: []
 
 ## Purpose
 
-The app-level body text primitive. Renders a `<span>` (or the consumer's host element) with token-aligned typography, a token-backed color prop, a `tone` modifier for muted or inverse contexts, a responsive `size` scale, and the shared margin, padding, alignment, wrap, trim, weight, truncate, high-contrast, and `asChild` infra.
+The app-level body text primitive. Renders a `<span>` (or a consumer host through `asChild`) with token-aligned typography, a token-backed color prop, a `tone` modifier for muted or inverse contexts, a nine-step `size` scale, and the shared margin, padding, alignment, wrap, trim, weight, truncate, high-contrast, and `asChild` infra.
 
 ## Anatomy & slots
 
@@ -20,7 +20,7 @@ The app-level body text primitive. Renders a `<span>` (or the consumer's host el
 
 **Slots:**
 
-No slots: flat export. The component renders a single `<span>` host element (or the consumer's host element when `as` or `asChild` is set) with the `dsx-text` root class, the variant modifier class (when no `size` is set), and any `tone` modifier class.
+No slots: flat export. The component renders a single `<span>` host element (or the consumer's host element when `asChild` is set) with the `dsx-text` root class, the variant modifier class (when no `size` is set), and any `tone` modifier class.
 
 ## Props contract
 
@@ -28,16 +28,16 @@ No slots: flat export. The component renders a single `<span>` host element (or
 |---|---|---|---|---|---|
 | `variant` | `'body-large' \| 'body-medium' \| 'body-small' \| 'label-large' \| 'label-medium' \| 'label-small'` | `'body-medium'` | no | Typography ramp. Writes the `dsx-text--{variant}` modifier class. Omitted when `size` is set. | no |
 | `tone` | `'default' \| 'muted' \| 'inverse'` | `'default'` | no | Tone modifier. Writes `dsx-text--{tone}` for `muted` and `inverse`. | no |
-| `size` | `'1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'` | `undefined` | no | Responsive size scale. When set, the `size` class (`dsx-r-text-size-{1..9}`) replaces the variant class. Accepts a responsive value (`{ initial, sm, md, lg, xl, 2xl }`). | yes |
-| `color` | token name string | `undefined` | no | Free-form color token reference. Writes `data-accent-color` and the matching `dsx-r-color-{name}` class. Accepts a responsive value. | yes |
-| `weight` | `string` | `undefined` | no | Typography weight. Writes the `dsx-r-weight-{name}` class. Accepts a responsive value. | yes |
-| `align` | `string` | `undefined` | no | Text alignment. Writes the `dsx-r-ta-{name}` class. Accepts a responsive value. | yes |
-| `wrap` | `string` | `undefined` | no | Text wrap. Writes the `dsx-r-wrap-{name}` class. | no |
+| `size` | `'1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'` | `undefined` | no | Scalar size scale. When set, the size class replaces the variant class. | no |
+| `color` | shared semantic color enum | `undefined` | no | Values are listed in the class contract below. Writes `data-accent-color` and the matching `dsx-r-color-{name}` class. | no |
+| `weight` | `'light' \| 'regular' \| 'medium' \| 'bold'` | `undefined` | no | Typography weight. Writes the `dsx-r-weight-{name}` class. | no |
+| `align` | `'left' \| 'center' \| 'right' \| 'justify'` | `undefined` | no | Text alignment. Writes the `dsx-r-ta-{name}` class. | no |
+| `wrap` | `'wrap' \| 'nowrap' \| 'pretty' \| 'balance'` | `undefined` | no | Text wrap. Writes the `dsx-r-tw-{name}` class. | no |
 | `truncate` | `boolean` | `undefined` | no | When set, writes the `dsx-truncate` class. | no |
-| `trim` | `string` | `undefined` | no | Leading-trim behavior. Writes the `dsx-r-lt-{name}` class. | no |
+| `trim` | `'normal' \| 'start' \| 'end' \| 'both'` | `undefined` | no | Leading-trim behavior. Writes the `dsx-r-lt-{name}` class. | no |
 | `highContrast` | `boolean` | `false` | no | When `true`, writes `data-high-contrast="true"`. | no |
-| `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my` | `string` | `undefined` | no | Margin style props from the `margin.prop` def. | no |
-| `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py` | `string` | `undefined` | no | Padding style props from the `padding.prop` def. | no |
+| `margin`, `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my` | `string` | `undefined` | no | Scalar margin style props from the `margin.prop` def. | no |
+| `padding`, `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py` | `string` | `undefined` | no | Scalar padding style props from the `padding.prop` def. | 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-text`. | no |
 | `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
@@ -54,18 +54,18 @@ Rules that apply to this row:
 
 **Root class:** `dsx-text`
 
-**Modifier classes** (driven by the prop def bag and the responsive helpers):
+**Modifier classes** (driven by the scalar prop def bag and shared class extraction):
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | (class) | `body-large`, `body-medium`, `body-small`, `label-large`, `label-medium`, `label-small` | `dsx-text--{variant}` (omitted when `size` is set) | `text.css` |
 | (class) | `muted`, `inverse` | `dsx-text--muted`, `dsx-text--inverse` | `text.css` |
-| `data-size` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9` | `dsx-r-text-size-{n}` (and breakpoint-prefixed `sm:`, `md:`, `lg:`, `xl:`, `2xl:`) | `text.css` (and `src/styles/responsive/*.css`) |
-| `data-accent-color` | any token name | `dsx-r-color-{name}` (and breakpoint-prefixed variants) | `src/styles/responsive/*.css` |
-| (class) | any weight name | `dsx-r-weight-{name}` (and breakpoint-prefixed variants) | `src/styles/responsive/*.css` |
-| (class) | any align name | `dsx-r-ta-{name}` (and breakpoint-prefixed variants) | `src/styles/responsive/*.css` |
-| (class) | any wrap name | `dsx-r-wrap-{name}` | `src/styles/responsive/*.css` |
-| (class) | any trim name | `dsx-r-lt-{name}` | `src/styles/responsive/*.css` |
+| `data-size` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9` | `dsx-r-text-size-{n}` | `text.css` |
+| `data-accent-color` | `primary`, `primary-container`, `secondary`, `secondary-container`, `tertiary`, `tertiary-container`, `success`, `success-container`, `error`, `error-container`, `surface`, `surface-raised`, `surface-overlay`, `surface-sunken`, `background`, `outline`, `outline-variant` | `dsx-r-color-{name}` | `src/styles/responsive/*.css` |
+| (class) | `light`, `regular`, `medium`, `bold` | `dsx-r-weight-{name}` | `src/styles/responsive/*.css` |
+| (class) | `left`, `center`, `right`, `justify` | `dsx-r-ta-{name}` | `src/styles/responsive/*.css` |
+| (class) | `wrap`, `nowrap`, `pretty`, `balance` | `dsx-r-tw-{name}` | `src/styles/responsive/*.css` |
+| (class) | `normal`, `start`, `end`, `both` | `dsx-r-lt-{name}` | `src/styles/responsive/*.css` |
 | (class) | `true` (truncate) | `dsx-truncate` | `src/styles/responsive/truncate.css` |
 | `data-high-contrast` | `true` | `.dsx-text[data-high-contrast='true']` | `text.css` |
 
@@ -73,13 +73,15 @@ Rules that apply to this row:
 
 **Responsive behavior:**
 
-- `size`, `color`, `weight`, and `align` are `responsive: true` in the prop def bag. The prop def bag applies breakpoint-prefixed classes (`sm:`, `md:`, `lg:`, `xl:`, `2xl:`) through the `responsive/*` style layer.
-- The component itself does not write `@media` rules. The `responsive/*` files are the source of the breakpoint-prefixed classes.
+- All typography and spacing props are scalar. This family emits no breakpoint-prefixed classes and has no viewport rules. Responsive page layout belongs to `Box`, `Flex` and `Grid`.
+- The maintainer approved removing the previous responsive typography API on 2026-10-04: “better to do it best versions from the get go and dont make backwards”. This is a breaking type change; release classification must reflect it.
 
 **Reduced motion:**
 
 - Text has no motion. No transitions or animations are declared in `text.css`.
 
+High contrast preserves `on-inverse-background` when `tone="inverse"` is used on its paired surface. Normal-surface high-contrast ink must not replace an inverse foreground.
+
 ## Token mapping
 
 Every CSS value the component paints is a `var(--dsx-*)` token.
@@ -97,12 +99,16 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | 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. |
-| Responsive size 1–9 | `var(--dsx-typography-*-font-size)` | `dsx-r-text-size-1` through `dsx-r-text-size-9` map to the same typography tokens. |
-| Margin / padding | `var(--dsx-r-m*)`, `var(--dsx-r-p*)` | The `margin.prop` and `padding.prop` defs write `--dsx-r-*` variables that the responsive layer consumes. |
+| Scalar size 1–9 | `var(--dsx-typography-*-font-size)` | `dsx-r-text-size-1` through `dsx-r-text-size-9` map to the same typography tokens. |
+| Margin / padding | `var(--dsx-r-margin-{top,right,bottom,left})`, `var(--dsx-r-p*)` | Numeric, named and arbitrary spacing utilities resolve the local margins and padding. |
 
 Rules:
 
-- Tokens come from `DESIGN.md` and the generated `tokens.css`. The variant classes are the only modifiers; the responsive size classes are the second axis.
+- Tokens come from `DESIGN.md` and the generated `tokens.css`. The variant classes are the only modifiers; the size classes are the second axis.
+
+Spacing custom properties are reset locally so ancestor padding and margins do not leak into this element. Named margins use the same resolved directional variables as numeric and arbitrary values. Weight utilities resolve to 300 / 400 / 500 / 700.
+
+The scalar size scale paints font size and the matching role line height. Its existing role-derived size mapping is preserved. Responsive objects are outside the public contract; compose responsive page layout with Box, Flex or Grid.
 
 ## Motion contract
 
@@ -118,7 +124,7 @@ Rules:
 
 **Roles:**
 
-- The component renders a `<span>` by default (or the consumer's host element when `as` / `asChild` is set). It has no implicit role. Consumers that need a paragraph should set `as="p"`.
+- The component renders a `<span>` by default (or the consumer's host element when `asChild` is set). It has no implicit role. Consumers that need a paragraph should use `asChild` with a `<p>`.
 
 **Keyboard:**
 
@@ -154,11 +160,11 @@ Rules:
 
 **Size story:**
 
-- Renders Text with each `size` value. Asserts the `data-size` attribute and the `dsx-r-text-size-{n}` class. Responsive `size` produces breakpoint-prefixed classes.
+- Renders Text with each `size` value. Asserts the `data-size` attribute and the `dsx-r-text-size-{n}` class. Size remains unchanged when the viewport changes; responsive maps are rejected by the public type.
 
 **Color story:**
 
-- Renders Text with each `color` token name. Asserts the `data-accent-color` attribute and the `dsx-r-color-{name}` class. Responsive `color` produces breakpoint-prefixed classes.
+- Renders Text with each `color` token name. Asserts the `data-accent-color` attribute and the `dsx-r-color-{name}` class. Color is scalar; responsive maps are rejected by the public type.
 
 **Composition story** (for `asChild`):
 
@@ -170,7 +176,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="warp"` and `accentColor="ray"`. Asserts the `data-accent-color` attribute on the wrapper tracks the active accent.
+- Renders inside a `Theme` wrapper with `accentColor="rift"` and `accentColor="warp"`. Asserts the `data-accent-color` attribute on the wrapper tracks the active accent.
 
 **A11y story:**
 
@@ -206,8 +212,8 @@ Rules:
 
 **State boundaries:**
 
-- Owned by Text: the root class, the variant and tone modifier classes, the responsive size class, the color and weight responsive classes, the alignment, wrap, trim, and truncate classes, the high-contrast attribute, the `data-size` and `data-accent-color` attributes, and the prop def bag.
-- Owned by the consumer: the text body, the host element when `as` / `asChild` is set, and any extra `className` / `style` applied through prop forwarding.
+- Owned by Text: the root class, the variant and tone modifier classes, the size class, the color and weight classes, the alignment, wrap, trim, and truncate classes, the high-contrast attribute, the `data-size` and `data-accent-color` attributes, and the prop def bag.
+- Owned by the consumer: the text body, the host element when `asChild` is set, and any extra `className` / `style` applied through prop forwarding.
 
 **Boundary rules:**
 

package/dist/docs/components/theme-panel.md

@@ -131,36 +131,11 @@ The component has no motion.
 
 - The `label` prop should be the human-readable token name ("Mode", "Accent", "Density"). The `value` should be the current setting ("dark", "amber", "compact"). When the row is interactive, the consumer is responsible for the accessible name of the interactive control.
 
-## Playground demo spec
-
-**Default story:**
-
-- Renders a `ThemePanel` with three `Row`s: `label="Mode" value="dark"`, `label="Accent" value="amber"`, `label="Radius" value="medium"`. Asserts the root class is `dsx-theme-panel` and each row renders the matching label and `Badge` value.
-
-**Variant story:**
-
-- The component has no variant. Skip the variant story.
-
-**State story:**
-
-- Renders a row with custom `children` (e.g. a `<span data-testid="custom">` element). Asserts the custom content is rendered and the default `Badge` is suppressed.
-- Renders a `ThemePanel asChild` wrapping a `<section>` and asserts the root class is moved onto the host element.
+The live example explains that the panel displays app-supplied values and reflects the playground preferences; it is not a built-in theme editor.
 
-**Composition story:**
-
-- Renders the full panel: six rows covering `Mode`, `Accent`, `Gray`, `Radius`, `Density`, `Scaling`. Asserts all six labels and values resolve, and the `dsx-theme-panel__row` class is applied to every row.
-
-**Token story:**
-
-- Renders the default panel inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the panel surface tracks `--dsx-color-panel-translucent` and is unaffected by the accent token; the value chip's text color is driven by the `Badge` component.
-
-**A11y story:**
-
-- Uses `vitest-axe` against the default story. Asserts no axe violations.
-
-**Props exposed in the playground controls:**
+## Playground demo spec
 
-The playground registry for `theme-panel` does not expose prop controls. The component has no variants or size scale; the registry render explains that the panel is mounted live inside `ConfigDrawer` and a second inline instance would conflict with the active one.
+The compact render and full live example show values supplied from the playground theme context. The live description explains application ownership; current appearance/accent/gray/radius/density/scaling update with preferences, and a custom row shows consumer content. The panel does not modify the theme itself.
 
 ## Wiring notes