@d4gger/design-system 2.7.0 → 3.0.0

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.

package/dist/docs/{text-area.md → components/text-area.md}

@@ -3,19 +3,12 @@ title: TextArea
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/textArea/TextArea.tsx
-css_path: packages/d4gger-design-system/src/styles/components/textarea.css
-props_path: packages/d4gger-design-system/src/components/textArea/textArea.props.ts
-test_path: packages/d4gger-design-system/src/test/components/TextArea.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: []
 ---
 
 # TextArea
 
-> 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
 
@@ -39,7 +32,7 @@ No slots: flat export. The component renders a single `<textarea>` host element
 | `variant` | `'classic' \| 'surface' \| 'soft'` | `'surface'` | no | Visual treatment; writes `data-variant`. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control density; writes `data-size`. | no |
 | `color` | `string` (token name or CSS variable name) | `undefined` | no | Writes `data-accent-color`. The token layer resolves the value. | no |
-| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner roundness; writes `data-radius`. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg'` | `undefined` | no | Corner roundness; writes `data-radius`. Multiline never goes pill — `full` is not a value (the theme-scale selector would rewrite the rounded scale to 9999px on the element). | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-textarea`. | no |
 | `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host element. | no |
 | `value` | `string \| number` | `undefined` | no | Controlled value, forwarded to the host. | no |
@@ -72,7 +65,7 @@ Rules:
 |---|---|---|---|
 | `data-size` | `sm`, `md`, `lg` | (the attribute is written; the CSS contract reads the density tokens for block and inline padding) | `textarea.css` |
 | `data-variant` | `classic`, `surface`, `soft` | (the attribute is written; `baseInput.css` provides the variant fills) | `textarea.css` (via `baseInput.css`) |
-| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (the attribute is written; the CSS contract reads the radius tokens) | `textarea.css` (via `baseInput.css`) |
+| `data-radius` | `none`, `sm`, `md`, `lg` | (the attribute is written; the CSS contract reads the radius tokens) | `textarea.css` (via `baseInput.css`) |
 | `data-accent-color` | any token name | (the attribute is written; the CSS contract picks the accent token when present) | `textarea.css` (via `baseInput.css`) |
 | `invalid` prop | `true` | `.dsx-textarea--invalid` | `textarea.css` (via `baseInput.css`) |
 | `resize` prop | `none`, `vertical`, `horizontal`, `both` | `.dsx-textarea--resize-none`, `.dsx-textarea--resize-vertical`, `.dsx-textarea--resize-horizontal`, `.dsx-textarea--resize-both` | `textarea.css` |
@@ -102,11 +95,13 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Font weight | `var(--dsx-typography-body-medium-font-weight)` | Body font weight |
 | Line height | `var(--dsx-typography-body-medium-line-height)` | Body line height |
 | Resize handle | `none` / `vertical` / `horizontal` / `both` (CSS literal value) | `resize` CSS property; not a token |
+| Resize grip | platform-native (unstyled) | The bare primitive keeps the OS grip; the designed grip lives in `TextAreaField` |
 
 Rules:
 
 - The width declaration `width: 100%` is a CSS literal that mirrors HTML `<textarea>` behavior; it is not a token.
 - The `resize` value is a CSS keyword, not a token; the prop-to-class map is the only knob.
+- The bare control keeps the platform-native resize grip. Painted `::-webkit-resizer` chrome proved unkeepable across zoom and engines; do not re-add it here — the designed grip lives in `TextAreaField`.
 - Variant, radius, and accent-color fills come from the shared `baseInput.css` rules that `textarea.css` imports. No raw color or motion values are introduced in the textarea-specific CSS.
 
 ## Motion contract
@@ -264,7 +259,7 @@ The package does not yet publish a Penpot asset for TextArea. Recipe is visual r
 - `variant`: `classic`, `surface`, `soft`. Default `surface`.
 - `size`: `sm`, `md`, `lg`. Default `md`.
 - `resize`: `none`, `vertical`, `horizontal`, `both`. Default `vertical`.
-- `radius`: `none`, `sm`, `md`, `lg`, `full`. Default unset.
+- `radius`: `none`, `sm`, `md`, `lg`. Default unset (no `full` — see above).
 - `invalid`: boolean. Default `false`.
 - `color`: any token name. Default unset.
 - Total members: 3 × 3 × 4 × 5 × 2 × (color variants) = the matrix fans out from a single `variant` axis in the actual authoring board; the rest are CSS-only hooks.

package/dist/docs/{text-field.md → components/text-field.md}

@@ -3,23 +3,17 @@ title: TextField
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/textField/TextField.tsx
-css_path: packages/d4gger-design-system/src/styles/components/text-field.css
-props_path: packages/d4gger-design-system/src/components/textField/textField.props.ts
-test_path: packages/d4gger-design-system/src/test/components/TextField.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - Field (the canonical form-row wrapper; `TextField` is a convenience composition that bundles label, control, helper, and error into one slot, and is intended to live inside a `Field.Root` for app-level form rows)
   - Input (the inner input reuses the body-medium typography and the disabled / autofill contract from `baseInput.css`; the runtime does not import the `Input` component)
   - Label (the label slot renders through the `Label` primitive for accessible `<label htmlFor>` association)
   - Text (the helper and error text slots render through the `Text` primitive at the `label-small` ramp)
-  - "_internal/baseInput.css (shared shell, border, hover, focus, disabled, and autofill contract)"
   - "@radix-ui/react-slot"
 ---
 
 # TextField
 
-> 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
 
@@ -60,8 +54,8 @@ The roster's `Parent / Slots` column currently lists `-` (flat export) for `Text
 | `invalid` | `boolean` | `false` | no | Marks the field as invalid. Adds the `dsx-text-field--invalid` modifier class, sets `aria-invalid="true"` on the input, and switches the error / helper visibility. | no |
 | `density` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height and inner padding. Writes `data-size="sm"\|"md"\|"lg"` on the root and adds the `dsx-text-field--{value}` modifier class. | no |
 | `variant` | `'classic' \| 'surface' \| 'soft'` | `'surface'` | no | Shell surface treatment. `'surface'` is the bordered resting state; `'classic'` adds an elevation shadow; `'soft'` removes the border and uses the raised surface. | no |
-| `color` | `string` (any `data-accent-color` value) | `undefined` | no | Accent color override. Writes `data-accent-color` on the root. The prop def is `type: 'enum | string'` with an empty `values` array, so any string the consumer passes is accepted; the CSS does not currently declare `[data-accent-color='...']` rules. | no |
-| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner radius override. Writes `data-radius`. The CSS does not currently declare matching `[data-radius='...']` rules. | no |
+| `color` | `string` (any `data-accent-color` value) | `undefined` | no | Accent color override. Writes `data-accent-color` on the root; the shell focus border follows `var(--dsx-color-accent-indicator)` when set. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner radius override. Writes `data-radius`; the shell border-radius follows the matching `var(--dsx-rounded-*)` token. | no |
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. The label, shell, error, and helper stay on their default elements. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to the root. | no |
 | `style` | `React.CSSProperties` | `undefined` | no | Inline style forwarded to the root. | no |
@@ -77,8 +71,11 @@ The roster's `Parent / Slots` column currently lists `-` (flat export) for `Text
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
+| `side` | `'left' \| 'right'` | `undefined` | no | Edge the slot sits on. Writes `data-side`; the outer gutter is dropped on that side so edge icons sit flush with the shell. | no |
 | (extends `React.ComponentPropsWithoutRef<'div'>`) | n/a | n/a | no | Standard div attributes. The slot renders an inline-flex region next to the input. | no |
 
+At `density="sm"` there is not enough vertical room for nested interactive elements — keep slots to static icons or text, and put buttons in `md`/`lg` rows.
+
 Rules that apply to this row:
 
 - `TextFieldRootProps` extends `Omit<React.ComponentPropsWithoutRef<'div'>, 'color'>` because `color` is redefined by the prop bag.
@@ -98,8 +95,8 @@ Rules that apply to this row:
 |---|---|---|---|
 | `data-size` | `sm`, `md`, `lg` | `dsx-text-field--sm`, `dsx-text-field--md`, `dsx-text-field--lg` (applied in TSX, not via `extractProps`); no CSS rule for `[data-size='...']` | `text-field.css` |
 | `data-variant` | `classic`, `surface`, `soft` | `dsx-text-field--classic`, `dsx-text-field--surface`, `dsx-text-field--soft` (applied in TSX) plus `.dsx-text-field[data-variant='soft']` shell rules | `text-field.css` |
-| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (no CSS rule declared today; reserved) | `text-field.css` |
-| `data-accent-color` | any string | (no CSS rule declared today; the attribute is mirrored for theme-aware descendant styling) | `text-field.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | Shell border-radius follows the matching `var(--dsx-rounded-*)` token (`0` for `none`). | `text-field.css` |
+| `data-accent-color` | any string | Shell focus border follows `var(--dsx-color-accent-indicator)`. | `text-field.css` |
 
 **Visual modifier classes (root level):**
 
@@ -109,7 +106,7 @@ Rules that apply to this row:
 | `dsx-text-field--md` | Density override (md, default). | `text-field.css` |
 | `dsx-text-field--lg` | Density override (lg). | `text-field.css` |
 | `dsx-text-field--surface` | Variant override (surface, default). | `text-field.css` |
-| `dsx-text-field--classic` | Variant override (classic) — adds `var(--dsx-effect-shadow-1)` to the shell. | `text-field.css` |
+| `dsx-text-field--classic` | Variant override (classic) — raised fill + elevation over the surface shell, so it reads distinct on both themes. | `text-field.css` |
 | `dsx-text-field--soft` | Variant override (soft) — uses `var(--dsx-color-surface-raised)` and a transparent border. | `text-field.css` |
 | `dsx-text-field--invalid` | Adds the error border to the shell via the `:where(.dsx-text-field--invalid) .dsx-text-field__shell` rule in `baseInput.css`. | `_internal/baseInput.css` |
 

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

@@ -3,19 +3,12 @@ title: Text
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/text/Text.tsx
-css_path: packages/d4gger-design-system/src/styles/components/text.css
-props_path: packages/d4gger-design-system/src/components/text/text.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Text.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/typography.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Text
 
-> 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
 
@@ -40,7 +33,7 @@ No slots: flat export. The component renders a single `<span>` host element (or
 | `weight` | `string` | `undefined` | no | Typography weight. Writes the `dsx-r-weight-{name}` class. Accepts a responsive value. | yes |
 | `align` | `string` | `undefined` | no | Text alignment. Writes the `dsx-r-ta-{name}` class. Accepts a responsive value. | yes |
 | `wrap` | `string` | `undefined` | no | Text wrap. Writes the `dsx-r-wrap-{name}` class. | no |
-| `truncate` | `boolean` | `undefined` | no | When set, writes the `dsx-r-truncate` class. | no |
+| `truncate` | `boolean` | `undefined` | no | When set, writes the `dsx-truncate` class. | no |
 | `trim` | `string` | `undefined` | no | Leading-trim behavior. Writes the `dsx-r-lt-{name}` class. | no |
 | `highContrast` | `boolean` | `false` | no | When `true`, writes `data-high-contrast="true"`. | no |
 | `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my` | `string` | `undefined` | no | Margin style props from the `margin.prop` def. | no |
@@ -73,7 +66,7 @@ Rules that apply to this row:
 | (class) | any align name | `dsx-r-ta-{name}` (and breakpoint-prefixed variants) | `src/styles/responsive/*.css` |
 | (class) | any wrap name | `dsx-r-wrap-{name}` | `src/styles/responsive/*.css` |
 | (class) | any trim name | `dsx-r-lt-{name}` | `src/styles/responsive/*.css` |
-| (class) | `true` (truncate) | `dsx-r-truncate` | `src/styles/responsive/*.css` |
+| (class) | `true` (truncate) | `dsx-truncate` | `src/styles/responsive/truncate.css` |
 | `data-high-contrast` | `true` | `.dsx-text[data-high-contrast='true']` | `text.css` |
 
 **Slot classes:** none.
@@ -177,7 +170,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the `data-accent-color` attribute on the wrapper tracks the active accent.
+- Renders inside a `Theme` wrapper with `accentColor="warp"` and `accentColor="ray"`. Asserts the `data-accent-color` attribute on the wrapper tracks the active accent.
 
 **A11y story:**
 
@@ -221,6 +214,8 @@ Rules:
 - App-owned data: the prose context, the surrounding copy, and the host element when `asChild` is set.
 - DS-owned visuals: the `dsx-text` root class, the variant, tone, size, color, weight, align, wrap, trim, truncate, and high-contrast classes and attributes, and the prop def bag.
 
+> Caution (foundation vs app tone axes): the foundation `FoundationText` tone axis is `default | muted | primary | secondary | success | error` painted through the `--dsx-text-color` CSS variable, while this app-level `Text` tone axis is `default | muted | inverse` painted through modifier classes. The two contracts are not interchangeable — do not pass a foundation tone to `Text` or expect `dsx-text--inverse` from `FoundationText`.
+
 ## Penpot build recipe
 
 > Optional. Penpot is a visual reference, not a code authority. The Text recipe tracks the variant, tone, size, color, weight, align, wrap, trim, truncate, and high-contrast contract.

package/dist/docs/{theme-panel.md → components/theme-panel.md}

@@ -3,13 +3,6 @@ title: ThemePanel
 status: canonical
 category: Foundations
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/themePanel/ThemePanel.tsx
-css_path: packages/d4gger-design-system/src/styles/components/theme-panel.css
-props_path: packages/d4gger-design-system/src/components/themePanel/themePanel.props.ts
-test_path: packages/d4gger-design-system/src/test/components/ThemePanel.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/utility.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Text
   - Badge
@@ -21,7 +14,7 @@ depends_on:
 
 # ThemePanel
 
-> 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
 
@@ -40,7 +33,7 @@ A read-mostly visual panel for inspecting the active theme tokens. Each row pair
 
 **Internal layout:**
 
-- The root is a flex column with `gap: var(--dsx-space-xs)`, a `var(--dsx-space-md)` padding, a `var(--dsx-rounded-lg)` radius, an `var(--dsx-color-surface-overlay)` background, a 1px `var(--dsx-color-outline-variant)` outline, and the body-medium type ramp.
+- The root is a flex column with `gap: var(--dsx-space-xs)`, a `var(--dsx-space-md)` padding, a `var(--dsx-rounded-lg)` radius, an `var(--dsx-color-panel-translucent)` background, a 1px `var(--dsx-color-outline-variant)` outline, and the body-medium type ramp.
 - `ThemePanel.Row` is a flex row with `align-items: center`, `justify-content: space-between`, `gap: var(--dsx-space-md)`, and a small `var(--dsx-space-xs) 0` vertical padding. The label sits on the left; the value / children sit on the right.
 - The label uses the `dsx-theme-panel__label` class so the muted text color (`var(--dsx-color-on-surface-variant)`) is enforced even if the consumer changes the surrounding context.
 
@@ -92,7 +85,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Root gap | `var(--dsx-space-xs)` | Vertical gap between rows |
 | Root padding | `var(--dsx-space-md)` | Internal gutter |
 | Root border-radius | `var(--dsx-rounded-lg)` | Roundness |
-| Root background | `var(--dsx-color-surface-overlay)` | Panel surface |
+| Root background | `var(--dsx-color-panel-translucent)` | Panel surface |
 | Root border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline-variant)` | Edge |
 | Root type ramp | `var(--dsx-typography-body-medium-*)` | Body text |
 | Row gap | `var(--dsx-space-md)` | Horizontal gap between label and value |
@@ -159,7 +152,7 @@ The component has no motion.
 
 **Token story:**
 
-- Renders the default panel inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the panel surface tracks `--dsx-color-surface-overlay` and is unaffected by the accent token; the value chip's text color is driven by the `Badge` component.
+- Renders the default panel inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the panel surface tracks `--dsx-color-panel-translucent` and is unaffected by the accent token; the value chip's text color is driven by the `Badge` component.
 
 **A11y story:**
 

package/dist/docs/{theme-provider.md → components/theme-provider.md}

@@ -3,25 +3,19 @@ title: ThemeProvider
 status: canonical
 category: Foundations
 archetype: utility
-package_path: packages/d4gger-design-system/src/components/themeProvider/ThemeProvider.tsx
-props_path: packages/d4gger-design-system/src/components/themeProvider/themeProvider.props.ts
-test_path: packages/d4gger-design-system/src/test/components/ThemeProvider.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/utility.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Theme
 ---
 
 # ThemeProvider
 
-> 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
 
-The persisted theme provider. It mirrors the full `data-dsx-*` attribute contract to the document, resolves the active light or dark mode from a `'system'` media query or a stored `light`/`dark` choice, and exposes a `useTheme` hook with imperative setters for every persisted dimension.
+The persisted theme provider. It mirrors the full `data-dsx-*` attribute contract to the document, resolves the active light or dark mode from a stored choice or the active host environment, and exposes a `useTheme` hook with imperative setters for every persisted dimension. In `'system'` mode a Telegram Mini App uses `Telegram.WebApp.colorScheme`; ordinary browsers fall back to `prefers-color-scheme`.
 
-`ThemeScript` (same directory: `ThemeScript.tsx`) is the pre-hydration companion. `ThemeProvider` can only apply the document attribute contract once React mounts, which is always after the SSR-rendered HTML exists — on a direct page load that gap is visible as an SSR-default frame before the persisted/system theme takes over. `ThemeScript` renders a blocking `<script>` for the SSR document `<head>` that reads the same `storageKey` schema and resolves `system` via `matchMedia` before first paint, closing that gap. `getThemeInitScript(options)` returns the same logic as a plain string for callers building their own `<script>` tag (e.g. to attach a CSP `nonce` in a custom `_document`).
+`ThemeScript` (same directory: `ThemeScript.tsx`) is the pre-hydration companion. `ThemeProvider` can only apply the document attribute contract once React mounts, which is always after the SSR-rendered HTML exists — on a direct page load that gap is visible as an SSR-default frame before the persisted/system theme takes over. `ThemeScript` renders a blocking `<script>` for the SSR document `<head>` that reads the same `storageKey` schema and resolves `system` with the same Telegram-first, media-query-fallback precedence before first paint, closing that gap. `getThemeInitScript(options)` returns the same logic as a plain string for callers building their own `<script>` tag (e.g. to attach a CSP `nonce` in a custom `_document`).
 
 ## Anatomy & slots
 
@@ -36,8 +30,8 @@ No slots: flat export. The component renders no wrapper element. It provides two
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `storageKey` | `string` | (none) | yes | `localStorage` key used to persist and restore the active dimensions. Required: the provider errors if it is missing. | no |
-| `defaultTheme` | `'light' \| 'dark' \| 'system'` | `'system'` | no | Initial `mode` value used during SSR and on first render before `localStorage` is read. `'system'` resolves the active mode from `window.matchMedia('(prefers-color-scheme: dark)')`. | no |
-| `accentColor` | `'amber' \| 'silver' \| 'bronze'` | `undefined` | no | Initial accent. Falls back to the foundation default (`'amber'`) when unset. Persisted as part of the storage payload. | no |
+| `defaultTheme` | `'light' \| 'dark' \| 'system'` | `'system'` | no | Initial `mode` value used during SSR and on first render before `localStorage` is read. `'system'` resolves from `Telegram.WebApp.colorScheme` when available, then `window.matchMedia('(prefers-color-scheme: dark)')`. | no |
+| `accentColor` | `'rift' \| 'warp' \| 'ray' \| 'astral' \| 'spark'` | `undefined` | no | Initial accent. Falls back to the foundation default (`'rift'`) when unset. Persisted as part of the storage payload. | no |
 | `grayColor` | `'auto' \| 'neutral'` | `undefined` | no | Initial gray color. Falls back to the foundation default (`'auto'`) when unset. Persisted. | no |
 | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Initial radius preset. Falls back to the foundation default (`'md'`) when unset. Persisted. | no |
 | `panelBackground` | `'solid' \| 'translucent'` | `undefined` | no | Initial panel background. Falls back to the foundation default (`'translucent'`) when unset. Persisted. | no |
@@ -164,7 +158,7 @@ The playground does not expose `ThemeProvider` controls because the provider is
 **Composes from:**
 
 - `Theme` infrastructure: `applyThemeToDocument`, `ThemeContext`, and the `ThemeContextValue` type from `foundations/Theme`.
-- React `useState`, `useLayoutEffect`, `useEffect`, `useCallback`, `useMemo`, and the `matchMedia` browser API for system theme resolution.
+- React `useState`, `useLayoutEffect`, `useEffect`, `useCallback`, `useMemo`, Telegram's optional `WebApp` bridge, and the `matchMedia` browser API for fallback system-theme resolution.
 - No Radix primitive. No portal.
 
 **Used by:**
@@ -180,7 +174,7 @@ The playground does not expose `ThemeProvider` controls because the provider is
 
 **State boundaries:**
 
-- Owned by ThemeProvider: the resolved mode (`light` or `dark`), the persisted `localStorage` payload, the system media-query subscription, and the document-level attribute mirror through `applyThemeToDocument`.
+- Owned by ThemeProvider: the resolved mode (`light` or `dark`), the persisted `localStorage` payload, the active Telegram `themeChanged` or system media-query subscription, and the document-level attribute mirror through `applyThemeToDocument`.
 - Owned by the consumer: the persistence key (`storageKey`), the initial dimensions, and the consumer-side handling of `useTheme`'s setters.
 
 **Boundary rules:**

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

@@ -3,18 +3,12 @@ title: Theme
 status: canonical
 category: Foundations
 archetype: utility
-package_path: packages/d4gger-design-system/src/foundations/Theme.tsx
-css_path: packages/d4gger-design-system/src/styles/components/theme-panel.css
-test_path: packages/d4gger-design-system/src/test/foundations/Theme.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/utility.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Theme
 
-> 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
 
@@ -34,13 +28,13 @@ No slots: flat export. The component renders a single wrapper element (default `
 |---|---|---|---|---|---|
 | `mode` | `'light' \| 'dark'` | `undefined` | no | Light or dark appearance. Falls back to inherited `ThemeContext`, then to `DEFAULT_THEME_CONTEXT_VALUE.mode` (`'dark'`). | no |
 | `appearance` | `'light' \| 'dark' \| 'inherit'` | `undefined` | no | Overrides `mode` for one render. `'inherit'` keeps the inherited or document `data-dsx-theme` value and lets the remaining theme state override freely. | no |
-| `accentColor` | `'amber' \| 'silver' \| 'bronze'` | `undefined` | no | Active accent. Falls back to inherited context, then to `DEFAULT_THEME_CONTEXT_VALUE.accentColor` (`'amber'`). | no |
+| `accentColor` | `'rift' \| 'warp' \| 'ray' \| 'astral' \| 'spark'` | `undefined` | no | Active accent. Falls back to inherited context, then to `DEFAULT_THEME_CONTEXT_VALUE.accentColor` (`'rift'`). | no |
 | `grayColor` | `'auto' \| 'neutral'` | `undefined` | no | Gray color family. Falls back to inherited context, then to `DEFAULT_THEME_CONTEXT_VALUE.grayColor` (`'auto'`). | no |
 | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Border radius preset. Falls back to inherited context, then to `DEFAULT_THEME_CONTEXT_VALUE.radius` (`'md'`). | no |
 | `panelBackground` | `'solid' \| 'translucent'` | `undefined` | no | Panel background treatment. Falls back to inherited context, then to `DEFAULT_THEME_CONTEXT_VALUE.panelBackground` (`'translucent'`). | no |
 | `density` | `'comfortable' \| 'compact'` | `undefined` | no | Density mode. Falls back to inherited context, then to `DEFAULT_THEME_CONTEXT_VALUE.density` (`'comfortable'`). | no |
 | `scaling` | `'90' \| '95' \| '100' \| '105' \| '110'` | `undefined` | no | UI scaling step. Falls back to inherited context, then to `DEFAULT_THEME_CONTEXT_VALUE.scaling` (`'100'`). The attribute is removed from the document when `scaling` is `undefined`. | no |
-| `surface` | `'theme' \| 'transparent'` | `'theme'` | no | When `'theme'`, the wrapper paints `var(--dsx-color-surface)` via the `dsx-theme--surface` class and `data-has-background="true"`. When `'transparent'`, no surface is painted and `data-has-background` is omitted. | no |
+| `surface` | `'theme' \| 'transparent'` | `'theme'` | no | When `'theme'`, the wrapper paints `var(--dsx-color-background)` via the `dsx-theme--surface` class and `data-has-background="true"`. When `'transparent'`, no surface is painted and `data-has-background` is omitted. | no |
 | `applyToDocument` | `boolean` | `false` | no | Mirrors the resolved theme attributes to `html` and `body` (and restores the prior snapshot on unmount) instead of only scoping to the wrapper. | no |
 | `asChild` | `boolean` | `false` | no | Renders the wrapper through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
 | `as` | `React.ElementType` | `'div'` | no | Polymorphic host element when `asChild` is `false`. | no |
@@ -67,7 +61,7 @@ Rules that apply to this row:
 | `data-dsx-theme` | `light`, `dark` | (CSS contract from token layer) | n/a |
 | `data-dsx-density` | `comfortable`, `compact` | (CSS contract from token layer) | n/a |
 | `data-dsx-scaling` | `90`, `95`, `100`, `105`, `110` | (CSS contract from token layer) | n/a |
-| `data-accent-color` | `amber`, `silver`, `bronze` | (CSS contract from token layer) | n/a |
+| `data-accent-color` | `rift`, `warp`, `ray`, `astral`, `spark` | (CSS contract from token layer) | n/a |
 | `data-gray-color` | `auto`, `neutral` | (CSS contract from token layer) | n/a |
 | `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (CSS contract from token layer) | n/a |
 | `data-panel-background` | `solid`, `translucent` | (CSS contract from token layer) | n/a |
@@ -85,11 +79,11 @@ Rules that apply to this row:
 
 ## Token mapping
 
-The component does not consume a token directly through CSS. The attribute contract it writes is the source of truth for the token layer (`tokens.css`); every `data-dsx-*` value the wrapper writes resolves to a token family. `dsx-theme--surface` paints `var(--dsx-color-surface)` when the surface is active. `colorScheme` is set to the resolved `mode` (`'light'` or `'dark'`) so the browser paints native form controls correctly inside the themed subtree.
+The component does not consume a token directly through CSS. The attribute contract it writes is the source of truth for the token layer (`tokens.css`); every `data-dsx-*` value the wrapper writes resolves to a token family. `dsx-theme--surface` paints `var(--dsx-color-background)` when the surface is active. `colorScheme` is set to the resolved `mode` (`'light'` or `'dark'`) so the browser paints native form controls correctly inside the themed subtree.
 
 | Property | Token | Role |
 |---|---|---|
-| Surface (when `surface="theme"`) | `var(--dsx-color-surface)` | Wrapper background. |
+| Surface (when `surface="theme"`) | `var(--dsx-color-background)` | Wrapper background. |
 | Native color scheme | resolved `mode` (`light` \| `dark`) | Maps to `colorScheme` style for native controls. |
 
 Rules:
@@ -97,7 +91,7 @@ Rules:
 - The wrapper does not paint border, padding, or radius. Surface application is the only visible effect; the rest of the surface family comes from downstream components reacting to the attributes.
 - `data-dsx-scaling` is removed (rather than set to `undefined`) when no scaling is resolved. The token layer treats the missing attribute as the default `100%` scale.
 - Accent roles are semantic, not four names for one color. `accent-track` owns solid fills, `accent-contrast` owns their foreground, `accent-indicator` owns accent-as-foreground/indicator paint, and `accent-surface` owns subtle tinted backgrounds.
-- Light mode intentionally separates bright track values from darker indicator values. Local silver/bronze `data-accent-color` overrides inherit the nearest Theme's appearance palette, including when the accent attribute is on a descendant component rather than the Theme host.
+- Light mode intentionally separates bright track values from darker indicator values. Local `data-accent-color` overrides inherit the nearest Theme's appearance palette, including when the accent attribute is on a descendant component rather than the Theme host.
 
 ## Motion contract
 
@@ -157,7 +151,7 @@ Rules:
 
 **Token story:**
 
-- The wrapper is the source of `data-accent-color`. Other components are demonstrated inside `Theme accentColor="silver"` and `Theme accentColor="bronze"` to show the attribute contract threading through nested children.
+- The wrapper is the source of `data-accent-color`. Other components are demonstrated inside `Theme accentColor="warp"` and `Theme accentColor="ray"` to show the attribute contract threading through nested children.
 
 **A11y story:**
 
@@ -169,7 +163,7 @@ Rules:
 |---|---|---|
 | `mode` | select | `dark` |
 | `appearance` | select | `inherit` |
-| `accentColor` | select | `amber` |
+| `accentColor` | select | `rift` |
 | `grayColor` | select | `auto` |
 | `radius` | select | `md` |
 | `panelBackground` | select | `translucent` |

package/dist/docs/{time-picker.md → components/time-picker.md}

@@ -3,13 +3,6 @@ title: TimePicker
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/timePicker/TimePicker.tsx
-css_path: packages/d4gger-design-system/src/styles/components/time-picker.css
-props_path: packages/d4gger-design-system/src/components/timePicker/timePicker.props.ts
-test_path: packages/d4gger-design-system/src/test/components/TimePicker.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:
   - Popover
   - ScrollArea
@@ -19,7 +12,7 @@ depends_on:
 
 # TimePicker
 
-> 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/{timeline.md → components/timeline.md}

@@ -3,13 +3,6 @@ title: Timeline
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/timeline/Timeline.tsx
-css_path: packages/d4gger-design-system/src/styles/components/timeline.css
-props_path: packages/d4gger-design-system/src/components/timeline/timeline.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Timeline.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:
   - Text
   - Badge
@@ -18,7 +11,7 @@ depends_on:
 
 # Timeline
 
-> 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