@d4gger/design-system 2.7.0

package/dist/docs/tab-nav.md

@@ -0,0 +1,321 @@
+---
+title: TabNav
+status: canonical
+category: Components
+archetype: primitive
+package_path: packages/d4gger-design-system/src/components/tabNav/TabNav.tsx
+css_path: packages/d4gger-design-system/src/styles/components/tab-nav.css
+props_path: packages/d4gger-design-system/src/components/tabNav/tabNav.props.ts
+test_path: packages/d4gger-design-system/src/test/components/TabNav.test.tsx
+demo_path: apps/playground/app/page.tsx
+depends_on: []
+---
+
+# TabNav
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+A simpler horizontal tab bar for routing, where each tab is a real `<a>` element rather than a Radix panel trigger. Use TabNav for site or app navigation that should not be tied to a linked `Tabs.Content` panel; for peer views with linked panels, use `Tabs`.
+
+## Anatomy & slots
+
+**Parent:** `TabNav` (compound export with `TabNav.List` and `TabNav.Link`).
+
+**Slots:**
+
+| 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`. |
+
+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.
+
+## Props contract
+
+### `TabNav` (root)
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'default' \| 'pills' \| 'underline'` | `'default'` | no | Visual variant. `'default'` and `'underline'` both render an underline indicator; `'default'` also paints a bottom border on the list. `'pills'` renders a pill-shaped segmented background with an inverted active state. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Height/density of the link targets via padding and font-size. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. The component does not wire `asChild` through `extractProps`; the root consumes it directly. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-tab-nav`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Slot content; expected to contain a `TabNav.List` with `TabNav.Link` children. | no |
+
+### `TabNav.List`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the list through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-tab-nav__list`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Slot content; expected to contain `TabNav.Link` children. | no |
+
+### `TabNav.Link`
+
+| 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 |
+| `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 |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Link label. | no |
+
+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).
+
+## CSS class contract
+
+**Root class:** `dsx-tab-nav`
+
+**Modifier classes** (driven by `data-*` attributes on the root):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-variant` | `default`, `pills`, `underline` | `.dsx-tab-nav[data-variant='default']`, `.dsx-tab-nav[data-variant='pills']`, `.dsx-tab-nav[data-variant='underline']` | `tab-nav.css` |
+| `data-size` | `sm`, `md`, `lg` | `.dsx-tab-nav[data-size='sm']`, `.dsx-tab-nav[data-size='md']`, `.dsx-tab-nav[data-size='lg']` | `tab-nav.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `TabNav` (root) | `dsx-tab-nav` | `tab-nav.css` |
+| `TabNav.List` | `dsx-tab-nav__list` | `tab-nav.css` |
+| internal list item | `dsx-tab-nav__list-item` | `tab-nav.css` |
+| `TabNav.Link` | `dsx-tab-nav__link` | `tab-nav.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`.
+
+**Reduced motion:**
+
+- The link's color and background-color transitions are wrapped in a `@media (prefers-reduced-motion: reduce)` block that sets `transition: none` on `.dsx-tab-nav__link`. The runtime does not import `usePrefersReducedMotion`; the override is CSS-only.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token, with `150ms` and `ease` as the motion-token fallbacks.
+
+| Property | Token | Role |
+|---|---|---|
+| Display (root) | `block` | Wrapper layout. |
+| Display (list) | `inline-flex` | Horizontal list. |
+| Align (list) | `center` | Vertically center links. |
+| 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 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. |
+| 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. |
+| Link radius (default / underline) | `var(--dsx-rounded-md)` | Link corners. |
+| Link radius (pills) | `var(--dsx-rounded-full)` | Pill-shaped links. |
+| 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 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. |
+| Focus ring | `var(--dsx-shadow-focus-ring)` | Visible focus on the link. |
+| Transition | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Color and background transitions. |
+
+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
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Link color and background transitions | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | `transition: background-color, color` on `.dsx-tab-nav__link`. | `none` — CSS `transition: none` inside `@media (prefers-reduced-motion: reduce)`. |
+
+Rules:
+
+- The component uses raw CSS transitions against the motion tokens. It does not import `MOTION_TRANSITIONS` from `src/_internal/motion.ts` and does not use framer-motion.
+- A future promotion that needs framer-motion (for example, an animated sliding indicator shared with `SegmentedControl`) should pick a preset from `MOTION_TRANSITIONS`.
+
+## Accessibility
+
+**Roles:**
+
+- Root: `nav` (semantic landmark when `asChild` is false). The list declares `role="tablist"`. Each link declares `role="tab"` and `aria-selected="true" | "false"`.
+
+**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`).
+
+## 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 | `#` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-slot` (`Slot`, `Slottable`): enables `asChild` for the root, list, and link.
+- No DS component composition. The component is a self-contained navigation surface; it does not depend on `Tabs` or any other DS primitive (the roster labels it a `primitive`).
+
+**Used by:**
+
+- App-level site and product navigation where each tab is a real route. The roster currently lists no DS components that consume `TabNav`; it is a leaf surface intended for direct app usage. Common composition targets are `Sidebar` and `Header`, but those compositions are app-owned.
+
+**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 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.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. Keep this section when the component has a published Penpot asset, or when the spec needs to call out a visual decision the package does not encode. Skip the section when the component is utility or layout-primitive; the package code is the only authority.
+
+The package does not yet publish a Penpot asset for TabNav. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / TabNav`.
+- **Dimensions**: `auto × auto` (wrapper); `auto × 48` at `md` for the list row.
+- **Layout**: `Flex` (column, root wraps a single list row).
+- **Sizing**: `horizontalSizing = 'auto'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board: TabNav / default / md>
+  └── <Frame: dsx-tab-nav>
+        └── <Frame: dsx-tab-nav__list (ul, role=tablist)>
+              ├── <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__list-item (li)>
+              │     └── <Frame: dsx-tab-nav__link (a, role=tab, aria-selected=false)>
+              └── <Frame: dsx-tab-nav__list-item (li)>
+                    └── <Frame: dsx-tab-nav__link (a, role=tab, aria-selected=false)>
+```
+
+### Token bindings (Penpot properties)
+
+| 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 (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 (focus-visible) | shadow | `--dsx-shadow-focus-ring` | Effect | `shadow` (state) |
+
+### State transformations
+
+| State | Link text fill | Link background | Indicator |
+|---|---|---|---|
+| `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 |
+| `focus-visible` | (active or resting) | (active or resting) | `--dsx-shadow-focus-ring` ring |
+
+### Variant model
+
+- `variant`: `default`, `pills`, `underline`. Default `default`.
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `active` (link): `true`, `false`. Default `false`.
+- Total members: 18 (3 × 3 × 2).
+
+### Validation checklist
+
+- [ ] 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.
+- [ ] `2px` indicator height in the `underline` variant is a CSS hard-code; document it as not themable in Penpot.
+- [ ] Roving focus is consumer-owned; document the keyboard gap in the Penpot validation notes.

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

@@ -0,0 +1,22 @@
+---
+title: TableOfContents
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/tableOfContents/TableOfContents.tsx
+css_path: packages/d4gger-design-system/src/styles/components/table-of-contents.css
+---
+
+# TableOfContents
+
+## Purpose
+
+Article navigation over stable serialized heading IDs. `extractTableOfContentsHeadings(root)` extracts h2–h4 anchors and `useHeadingObserver(ids)` exposes scroll-spy state.
+
+## 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.
+
+## Playground demo spec
+
+Show nested headings, active state, keyboard links, reduced-motion behavior, and an empty item list.

package/dist/docs/table.md

@@ -0,0 +1,277 @@
+---
+title: Table
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/table/Table.tsx
+css_path: packages/d4gger-design-system/src/styles/components/table.css
+responsive_css_path: packages/d4gger-design-system/src/styles/responsive/tableLayout.css
+props_path: packages/d4gger-design-system/src/components/table/table.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Table.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/data.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - ScrollArea
+---
+
+# Table
+
+> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+
+## Purpose
+
+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.
+
+## Anatomy & slots
+
+**Parent:** `Table` (alias of `TableRoot`). The root is a `<table>` element (or `Slot` host when `asChild` is set).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Table` (root) | `<table>` (or `Slot` host) | `dsx-table` | Root table. Writes `data-size`, `data-variant`, `data-layout`, `data-slot="table"`. |
+| `Table.Caption` | `<caption>` (or `Slot` host) | `dsx-table__caption` | Optional caption. Writes `data-slot="table-caption"`. |
+| `Table.Header` | `<thead>` (or `Slot` host) | `dsx-table__header` | Optional header section. Writes `data-slot="table-header"`. |
+| `Table.Body` | `<tbody>` (or `Slot` host) | `dsx-table__body` | Body section. Writes `data-slot="table-body"`. |
+| `Table.Footer` | `<tfoot>` (or `Slot` host) | `dsx-table__footer` | Optional footer section. Writes `data-slot="table-footer"`. |
+| `Table.Row` | `<tr>` (or `Slot` host) | `dsx-table__row` | Row. Writes `data-slot="table-row"`, `data-align`. |
+| `Table.Head` | `<th>` (or `Slot` host) | `dsx-table__head` | Header cell. Writes `data-slot="table-head"`. |
+| `Table.Cell` | `<td>` (or `Slot` host) | `dsx-table__cell` | Body cell. Writes `data-slot="table-cell"`, `data-justify`, `data-width`, `data-padding`. |
+| `Table.ColumnHeaderCell` | `<th>` (or `Slot` host) | `dsx-table__head dsx-table__column-header-cell` | Header cell with sort affordance. Forwards all `TableHeadProps` and adds `sortable` and `sorted` props that map to `data-sortable`, `data-sorted`, `role="columnheader"`, and `aria-sort`. |
+| `Table.RowHeaderCell` | `<th>` (or `Slot` host) | `dsx-table__cell dsx-table__row-header-cell` | Row-label cell. Sets `scope="row"` and `data-slot="table-row-header-cell"`. |
+
+**Internal layout:**
+
+- 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)`).
+- `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.
+- `Table.RowHeaderCell` is a `<th scope="row">` that keeps the same padding rhythm as `Table.Cell` but uses the label-medium type ramp.
+
+## Props contract
+
+**Root props (`Table`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `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 |
+| `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 |
+
+**Row props (`Table.Row`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `align` | `'start' \| 'center' \| 'end'` | `undefined` | no | Text alignment for every cell in the row. Writes `data-align`. | no |
+| `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
+
+**Cell props (`Table.Cell`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `justify` | `'start' \| 'center' \| 'end'` | `undefined` | no | Horizontal `justify-content` for the cell contents. 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 |
+
+**ColumnHeaderCell props (`Table.ColumnHeaderCell`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `sortable` | `boolean` | `false` | no | When `true`, the cell becomes interactive: writes `data-sortable="true"`, `role="columnheader"`, and an `aria-sort` of `'none'` (or `'ascending'` / `'descending'` when `sorted` is set). | no |
+| `sorted` | `'asc' \| 'desc'` | `undefined` | no | Active sort direction. Writes `data-sorted` and updates `aria-sort` accordingly. | no |
+| `asChild` | `boolean` | `false` | no | Inherited from `TableHeadProps`. | no |
+
+**RowHeaderCell props (`Table.RowHeaderCell`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Polymorphic host. | no |
+
+The remaining slots (`Table.Caption`, `Table.Header`, `Table.Body`, `Table.Footer`, `Table.Head`) accept only `asChild` plus the standard HTML attribute surface for their host elements.
+
+## CSS class contract
+
+**Root class:** `dsx-table`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `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-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` |
+| `data-padding` (cell) | `none`, space-scale value | `.dsx-table__cell[data-padding='none']` (other values inherit size rules) | `table.css` |
+| `data-sortable` (column header) | `true` | `.dsx-table__column-header-cell[data-sortable='true']` | `table.css` |
+| `data-sorted` (column header) | `asc`, `desc` | `.dsx-table__column-header-cell[data-sorted='asc'\|'desc']::after` | `table.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Table` (root) | `dsx-table` | `table.css` |
+| `Table.Caption` | `dsx-table__caption` | `table.css` |
+| `Table.Header` | `dsx-table__header` | `table.css` |
+| `Table.Body` | `dsx-table__body` | `table.css` |
+| `Table.Footer` | `dsx-table__footer` | `table.css` |
+| `Table.Row` | `dsx-table__row` | `table.css` |
+| `Table.Head` | `dsx-table__head` | `table.css` |
+| `Table.Cell` | `dsx-table__cell` | `table.css` |
+| `Table.ColumnHeaderCell` | `dsx-table__head dsx-table__column-header-cell` | `table.css` |
+| `Table.RowHeaderCell` | `dsx-table__cell dsx-table__row-header-cell` | `table.css` |
+| Scroll wrapper viewport | `dsx-table__scroll-viewport` | `table.css` |
+
+**Responsive behavior:**
+
+- 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.
+
+**Reduced motion:**
+
+- The component is static. No motion is applied.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Root border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Edge |
+| Root border-radius | `var(--dsx-rounded-lg)` | Roundness |
+| Root text color | `var(--dsx-color-on-surface)` | Default text color |
+| Root background | `var(--dsx-color-surface)` | Surface for `variant="surface"` |
+| Header bottom border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Header row separator |
+| Header cell text color | `var(--dsx-color-on-surface-variant)` | Header label color |
+| Header cell type ramp | `var(--dsx-typography-label-medium-*)` | Header text |
+| Header cell background | `var(--dsx-color-surface-raised)` | Header row background |
+| Default cell padding | `var(--dsx-space-sm) var(--dsx-space-md)` | `size="md"` cell padding |
+| `sm` cell padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Compact cell padding |
+| `lg` cell padding | `var(--dsx-space-md) var(--dsx-space-lg)` | Spacious cell padding |
+| Row hover | `var(--dsx-effect-hover-ghost)` | Subtle row hover |
+| Footer cell background | `var(--dsx-color-high-contrast-container)` | Summary row |
+| Footer cell color | `var(--dsx-color-high-contrast)` | Summary row text |
+| Footer cell weight | `var(--dsx-typography-label-large-font-weight)` | Summary row text weight |
+| `RowHeaderCell` color | `var(--dsx-color-on-surface-variant)` | Row label color |
+| `RowHeaderCell` type ramp | `var(--dsx-typography-label-medium-*)` | Row label |
+| `ColumnHeaderCell` arrow border | `var(--dsx-space-xs) solid currentColor` | Sort arrow |
+| Caption margin | `var(--dsx-space-md)` | Caption spacing |
+| Scroll viewport overflow | `auto` | Horizontal scroll when wrapped |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | none | none | n/a |
+
+The component has no motion. It is a static read surface.
+
+## Accessibility
+
+**Roles:**
+
+- The root renders a native `<table>`, which is the WAI-ARIA pattern for tabular data. No explicit `role="table"` is required.
+- `Table.Caption` is a native `<caption>`, which is programmatically associated with the table.
+- `Table.ColumnHeaderCell` adds `role="columnheader"` and `aria-sort` only when `sortable` is `true`. The `aria-sort` value is `'ascending'`, `'descending'`, or `'none'`. When `sortable` is `false`, no `role` and no `aria-sort` are written so the cell is a regular header.
+- `Table.RowHeaderCell` is a native `<th scope="row">`, which is the WAI-ARIA pattern for row header cells.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus through interactive elements inside cells (e.g. buttons, links). The `<th>` and `<td>` cells themselves are not focusable. |
+
+**Focus:**
+
+- The component does not render a focus ring on cell or row containers. Interactive cell content (buttons, links, sortable column headers when they wrap an interactive element) provides its own focus ring.
+- When a `Table.ColumnHeaderCell` is `sortable`, the consumer is expected to wrap or compose an interactive element (e.g. a Button) inside the cell so the sort action is keyboard-accessible. The TSX does not add `tabIndex` automatically.
+
+**Reduced motion:**
+
+- No motion is applied; no `prefers-reduced-motion` override is needed.
+
+**Color and meaning:**
+
+- Sort direction is communicated by both the `::after` arrow glyph and the `aria-sort` value. Color is not used to convey sort state.
+- Row hover uses a subtle background, not color alone, to indicate interactivity.
+
+**Naming:**
+
+- `Table.Caption` should describe the dataset or purpose of the table.
+- Header cells should be short, descriptive labels.
+- Sortable column headers should expose an accessible name through their child button/link or through a `<span>` with `VisuallyHidden` text describing the current sort state.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders a `Table` with one header row (`Region`, `Status`) and two body rows. Asserts the root is a `<table>` with class `dsx-table`, `data-size="md"`, `data-variant="surface"`, `data-layout="auto"`.
+
+**Variant story:**
+
+- Renders three tables: `variant="surface"`, `variant="ghost"`, and `layout="fixed"`. Asserts the matching `data-variant` and `data-layout` attributes.
+
+**Size story:**
+
+- Renders three tables: `size="sm"`, `size="md"`, `size="lg"`. Asserts the matching `data-size` attribute and that the `sm` / `lg` modifiers apply their own padding.
+
+**State story:**
+
+- Renders a table with `wrapScrollArea`. Asserts the `dsx-table__scroll-viewport` element wraps the `<table>`.
+- Renders a row with `align="center"`. Asserts `data-align="center"`.
+- Renders a cell with `justify="end"`, `width="full"`, and `padding="md"`. Asserts all three `data-*` attributes.
+
+**Composition story:**
+
+- Renders a `Table.Caption`, `Table.Header`, `Table.Body`, `Table.Footer`, plus `Table.ColumnHeaderCell` (sortable, `sorted="asc"`) and `Table.RowHeaderCell` (`scope="row"`). Asserts all slot classes and the `aria-sort="ascending"` value.
+
+**Token story:**
+
+- Renders the default table inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the `data-accent-color` attribute is forwarded, but the table surface is not themed by accent (it reads from `--dsx-color-surface`).
+
+**A11y story:**
+
+- Uses `vitest-axe` against the default story and against the sortable column-header story. Asserts no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `variant` | select | `surface` |
+| `layout` | select | `auto` |
+| `wrapScrollArea` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `ScrollArea` (`src/components/scrollArea/ScrollArea`): wraps the `<table>` when `wrapScrollArea` is set. The `ScrollArea` viewport receives the `dsx-table__scroll-viewport` class so CSS can scope the overflow rule to the table wrapper.
+- `@radix-ui/react-slot`: enables `asChild` on the root and on every named slot.
+
+**Used by:**
+
+- `DataTable` (`DataTable` composes the full `Table` slot set inside its controlled visual shell).
+- App-level read surfaces: lists, settings, audit logs, anything where the consumer owns data fetching and the table does not need sort, filter, or pagination.
+
+**State boundaries:**
+
+- Owned by Table: `size`, `variant`, `layout`, `wrapScrollArea`, row `align`, cell `justify` / `width` / `padding`, column header `sortable` and `sorted`, and the `dsx-table__*` slot classes.
+- Owned by the consumer: the row and cell data, the sort handler, the data source, the responsive layout, and any per-row or per-cell interactive content.
+
+**Boundary rules:**
+
+- App-owned data: rows, cells, sort behavior, pagination, and selection state.
+- DS-owned visuals: token bindings, slot classes, motion-free rendering, and the scroll wrapper integration.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. The package source is the only authority. Skip the section when the component is fully covered by the spec above; the spec's CSS class contract and token mapping table are the binding deliverable.