@d4gger/design-system 2.7.0 → 3.0.1

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
 
@@ -41,8 +34,9 @@ A vertical or alternating event timeline for activity feeds, audit logs, and ord
 **Internal layout:**
 
 - The root renders a flex column. Items are stacked vertically.
+- Rail/connector geometry is shared with Stepper's vertical rail engine (see `stepper.md` and `stepper.css` `.dsx-stepper--vertical .dsx-stepper__item:not(:last-child)::after`): the connector is item-local, anchored at the marker bottom (`top` = marker size) and stretched to the item bottom (`bottom: 0`), centered on the dot column via `calc(marker-size / 2 - rail-width / 2)` with size-aware overrides per `data-size`. Timeline keeps its own `Connector` DOM node (Stepper draws via `::after` and hides its `Separator`) and its own rail width (`--dsx-border-width-sm`); the geometry recipe is shared, the slot API and ARIA roles stay distinct. The two components are never merged: Stepper answers "where am I in a process" (`role="progressbar"`), Timeline answers "what happened, when" (per-event states, no progress semantics). Precedent: antd Timeline renders `<Steps type="dot">`.
 - In the `left` variant (the default), every item is a flex row with `gap: var(--dsx-space-lg)`. The marker sits on the left rail; the content fills the remaining space.
-- In the `alternate` variant, every item is a full-width flex row; the consumer is responsible for the alternating side-by-side layout (CSS does not alternate automatically).
+- In the `alternate` variant, every item is a three-column grid (`minmax(0, 1fr) auto minmax(0, 1fr)`): the `1fr` tracks exist without any spacer element, so equal `fr` shares keep the marker exactly on the dot column in both parities. Odd items place content in column 1 (`text-align: right`), even items in column 3; the marker is always column 2. Placement is explicit (`grid-column` + `grid-row: 1`), so DOM order is irrelevant. The connector runs down the item's vertical centerline (`left: calc(50% - rail-width / 2)`), which is the marker center. DOM order stays Marker-then-Content by convention; the split is pure CSS, so no prop or slot change was needed.
 - `Timeline.Marker` is a square (`var(--dsx-size-md)`) fully rounded element with a 1px outline. It accepts arbitrary children, typically an `Icon` or a number from the consumer.
 - `Timeline.Connector` is an absolutely positioned vertical bar inside the item. It begins at the bottom of the marker and extends to the bottom of the item. Width is `var(--dsx-border-width-sm)` and color is `var(--dsx-color-outline-variant)`. The active state recolors it to `var(--dsx-color-primary)`.
 - `Timeline.Content` is the consumer's content surface. The CSS file defines helper classes `dsx-timeline__content-title`, `dsx-timeline__content-description`, and `dsx-timeline__content-time` for the typical title/body/time pattern, but the consumer is free to compose any children.
@@ -102,6 +96,8 @@ These three slots accept only `asChild` plus the standard HTML attribute surface
 
 - The component does not write `@media` rules. Responsive layout comes from the layout primitives' responsive classes when the consumer wraps the timeline in a responsive shell.
 
+- Items and content can shrink to the container; long identifiers wrap. Alternate tracks have a zero minimum so content cannot displace the centered marker rail. Error connectors use the same error token as their marker.
+
 **Reduced motion:**
 
 - The component is static. No motion is applied.
@@ -181,7 +177,7 @@ The component has no motion. It is a static read surface.
 
 **Variant story:**
 
-- Renders one `Timeline` with `variant="left"` and one with `variant="alternate"`. Asserts the `dsx-timeline--left` and `dsx-timeline--alternate` classes.
+- Renders one `Timeline` with `variant="left"` (deployment feed) and one with `variant="alternate"` (centered spine, three items covering odd/even parity). Asserts the `dsx-timeline--left` and `dsx-timeline--alternate` classes.
 
 **State story:**
 
@@ -193,7 +189,7 @@ The component has no motion. It is a static read surface.
 
 **Token story:**
 
-- Renders the default timeline inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the `data-accent-color` attribute is forwarded, but the active marker color tracks `--dsx-color-primary` and is not affected by the accent token.
+- Renders the default timeline inside a `Theme` wrapper with `accentColor="rift"` and `accentColor="warp"`. Asserts the `data-accent-color` attribute is forwarded, but the active marker color tracks `--dsx-color-primary` and is not affected by the accent token.
 
 **A11y story:**
 
@@ -211,6 +207,7 @@ The component has no motion. It is a static read surface.
 **Composes from:**
 
 - `@radix-ui/react-slot`: enables `asChild` on the root and on every named slot.
+- Stepper's vertical rail engine (CSS recipe only, no component dependency): Timeline reuses the dot-column centering calc, the marker-bottom anchor, and the size-aware offsets. The two components share geometry, never API or ARIA roles.
 
 **Used by:**
 
@@ -230,8 +227,8 @@ The component has no motion. It is a static read surface.
 
 1. **Content block layout collapsed; title, description, time rendered run-together.** The `.dsx-timeline__content` slot had no `display`, `flex-direction`, or `gap`, causing its children (the title `<span>`, description `<span>`, and time `<span>`, typically rendered bare by consumers) to render as inline siblings on a single line ("Project createdInitial scaffold2 hours ago"). FIXED 2026-07-03: added `display: flex; flex-direction: column; gap: var(--dsx-space-2xs);` to `.dsx-timeline__content`, plus `flex: 1; padding-bottom: var(--dsx-space-lg);` to preserve the item gap semantics and support the connector's absolute positioning.
 
-2. **Alternate variant had no CSS implementation; items never alternated.** The `variant="alternate"` prop def wrote the `dsx-timeline--alternate` modifier class on the root, but the CSS file contained no rules targeting that modifier — the layout was identical to the `left` variant. FIXED 2026-07-03: added per-item zigzag rules for the `alternate` variant: even-indexed items get `flex-direction: row-reverse` (marker on the right), `text-align: right` on content, and the connector repositioned from `left` to `right` with size-aware recalculation per `data-size` (sm/md/lg). This is a per-item flip, not a shared centered spine — the connector is item-local, not a continuous centerline. A future polish iteration may introduce a centered-column connector pattern.
+2. **Alternate variant had no CSS implementation; items never alternated.** The `variant="alternate"` prop def wrote the `dsx-timeline--alternate` modifier class on the root, but the CSS file contained no rules targeting that modifier — the layout was identical to the `left` variant. FIXED 2026-07-03: added per-item zigzag rules for the `alternate` variant: even-indexed items get `flex-direction: row-reverse` (marker on the right), `text-align: right` on content, and the connector repositioned from `left` to `right` with size-aware recalculation per `data-size` (sm/md/lg). REDESIGNED 2026-09-21 (F12 brief §4): replaced the per-item flip with a centered-spine recipe shared with Stepper's vertical rail engine — each item is a three-column flex row (half | marker | half) with the `::before` pseudo as the empty half, content split on parity (odd left, even right), and the connector on the item centerline. The flip is obsolete; the spine is the contract.
 
 3. **Connector appeared missing but was symptom of layout bug, not a separate defect.** The connector (an absolutely positioned vertical bar inside each item) appeared invisible or extremely short (~18px) in rendered demos. Investigation revealed the connector itself was present with correct background color and dimensions; the visual symptom was a side effect of the spacing bug (#1 above). When `.dsx-timeline__content` had no flex layout, its children ran together in ~20px of vertical space, making the item itself tiny, and the connector's absolute `top: marker-bottom; bottom: 0` was proportionally tiny too. Fixing the spacing bug (adding the flex column layout) expanded the item's natural height, and the connector automatically became visible. No separate CSS fix was needed for the connector; it was never the root cause.
 
-4. **Playground fixture uses invalid state values.** The registry fixture at `apps/playground/lib/registry/data.tsx` (Timeline entry, "Default" story) passes `state="complete"` and `state="pending"` to `TimelineItem`, but `timeline.props.ts`'s `timelineItemPropDefs.state` enum only allows `'default' | 'active' | 'error' | 'disabled'`. Invalid enum values silently fall through to the default modifier class (no visible error). This is a fixture-honesty gap (the fixture uses API values that the type definitions reject) and is deferred to the next promotion batch.
+4. **Playground fixture uses invalid state values.** The registry fixture at `apps/playground/lib/registry/data.tsx` (Timeline entry, "Default" story) passes `state="complete"` and `state="pending"` to `TimelineItem`, but `timeline.props.ts`'s `timelineItemPropDefs.state` enum only allows `'default' | 'active' | 'error' | 'disabled'`. Invalid enum values silently fall through to the default modifier class (no visible error). FIXED 2026-09-21: fixture rewritten with valid states only — a timestamped deployment feed (left rail), a three-item alternate story covering odd/even parity, an error + disabled story, and a token story over `rift`/`warp`/`ray`.

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

@@ -3,13 +3,6 @@ title: Toast
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/toast/Toast.tsx
-css_path: packages/d4gger-design-system/src/styles/components/toast.css
-props_path: packages/d4gger-design-system/src/components/toast/toast.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Toast.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/overlay.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - "@radix-ui/react-toast"
   - "@radix-ui/react-slot"
@@ -18,7 +11,7 @@ depends_on:
 
 # Toast
 
-> 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
 
@@ -73,7 +66,7 @@ The `Toast.Viewport` slot accepts the full `ComponentPropsWithoutRef<typeof Toas
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'default' \| 'destructive'` | `'default'` | no | Drives `data-variant` on the root. The CSS file consumes `data-variant='destructive'` to swap the background to the error container and the text to the on-error container. | no |
+| `variant` | `'default' \| 'success' \| 'warning' \| 'destructive' \| 'info'` | `'default'` | no | Drives `data-variant` on the root. Status variants swap the background to the matching container and the text to the on-container color. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Drives `data-size` on the root. The CSS file consumes `data-size` for token-driven sizing variants. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-toast`. | no |
 
@@ -109,7 +102,7 @@ The close also accepts the full `ComponentPropsWithoutRef<typeof ToastPrimitive.
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-variant` | `default`, `destructive` | `.dsx-toast[data-variant='destructive']`, `.dsx-toast-variant-destructive` | `toast.css` |
+| `data-variant` | `default`, `success`, `warning`, `destructive`, `info` | `.dsx-toast[data-variant='...']`, `.dsx-toast-variant-...` | `toast.css` |
 | `data-size` | `sm`, `md`, `lg` | `.dsx-toast[data-size='…']` | `toast.css` |
 | `data-state` (Radix) | `open`, `closed` | `.dsx-toast[data-state='open']` | `toast.css` |
 | `data-swipe-direction` (Radix) | `up`, `down`, `left`, `right` | (Radix) | `toast.css` |
@@ -181,7 +174,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Toast background | `var(--dsx-color-surface)` | Resting toast surface. |
 | Toast radius | `var(--dsx-rounded-md)` | Toast corner roundness. |
 | Toast border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Toast edge. |
-| Toast shadow | `var(--dsx-shadow-elevation-2)` | Toast elevation. |
+| Toast shadow | `var(--dsx-shadow-elevation-5)` | Spotlight: below dialogs, above all menus (B4 Q3). |
 | Destructive background | `var(--dsx-color-error-container)` | Destructive variant surface. |
 | Destructive border | `var(--dsx-color-error)` | Destructive variant edge. |
 | Destructive text | `var(--dsx-color-on-error-container)` | Destructive variant text. |

package/dist/docs/{toggle-group.md → components/toggle-group.md}

@@ -3,13 +3,6 @@ title: ToggleGroup
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/toggleGroup/ToggleGroup.tsx
-css_path: packages/d4gger-design-system/src/styles/components/toggle-group.css
-props_path: packages/d4gger-design-system/src/components/toggleGroup/toggleGroup.props.ts
-test_path: packages/d4gger-design-system/src/test/components/ToggleGroup.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:
   - "@radix-ui/react-toggle-group"
   - Toggle
@@ -17,11 +10,11 @@ depends_on:
 
 # ToggleGroup
 
-> 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 coordinated cluster of toggle buttons backed by `@radix-ui/react-toggle-group`. Items can run in single or multiple selection, share a single border with collapsed inner radii, and lift the focused child above its siblings. The component is the right fit for view selectors and formatting clusters; for single-select with a sliding indicator use `SegmentedControl` instead.
+A coordinated cluster of toggle buttons backed by `@radix-ui/react-toggle-group`. Items can run in single or multiple selection, share a single border with collapsed inner radii, and lift the focused child above its siblings. The component is the right fit for view selectors and formatting clusters; for single-select with a sliding indicator use `SegmentedControl` instead. Boundary rule (F6 brief): ToggleGroup is frameless toolbar buttons with no thumb and no container fill — the moment a design needs a sliding indicator, it is a SegmentedControl, not a styled ToggleGroup.
 
 ## Anatomy & slots
 
@@ -86,6 +79,7 @@ Rules:
 **Responsive behavior:**
 
 - The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size and variant are single-value only.
+- Narrow containers: the root caps at `max-width: 100%` with `overflow-x: auto` — the fused frame cannot wrap, so an over-wide group scrolls instead of hard-clipping its last item (proven 2026-09-23 in a definite 272px column: group caps at 272, full content reachable by touch scroll).
 
 **Reduced motion:**