@d4gger/design-system 3.0.0 → 4.0.0

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/table.md

@@ -16,6 +16,8 @@ depends_on:
 
 A read-heavy, semantically-correct HTML table with token-aligned typography, sizing, and density. Use `Table` for plain data presentation; reach for `DataTable` when sort, filter, density toggling, or pagination is required.
 
+**Relationship:** `Table` is the primitive (rows/cells, density, alignment, overflow); `DataTable` is the shell over `Table` (toolbar, selection, pagination, state). Column transforms (sorter, filter, selection, title layering) are a `DataTable`-side concern, not `Table`'s. See `data-table.md` for the shell's ownership statement.
+
 ## Anatomy & slots
 
 **Parent:** `Table` (alias of `TableRoot`). The root is a `<table>` element (or `Slot` host when `asChild` is set).
@@ -39,7 +41,7 @@ A read-heavy, semantically-correct HTML table with token-aligned typography, siz
 
 - The root renders a `<table>` with `border-collapse: separate; border-spacing: 0;` plus a single border + radius around the entire table.
 - `Table.Cell` is omitted from the last row's bottom border (`.dsx-table__body tr:last-child .dsx-table__cell { border-bottom: 0 }`).
-- Row hover is provided by `.dsx-table__body tr:hover` (background `var(--dsx-effect-hover-ghost)`).
+- Row hover is provided by `.dsx-table__body tr:hover` (background `var(--dsx-effect-hover-ghost)`, transitioned at `fast/standard`). No other hover rule paints rows.
 - `Table.Header` rows get a `var(--dsx-color-outline)` bottom border.
 - `Table.Footer` overrides the cell color to `var(--dsx-color-high-contrast)` and removes the bottom border, giving it the appearance of a summary row.
 - `Table.ColumnHeaderCell` uses `cursor: pointer` only when `sortable` is true, and renders a small `::after` arrow when `sorted` is set.
@@ -54,6 +56,7 @@ A read-heavy, semantically-correct HTML table with token-aligned typography, siz
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Cell padding scale. Writes `data-size`. | no |
 | `variant` | `'surface' \| 'ghost'` | `'surface'` | no | Visual treatment. `surface` paints a bordered card; `ghost` removes the border and surface color for use on a pre-existing background. Writes `data-variant`. | no |
 | `layout` | `'auto' \| 'fixed'` | `'auto'` | no | Maps to `table-layout: auto \| fixed`. Writes `data-layout`. Pair with `width="full"` on cells when `layout="fixed"`. | no |
+| `separator` | `'rules' \| 'grid'` | `'rules'` | no | Separator treatment. `rules` paints the header divider plus horizontal row rules only; `grid` additionally paints vertical rules between columns, for dense-financial data, pinned columns, or column resizing. Writes `data-separator`. | no |
 | `wrapScrollArea` | `boolean` | `false` | no | When `true`, wraps the `<table>` in `ScrollArea` so wide content scrolls horizontally. The `ScrollArea` viewport gets the `dsx-table__scroll-viewport` class. | no |
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot`; consumer supplies the host element. | no |
 
@@ -68,7 +71,7 @@ A read-heavy, semantically-correct HTML table with token-aligned typography, siz
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `justify` | `'start' \| 'center' \| 'end'` | `undefined` | no | Horizontal `justify-content` for the cell contents. Writes `data-justify`. | no |
+| `justify` | `'start' \| 'center' \| 'end'` | `undefined` | no | Logical horizontal text alignment of the native table cell; an explicit cell value overrides row alignment. Writes `data-justify`. | no |
 | `width` | `'auto' \| 'full'` | `undefined` | no | Cell width. `'full'` sets `width: 100%`; `'auto'` clears an inherited width. Writes `data-width`. The prop type also accepts an arbitrary string at the TS level, but only `'auto'` and `'full'` get CSS rules; an arbitrary string is forwarded through `data-width` but produces no visual change. | no |
 | `padding` | `'none' \| space-scale-value` | `undefined` | no | Cell padding override. `'none'` zeroes out the cell padding. Other space-scale values are forwarded through `data-padding` and inherit from the parent's `data-size` rules. | no |
 | `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
@@ -100,6 +103,7 @@ The remaining slots (`Table.Caption`, `Table.Header`, `Table.Body`, `Table.Foote
 | `data-size` | `sm`, `md`, `lg` | `.dsx-table[data-size='sm'] .dsx-table__head, .dsx-table__cell`, `.dsx-table[data-size='lg'] ...` | `table.css` |
 | `data-variant` | `surface`, `ghost` | `.dsx-table[data-variant='ghost']` (and child overrides) | `table.css` |
 | `data-layout` | `auto`, `fixed` | `.dsx-table[data-layout='fixed']` (maps to `table-layout: fixed`) | `table.css` |
+| `data-separator` | `rules`, `grid` | `.dsx-table[data-separator='grid']` (vertical rules between columns) | `table.css` |
 | `data-align` (row) | `start`, `center`, `end` | `.dsx-table__row[data-align='...'] .dsx-table__head, .dsx-table__cell` | `table.css` |
 | `data-justify` (cell) | `start`, `center`, `end` | `.dsx-table__cell[data-justify='...']` | `table.css` |
 | `data-width` (cell) | `auto`, `full` | `.dsx-table__cell[data-width='...']` | `table.css` |
@@ -128,6 +132,9 @@ The remaining slots (`Table.Caption`, `Table.Header`, `Table.Body`, `Table.Foote
 - The component does not write `@media` rules. Responsive layout comes from the layout primitives' responsive classes and from the responsive table-layout helpers in `styles/responsive/tableLayout.css` (`dsx-r-tl-auto`, `dsx-r-tl-fixed`).
 - The component's CSS file is breakpoint-agnostic.
 
+- `Cell.justify` maps to native `text-align` (start/center/end), preserving table layout.
+- Static column headers use the default cursor and allow text selection. Pointer cursor and selection suppression apply only to sortable headers.
+
 **Reduced motion:**
 
 - The component is static. No motion is applied.
@@ -163,9 +170,9 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Region | Token | Default | Reduced |
 |---|---|---|---|
-| (none) | none | none | n/a |
+| Body row hover (`background-color`) | `var(--dsx-motion-duration-fast) var(--dsx-motion-easing-standard)` | 150ms ease | (CSS declares no `prefers-reduced-motion` override; consumers who need a hard gate add a page-level rule) |
 
-The component has no motion. It is a static read surface.
+The component is otherwise a static read surface.
 
 ## Accessibility
 
@@ -189,7 +196,7 @@ The component has no motion. It is a static read surface.
 
 **Reduced motion:**
 
-- No motion is applied; no `prefers-reduced-motion` override is needed.
+- Only the body-row hover background transitions; no `prefers-reduced-motion` override is needed beyond a page-level rule.
 
 **Color and meaning:**
 
@@ -211,6 +218,7 @@ The component has no motion. It is a static read surface.
 **Variant story:**
 
 - Renders three tables: `variant="surface"`, `variant="ghost"`, and `layout="fixed"`. Asserts the matching `data-variant` and `data-layout` attributes.
+- Renders `separator="grid"`. Asserts `data-separator="grid"` and vertical rules between columns.
 
 **Size story:**
 
@@ -241,6 +249,7 @@ The component has no motion. It is a static read surface.
 | `size` | select | `md` |
 | `variant` | select | `surface` |
 | `layout` | select | `auto` |
+| `separator` | select | `rules` |
 | `wrapScrollArea` | boolean | `false` |
 
 ## Wiring notes

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/tag.md

@@ -14,8 +14,10 @@ depends_on:
 ## Purpose
 
 The single dismissible label chip. Badge is the static status/metadata token; Pills is the
-filter cluster; Status is the dot indicator; Tag is the one interactive chip with an
-optional remove action. Use for active filters, selected values, and removable labels.
+selectable filter cluster; Status is the dot indicator; Tag is the one chip that owns
+its own remove action. Use for active filters, selected values, and removable labels.
+Cardinality rule (F6 brief): one chip with a remove action is a Tag; a row of chips
+with selection state is Pills. Tag claims dismissal, never selection.
 
 ## Anatomy & slots
 

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