@d4gger/design-system 2.7.0 → 3.0.1

package/dist/docs/{status.md → components/status.md}

@@ -3,17 +3,12 @@ title: Status
 status: canonical
 category: Components
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/status/Status.tsx
-css_path: packages/d4gger-design-system/src/styles/components/status.css
-props_path: packages/d4gger-design-system/src/components/status/status.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Status.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on: []
 ---
 
 # Status
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{stepper.md → components/stepper.md}

@@ -3,13 +3,6 @@ title: Stepper
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/stepper/Stepper.tsx
-css_path: packages/d4gger-design-system/src/styles/components/stepper.css
-props_path: packages/d4gger-design-system/src/components/stepper/stepper.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Stepper.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/navigation.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Progress
   - Separator
@@ -19,7 +12,7 @@ depends_on:
 
 # Stepper
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -236,6 +229,7 @@ Both issues are now fixed: the vertical override sets `flex: 0` and uses `margin
 **Used by:**
 
 - App-level onboarding flows, multi-step forms, and wizard navigation. The roster explicitly calls out that `Stepper` is a composite, not a pattern, and that it must compose primitive `Indicator + Separator + Label` parts rather than a parallel visual shell.
+- Timeline (rail recipe consumer, CSS contract only — no component dependency): Timeline reuses the vertical rail geometry (dot-column centering calc, marker-bottom anchor, size-aware offsets, active-state recolor) for its left rail and centered alternate spine, while keeping its own Item/Marker/Content/Connector API, its own event states, and its own (non-progressbar) semantics. The vertical rail rules in `stepper.css` are the layout engine of record; keep them in sync with `timeline.css`.
 
 **State boundaries:**
 

package/dist/docs/{strong.md → components/strong.md}

@@ -3,17 +3,12 @@ title: Strong
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/strong/Strong.tsx
-css_path: packages/d4gger-design-system/src/styles/components/strong.css
-props_path: packages/d4gger-design-system/src/components/strong/strong.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Strong.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on: []
 ---
 
 # Strong
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -110,7 +105,7 @@ Rules:
 
 ## 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.
+`Strong` is registered in `apps/playground/lib/registry/typography.tsx` under the `strong` key. The registry entry imports `strongPropDefs` and renders the component with a sample strong span. Per-component route: `/docs/strong`.
 
 **Default story:**
 
@@ -126,7 +121,7 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper. Strong has no accent-color or surface dependencies, so the story asserts the bold weight is visually unchanged between `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`.
+- Renders inside a `Theme` wrapper. Strong has no accent-color or surface dependencies, so the story asserts the bold weight is visually unchanged between `accentColor="rift"`, `accentColor="warp"`, and `accentColor="ray"`.
 
 **A11y story:**
 

package/dist/docs/{switch.md → components/switch.md}

@@ -3,19 +3,12 @@ title: Switch
 status: canonical
 category: Primitives
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/switch/Switch.tsx
-css_path: packages/d4gger-design-system/src/styles/components/switch.css
-props_path: packages/d4gger-design-system/src/components/switch/switch.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Switch.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/forms.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Switch
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{tab-nav.md → components/tab-nav.md}

@@ -2,18 +2,13 @@
 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
+archetype: composite
 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{table-of-contents.md → components/table-of-contents.md}

@@ -3,8 +3,6 @@ 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

package/dist/docs/{table.md → components/table.md}

@@ -3,26 +3,21 @@ 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## 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.
 
+**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).
@@ -46,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.
@@ -61,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 |
 
@@ -75,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 |
@@ -107,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` |
@@ -135,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.
@@ -170,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
 
@@ -196,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:**
 
@@ -218,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:**
 
@@ -248,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/{tabs.md → components/tabs.md}

@@ -3,22 +3,14 @@ title: Tabs
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/tabs/Tabs.tsx
-css_path: packages/d4gger-design-system/src/styles/components/tabs.css
-props_path: packages/d4gger-design-system/src/components/tabs/tabs.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Tabs.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/navigation.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - "@radix-ui/react-tabs (the underlying Radix primitive; `Tabs.Root`, `Tabs.List`, `Tabs.Trigger`, `Tabs.Content` proxy to it)"
   - "Slot (the DS-local `Slot` re-export used by `Tabs.Indicator` and `Tabs.ContentGroup` for `asChild`)"
-  - _internal/helpers/extractProps (turns the prop defs on `Tabs`, `Tabs.List`, `Tabs.Trigger`, and `Tabs.Content` into merged class + style output)
 ---
 
 # Tabs
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/components/tag.md

@@ -0,0 +1,90 @@
+---
+title: Tag
+status: canonical
+category: Primitives
+archetype: primitive
+depends_on:
+  - Icon
+---
+
+# Tag
+
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+
+## Purpose
+
+The single dismissible label chip. Badge is the static status/metadata token; Pills is the
+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
+
+**Parent:** `Tag` (flat export with internal slots).
+
+**Slots:**
+
+| Slot | Class | Role |
+|---|---|---|
+| label | `dsx-tag__label` | Visible text. |
+| remove | `dsx-tag__remove` | Dismiss button, rendered only when `onRemove` is set. |
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'default' \| 'soft' \| 'outline'` | `'default'` | no | Visual treatment; writes `data-variant`. `soft` is the accent-3 family recipe. | no |
+| `size` | `'sm' \| 'md'` | `'md'` | no | Height scale; writes `data-size`. | no |
+| `color` | `string` | `undefined` | no | Accent color; writes `data-accent-color`. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner roundness; writes `data-radius`. Root defaults to pill. | no |
+| `highContrast` | `boolean` | `false` | no | High-contrast fill; writes `data-high-contrast="true"`. | no |
+| `onRemove` | `() => void` | `undefined` | no | When set, renders the remove button. Read off props directly (not in the prop-def bag). | no |
+| `removeLabel` | `string` | `'Remove'` | no | Accessible name for the remove button. Read off props directly. | no |
+| `asChild` | `boolean` | `false` | no | Renders through `Slot`. Remove button is suppressed in this mode. | no |
+
+## CSS class contract
+
+**Root class:** `dsx-tag`
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-variant` | `default`, `outline` | `.dsx-tag`, `.dsx-tag:where([data-variant='outline'])` | `tag.css` |
+| `data-size` | `sm`, `md` | `.dsx-tag:where([data-size='sm'])` etc. | `tag.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | `.dsx-tag:where([data-radius='...'])` | `tag.css` |
+| `data-high-contrast` | `true` | `.dsx-tag:where([data-high-contrast='true'])` | `tag.css` |
+
+## Token mapping
+
+| Property | Token | Role |
+|---|---|---|
+| Background (default) | `var(--dsx-color-accent-surface)` | Soft accent fill. |
+| Text (default) | `var(--dsx-color-accent-indicator)` | Accent foreground. |
+| Background (outline) | `transparent` | Outline fill. |
+| Border (outline) | `var(--dsx-color-outline)` | Outline edge. |
+| Background (HC) | `var(--dsx-color-high-contrast)` | High-contrast fill. |
+| Remove hover | `var(--dsx-effect-hover-ghost)` | Dismiss hover wash. |
+| Focus (remove) | `var(--dsx-shadow-focus-ring)` | Visible focus ring. |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in `tag.css`.
+- All variant/size selectors use `:where()` (specificity gate 0,2,0).
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Remove hover (`background-color`) | `var(--dsx-motion-duration-fast, 150ms)` | Washes the dismiss button on hover. | `transition: none` inside `@media (prefers-reduced-motion: reduce)`. |
+
+## Accessibility
+
+- Host is a `<span>`; the remove control is a real `<button type="button">` with an
+  accessible name (`removeLabel`, default `'Remove'`).
+- Remove button is keyboard-focusable with a visible focus ring.
+- `asChild` suppresses the remove button — the consumer owns dismissal semantics there.
+
+## Playground demo spec
+
+- Variants row (default, outline), sizes row (sm, md), removable row (with `onRemove`),
+  high-contrast row.

package/dist/docs/{tags-input.md → components/tags-input.md}

@@ -3,11 +3,6 @@ title: TagsInput
 status: canonical
 category: Components
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/tagsInput/TagsInput.tsx
-css_path: packages/d4gger-design-system/src/styles/components/tags-input.css
-props_path: packages/d4gger-design-system/src/components/tagsInput/tagsInput.props.ts
-test_path: packages/d4gger-design-system/src/test/components/TagsInput.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - Input (token-aligned input shell; the visual treatment is reused via `dsx-input-shell`-adjacent classes but the runtime does not import the `Input` component)
   - Badge (the per-tag chip uses the same surface tokens as `Badge` and shares the label-small typography ramp)
@@ -17,7 +12,7 @@ depends_on:
 
 # TagsInput
 
-> 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.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -42,6 +37,11 @@ The implementation is intentionally written in source rather than by composing t
 | `onChange` | `(value: string[]) => void` | `undefined` | no | Called with the next tag array on every change. | no |
 | `placeholder` | `string` | `'Add tag...'` | no | Placeholder text for the input. Only shown when there are zero tags. | no |
 | `maxTags` | `number` | `undefined` | no | Maximum number of tags. Adding a tag that would exceed `maxTags` is a no-op. | no |
+| `delimiter` | `string` | `','` | no | Split character: typing it commits the current text as tags, and paste splits on it. Single-character delimiters commit on keypress. | no |
+| `addOnPaste` | `boolean` | `false` | no | When `true`, pasting text splits it on the delimiter into multiple tags. | no |
+| `addOnBlur` | `boolean` | `false` | no | When `true`, blur commits the current text as a tag instead of discarding it. | no |
+| `disabled` | `boolean` | `false` | no | Disables input and remove buttons; root takes `dsx-tags-input--disabled` + `data-disabled`. | no |
+| `invalid` | `boolean` | `false` | no | Error state: container paints the error border, input carries `aria-invalid`. | no |
 | `variant` | `'surface' \| 'classic' \| 'ghost'` | `'surface'` | no | Visual treatment for the container. `'classic'` adds an elevated surface; `'ghost'` removes border and background until focused. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height and inner padding. Drives the `data-size` attribute and the size-specific CSS overrides. | no |
 | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Container corner radius override. Drives the `data-radius` attribute. | no |

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

@@ -0,0 +1,183 @@
+---
+title: TextAreaField
+status: canonical
+category: Components
+archetype: composite
+depends_on:
+  - TextArea (the inner control reuses the body-medium typography; the runtime does not import the `TextArea` component — the shell resizes via custom grip drag, native resize off)
+  - Label (the label slot renders through the `Label` primitive for accessible `<label htmlFor>` association)
+  - Text (the helper, error, and counter rows render through the `Text` primitive at the `label-small` ramp)
+  - "@radix-ui/react-slot"
+---
+
+# TextAreaField
+
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+
+## Purpose
+
+A composite label-plus-textarea-plus-counter field for fast form rows. The component bundles a label, a resizable shell with an inner textarea, an inside-shell character counter, and an optional helper or error text into one element, so multiline rows do not have to compose `Field` + `TextArea` + counter by hand. For richer form rows with grouped fields or validation orchestration, use `Field` directly.
+
+Roster note: the roster prefers explicit `Field` for new specs. This composite exists by maintainer decision (2026-09-15): the textarea review concluded the bare `TextArea` reads incomplete without its label/counter/helper set, and the set ships inside the component, not as a composition recipe.
+
+## Anatomy & slots
+
+**Parent:** `TextAreaField` (root, attached to the `Textarea` subcomponent via `Object.assign`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `TextAreaField.Root` | `<div>` (or slotted host) | `dsx-text-area-field`, `dsx-text-area-field--{size}`, `dsx-text-area-field--{variant}`, `dsx-text-area-field--resize-{resize}`, `dsx-text-area-field--invalid` (when invalid) + `data-accent-color`, `data-radius`, `data-size`, `data-variant` | Owns the field-row layout, the label, the shell, the counter, and the helper / error text. Holds the value state (controlled or uncontrolled) that drives the counter. |
+| `TextAreaField.Textarea` | `<textarea>` | `dsx-text-area-field__textarea` | The actual text entry. Inherits `id`, `aria-invalid`, `aria-describedby`, `maxLength`, `value`, and `onChange` from the root via context. Always `resize: none` — the shell owns resizing (Radix wrapper pattern). |
+
+**Internal layout (not slots):**
+
+| Element | Class | Notes |
+|---|---|---|
+| Root (`<div>`) | `dsx-text-area-field` (+ size / variant / resize / invalid modifiers) | Hosts the column layout. |
+| Label (`<label>`) | `dsx-text-area-field__label` | Renders through the `Label` primitive; bound to the textarea's `id` via `htmlFor`. |
+| Shell (`<div>`) | `dsx-text-area-field__shell` | The token-aligned border, background, and focus contract, reused from `baseInput.css`. Owns the `resize` behavior with `overflow: hidden`; the native grip renders on the shell corner. |
+| Footer (`<div>`) | `dsx-text-area-field__footer` | Inside-shell row under the textarea. Hosts the counter; rendered only when `showCount` is true. |
+| Counter (`<span>`) | `dsx-text-area-field__counter` (+ `dsx-text-area-field__counter--exceed` past max) | Renders through the `Text` primitive at `label-small` with the muted tone. `aria-live="polite"` (CommentThread precedent). Visual-only: excluded from `aria-describedby`. |
+| Error (`<span>`) | `dsx-text-area-field__error` | Renders through the `Text` primitive at `label-small` with the error color. |
+| Helper (`<span>`) | `dsx-text-area-field__helper` | Renders through the `Text` primitive at `label-small` with the muted tone. |
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `label` | `string` | `undefined` | no | Optional label string. When set, renders a `<label>` bound to the textarea's `id` via `htmlFor`. | no |
+| `helperText` | `string` | `undefined` | no | Optional helper text. Renders only when not invalid. | no |
+| `errorText` | `string` | `undefined` | no | Optional error message. Renders only when `invalid` is `true`. | no |
+| `id` | `string` | `undefined` | no | The id used for the label `htmlFor` and the textarea `id`. | no |
+| `value` | `string` | `undefined` | no | Controlled value. Drives the counter length. | no |
+| `defaultValue` | `string` | `undefined` | no | Uncontrolled initial value. Tracked internally for the counter. | no |
+| `onChange` | `(e) => void` | `undefined` | no | Change handler, forwarded to the inner textarea. | no |
+| `variant` | `enum` | `'surface'` | no | `'classic'`, `'surface'`, `'soft'`. Shell fill treatment. | no |
+| `size` | `enum` | `'md'` | no | `'sm'`, `'md'`, `'lg'`. Shell min-height, padding, and type scale. | no |
+| `invalid` | `boolean` | `false` | no | Marks the field as invalid. Borders the shell in error, sets `aria-invalid` on the textarea, and switches the error / helper visibility. | no |
+| `resize` | `enum` | `'vertical'` | no | `'none'`, `'vertical'`, `'horizontal'`, `'both'`. Drag axes for the grip; native resize is off. `none` hides the grip. | no |
+| `showCount` | `boolean` | `true` | no | Renders the inside-shell counter footer. | no |
+| `maxLength` | `number` | `undefined` | no | Inherited by the inner textarea (native enforcement while typing) and by the counter (`count / max`). Past-max values mark the counter exceed-red without truncating. | no |
+| `color` | `enum \| string` | `undefined` | no | Accent color token name. | no |
+| `radius` | `enum` | `undefined` | no | `'none'`, `'sm'`, `'md'`, `'lg'`. Shell radius. | no |
+
+## CSS class contract
+
+**Root class:** `dsx-text-area-field`
+
+**Modifier classes** (driven by props):
+
+| Prop | Class pattern | CSS file |
+|---|---|---|
+| `size` | `.dsx-text-area-field--sm`, `--md`, `--lg` | `text-area-field.css` |
+| `variant` | `.dsx-text-area-field--classic`, `--surface`, `--soft` | `text-area-field.css` (via `baseInput.css`) |
+| `resize` | `.dsx-text-area-field--resize-none`, `--resize-vertical`, `--resize-horizontal`, `--resize-both` | `text-area-field.css` |
+| `invalid` | `.dsx-text-area-field--invalid` | `text-area-field.css` |
+
+**Slot classes:** `dsx-text-area-field__label`, `dsx-text-area-field__shell`, `dsx-text-area-field__textarea`, `dsx-text-area-field__footer`, `dsx-text-area-field__counter` (+ `--exceed`), `dsx-text-area-field__grip`, `dsx-text-area-field__error`, `dsx-text-area-field__helper`.
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `size` is single-value only.
+
+**Reduced motion:**
+
+- TextAreaField has no motion. No transitions or animations are declared in `text-area-field.css` beyond the shell border-color transition inherited from the base pattern.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Grip ink and box | `var(--dsx-color-on-surface-variant)` + `var(--dsx-space-md)` | Chevron color and 16px hit area; vector artwork, no image assets |
+| Root gap | `var(--dsx-space-xs)` | Column gap between label, shell, and helper/error rows |
+| Shell border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Default edge; `var(--dsx-color-error)` when invalid; `var(--dsx-color-primary)` + `var(--dsx-shadow-focus-ring)` on focus-within |
+| Shell radius | `var(--dsx-rounded-md)` | Default shell radius, overridable via `radius` |
+| Shell min-height | `var(--dsx-textarea-min-height-base)` scaled per size | `sm` 0.75x, `md` 1x, `lg` 1.25x |
+| Shell padding | density control paddings with space fallbacks | Per-size block/inline padding |
+| Textarea type | body-medium / body-small (`sm`) / body-large (`lg`) | Inner control type scale |
+| Counter type | `label-small` ramp, muted tone | Counter row; `var(--dsx-color-error)` when past max |
+| Error text | `var(--dsx-color-error)` | Error row |
+| Helper text | `var(--dsx-color-on-surface-variant)` | Helper row |
+
+Rules:
+
+- The inner textarea is always `resize: none` with transparent background and no border; the shell resizes via grip drag. Native resize is off everywhere, so the grip works in every engine.
+- The counter `maxLength` (when set) is inherited by the inner textarea as the native attribute.
+- Past-max values never truncate; only the counter turns exceed-red.
+
+## Motion contract
+
+Shell border-color and box-shadow transition on `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)`, mirroring `TextField`.
+
+## Accessibility
+
+- Label bound via `htmlFor`/`id`. Consumer must pass `id` for the association (mirrors `TextField`).
+- Helper and error rows get `{id}-helper` / `{id}-error` ids; the textarea's `aria-describedby` points at whichever is rendered.
+- `aria-invalid` set on the textarea when `invalid`.
+- Counter carries `aria-live="polite"` (CommentThread precedent) and is excluded from `aria-describedby` (visual-only per cross-system consensus).
+
+## Playground demo spec
+
+- Default story: labeled field with helper text, no extra props.
+- Variant stories: classic / surface / soft.
+- Size stories: sm / md / lg.
+- State stories: invalid + errorText, disabled (via Textarea slot prop), showCount with maxLength, past-max controlled value (exceed-red, untruncated).
+- Composition story: every slot populated (label, textarea, counter, error).
+- Token story: renders inside `Theme` with `accentColor="rift"` and `accentColor="spark"`.
+
+## Wiring notes
+
+- No external adapters. Resizing is a custom pointer drag on the grip element (pointer capture, 120px / 40px min clamps, per-mode axes); hidden when `resize` is `none` or the control is disabled. The grip is focusable (`role="separator"`, arrows resize 8px / 32px with Shift) with hover brightening and a focus ring. Works identically in every engine, at every zoom.
+- Counter length reads the root's value state: controlled `value` when provided, otherwise internal state seeded from `defaultValue` and updated on change.
+- `maxLength` is forwarded to the inner textarea as the native attribute (typing enforcement) and consumed by the counter as the max.
+
+## Penpot build recipe
+
+### Root board
+
+- Name: `TextAreaField / Root`. Layout: vertical stack, 4px gap, full width.
+
+### Layer tree
+
+- `Label` (text layer, bound)
+- `Shell` (rounded rectangle, md radius)
+  - `Textarea` (text layer, body-medium)
+  - `Footer` (auto-layout row, counter left)
+- `Helper` / `Error` (text layer, label-small)
+
+### Token bindings (Penpot properties)
+
+- Shell fill/border: surface / outline tokens per variant; error red when invalid.
+- Type: label-small for label/counter/helper/error rows; body scale for the control per size.
+
+### State transformations
+
+| State | Shell fill | Stroke | Extra |
+|---|---|---|---|
+| `default` | surface per variant | outline | — |
+| `focus-within` | surface per variant | primary + focus ring | — |
+| `invalid` | surface per variant | error | helper swaps to error text |
+| `showCount` | surface per variant | outline | footer row with counter |
+| `exceed` | surface per variant | outline | counter turns error red, value untruncated |
+
+### Variant model
+
+- `variant`: `classic`, `surface`, `soft`. Default `surface`.
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `resize`: `none`, `vertical`, `horizontal`, `both`. Default `vertical`.
+- `invalid`: `true`, `false`. Default `false`.
+- `showCount`: `true`, `false`. Default `true`.
+- Total members: 144.
+
+### Validation checklist
+
+- [ ] Label `htmlFor` matches the textarea `id`.
+- [ ] Helper renders only when not invalid; error renders only when invalid.
+- [ ] Counter shows `count / max` with maxLength, bare count without.
+- [ ] Past-max controlled value: counter red, value intact.
+- [ ] Grip drags the shell on the allowed axes; hidden when `resize` is `none` or disabled.
+- [ ] No `console.error` for controlled/uncontrolled switching.