@d4gger/design-system 2.7.0 → 3.0.1

package/dist/docs/{accessible-icon.md → components/accessible-icon.md}

@@ -3,19 +3,12 @@ title: AccessibleIcon
 status: canonical
 category: Primitives
 archetype: radix-wrapper
-package_path: packages/d4gger-design-system/src/components/accessibleIcon/AccessibleIcon.tsx
-css_path: packages/d4gger-design-system/src/components/accessibleIcon/AccessibleIcon.tsx
-props_path: packages/d4gger-design-system/src/components/accessibleIcon/accessibleIcon.props.ts
-test_path: packages/d4gger-design-system/src/test/components/AccessibleIcon.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: []
 ---
 
 # AccessibleIcon
 
-> 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/{accordion.md → components/accordion.md}

@@ -3,13 +3,6 @@ title: Accordion
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/accordion/Accordion.tsx
-css_path: packages/d4gger-design-system/src/styles/components/accordion.css
-props_path: packages/d4gger-design-system/src/components/accordion/accordion.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Accordion.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/navigation.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Collapsible
   - Icon
@@ -17,7 +10,7 @@ depends_on:
 
 # Accordion
 
-> 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/{alert-dialog.md → components/alert-dialog.md}

@@ -3,20 +3,13 @@ title: AlertDialog
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/alertDialog/AlertDialog.tsx
-css_path: packages/d4gger-design-system/src/styles/components/alert-dialog.css
-props_path: packages/d4gger-design-system/src/components/alertDialog/alertDialog.props.ts
-test_path: packages/d4gger-design-system/src/test/components/AlertDialog.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:
   - Dialog
 ---
 
 # AlertDialog
 
-> Source of truth: the package source at `package_path`. The spec 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
 
@@ -285,7 +278,7 @@ The content frame, overlay, and title typography mirror `Dialog`. The action and
 
 | Shape | Property | Token | Token type | Penpot property name |
 |---|---|---|---|---|
-| `<Content frame>` | fill | `var(--dsx-color-surface-overlay)` | Color | `fills` |
+| `<Content frame>` | fill | `var(--dsx-color-panel-translucent)` | Color | `fills` |
 | `<Content frame>` | radius | `var(--dsx-rounded-xl)` | Radius | `borderRadius` |
 | `<Action button (destructive)>` | fill | `var(--dsx-color-error)` | Color | `fills` |
 | `<Action button (destructive)>` | text fill | `var(--dsx-color-on-error)` | Color | `fills` |

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

@@ -3,13 +3,6 @@ title: Alert
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/alert/Alert.tsx
-css_path: packages/d4gger-design-system/src/styles/components/alert.css
-props_path: packages/d4gger-design-system/src/components/alert/alert.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Alert.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Card
   - Icon
@@ -18,7 +11,7 @@ depends_on:
 
 # Alert
 
-> 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/{article-nodes.md → components/article-nodes.md}

@@ -3,8 +3,6 @@ title: ArticleNodes
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/articleNodes/ArticleNodes.tsx
-css_path: packages/d4gger-design-system/src/styles/components/article-nodes.css
 depends_on: ["@tiptap/core", "@tiptap/extension-image", "@tiptap/extension-table", "@tiptap/extension-code-block-lowlight", "lowlight"]
 ---
 

package/dist/docs/{aspect-ratio.md → components/aspect-ratio.md}

@@ -3,19 +3,12 @@ title: AspectRatio
 status: canonical
 category: Primitives
 archetype: radix-wrapper
-package_path: packages/d4gger-design-system/src/components/aspectRatio/AspectRatio.tsx
-css_path: packages/d4gger-design-system/src/styles/components/aspect-ratio.css
-props_path: packages/d4gger-design-system/src/components/aspectRatio/aspectRatio.props.ts
-test_path: packages/d4gger-design-system/src/test/components/AspectRatio.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/layout.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # AspectRatio
 
-> 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/{avatar.md → components/avatar.md}

@@ -3,19 +3,12 @@ title: Avatar
 status: canonical
 category: Primitives
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/avatar/Avatar.tsx
-css_path: packages/d4gger-design-system/src/styles/components/avatar.css
-props_path: packages/d4gger-design-system/src/components/avatar/avatar.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Avatar.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Avatar
 
-> 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/{badge.md → components/badge.md}

@@ -3,19 +3,12 @@ title: Badge
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/badge/Badge.tsx
-css_path: packages/d4gger-design-system/src/styles/components/badge.css
-props_path: packages/d4gger-design-system/src/components/badge/badge.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Badge.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Badge
 
-> 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
 
@@ -33,7 +26,7 @@ No slots: flat export. The component renders a single `<span>` host element (or
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'default' \| 'primary' \| 'secondary' \| 'outline' \| 'success' \| 'error'` | `'default'` | no | Visual treatment; writes the `dsx-badge--{variant}` modifier class and `data-variant`. | no |
+| `variant` | `'default' \| 'primary' \| 'secondary' \| 'outline' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'default'` | no | Visual treatment; writes the `dsx-badge--{variant}` modifier class and `data-variant`. Status variants use container tints (directions-panel language). | no |
 | `size` | `'sm' \| 'md'` | `'md'` | no | Minimum height; writes the `dsx-badge--{size}` modifier class and `data-size`. | no |
 | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner roundness override; writes `data-radius`. The default uses `var(--dsx-rounded-full)` from the root class. | no |
 | `color` | `string` | `undefined` | no | Accent color; writes `data-accent-color`. The runtime accepts any string (the prop def has an empty enum). | no |
@@ -94,14 +87,14 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | `text-decoration` | `var(--dsx-typography-label-small-text-decoration)` | Underline treatment. |
 | Background (default) | `var(--dsx-color-surface-raised)` | Default surface. |
 | Text (default) | `var(--dsx-color-on-surface)` | Default label. |
-| Background (primary) | `var(--dsx-color-primary)` | Primary fill. |
-| Text (primary) | `var(--dsx-color-on-primary)` | Primary text. |
-| Background (secondary) | `var(--dsx-color-secondary)` | Secondary fill. |
-| Text (secondary) | `var(--dsx-color-on-secondary)` | Secondary text. |
-| Background (success) | `var(--dsx-color-success)` | Success fill. |
-| Text (success) | `var(--dsx-color-on-success)` | Success text. |
-| Background (error) | `var(--dsx-color-error)` | Error fill. |
-| Text (error) | `var(--dsx-color-on-error)` | Error text. |
+| Background (primary) | `var(--dsx-color-accent-track)` | Primary fill. |
+| Text (primary) | `var(--dsx-color-accent-contrast)` | Primary text. |
+| Background (secondary) | `var(--dsx-color-on-secondary-container)` dark / `var(--dsx-color-secondary-container)` light | Secondary — dark slate fill on dark, container tint on light. |
+| Text (secondary) | `var(--dsx-color-on-surface)` dark / `var(--dsx-color-on-secondary-container)` light | Secondary text. |
+| Background (success) | `var(--dsx-color-success-container)` | Success tint — the directions-panel language. |
+| Text (success) | `var(--dsx-color-on-success-container)` | Success text. |
+| Background (error) | `var(--dsx-color-error-container)` | Error tint — the directions-panel language. |
+| Text (error) | `var(--dsx-color-on-error-container)` | Error text. |
 | Background (outline) | `transparent` (CSS keyword) + `var(--dsx-color-outline)` border | Outline variant. |
 | High-contrast background (default, primary, secondary) | `var(--dsx-color-high-contrast)` | High-contrast fill. |
 | High-contrast text (default, primary, secondary) | `var(--dsx-color-on-high-contrast)` | High-contrast label. |

package/dist/docs/components/banner.md

@@ -0,0 +1,152 @@
+---
+title: Banner
+status: canonical
+category: Components
+archetype: composite
+depends_on:
+  - Text
+---
+
+# Banner
+
+Examples keep the headline value numeric and put units in Label or Footnote, preserving readable hero typography at narrow widths. Arbitrary consumer text still wraps within the surface.
+
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+
+## Purpose
+
+A hero mass: one label, one headline value, and an optional footnote over an accent wash or solid accent fill. A single mass by construction — it replaces Card-plus-StatCard nesting, which double-frames.
+
+## Anatomy & slots
+
+**Parent:** `Banner` (alias of `Banner.Root`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Banner.Root` | `<section>` | Hero surface + class | `role="group"`, consumer `aria-label`. Writes `dsx-banner`. Supports `asChild`. |
+| `Banner.Label` | `<span>` | Uppercase muted label + class | Renders `Text` label-small. Writes `dsx-banner__label`. |
+| `Banner.Value` | `<span>` | Headline value + class | Uses a span with the display-medium token ramp. Writes `dsx-banner__value`. |
+| `Banner.Footnote` | `<span>` | Muted footnote + class | Renders `Text` body-small. Writes `dsx-banner__footnote`. Optional. |
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `variant` | `'wash' \| 'fill'` | `'wash'` | no | Hero treatment; writes `data-variant`. `fill` is the solid-accent mass reusing Button primary's compliance (`accent-track` + `accent-contrast`). | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot`; consumer supplies the host element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-banner`. | no |
+
+Rules:
+
+- Slots take no props besides `asChild` and `className`; all copy is children.
+- `variant="wash"` is the default; `variant="fill"` uses accent-track and accent-contrast. There are no size or tone variants.
+- Long values, identifiers, and footnotes wrap within the available width; content is never silently truncated.
+
+## CSS class contract
+
+**Root class:** `dsx-banner`
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Banner.Root` | `dsx-banner` | `banner.css` |
+| `Banner.Label` | `dsx-banner__label` | `banner.css` |
+| `Banner.Value` | `dsx-banner__value` | `banner.css` |
+| `Banner.Footnote` | `dsx-banner__footnote` | `banner.css` |
+
+The enum PropDef emits `dsx-banner-variant-wash` / `dsx-banner-variant-fill`; the fill alias shares the data-variant paint rules.
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Root background | `var(--dsx-color-accent-surface)` | Hero wash (wash variant) |
+| Fill background | `var(--dsx-color-accent-track)` | Solid accent mass (fill variant) |
+| Fill text | `var(--dsx-color-accent-contrast)` | Compliant text on fill (near-black on spark, white elsewhere) |
+| Root radius | `var(--dsx-rounded-lg)` | Hero corner roundness |
+| Root padding | `var(--dsx-space-lg)` | Hero internal spacing |
+| Root gap | `var(--dsx-space-xs)` | Stack rhythm label/value/footnote |
+| Label typography | `var(--dsx-typography-label-small-*)` | Label type scale |
+| Label color | `var(--dsx-color-on-surface-variant)` | Muted label on wash |
+| Value typography | `var(--dsx-typography-display-medium-*)` | Headline value type scale |
+| Value color | `var(--dsx-color-on-surface)` | Value ink on wash |
+| Footnote typography | `var(--dsx-typography-body-small-*)` | Footnote type scale |
+| Footnote color | `var(--dsx-color-on-surface-variant)` | Muted footnote on wash |
+
+## Motion contract
+
+None — no transitions, no animation. Pressed/`focus-visible` states do not apply (non-interactive).
+
+## Accessibility
+
+**Roles:**
+
+- `group` (from `<section>` with consumer `aria-label`).
+
+**Naming:**
+
+- The Root must have an accessible name via `aria-label` when the hero purpose is not obvious from context.
+
+**Color and meaning:**
+
+- The wash is decorative; label/value text carries all meaning with `on-surface` contrast.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Banner` with Label + Value. Asserts the root class is `dsx-banner` and the host element is `SECTION`.
+
+**Footnote story:**
+
+- Renders with `Banner.Footnote`. Asserts `dsx-banner__footnote` is present.
+
+**Variant story:**
+
+- Renders with `variant="fill"`. Asserts `data-variant="fill"` and the fill background token.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the hero. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+`variant`: select (`wash`, `fill`), default `wash`.
+
+## Deliberate divergences (researched, 2026-10-02)
+
+Sibling-repo survey (Primer `Banner`/`PageHeader`/`Card`, Radix `Callout`/`Card`, Lobe docs-kit hero, NetBird `AnnouncementBanner`):
+
+- **No border, no leading icon.** Status banners pair their wash with a colored border + icon (Primer muted border, Radix accent ring). Banner is a hero mass, not an alert strip — the wash-vs-solid distinction alone carries the hierarchy. If an icon is ever needed, it becomes a new slot, not an ad-hoc child.
+- **Shared display-medium with StatCard.** Real heroes and stat cards share their value scale (Lobe h1 vs feature numbers differ by context, not by component); surface treatment — wash vs solid + shadow — is the differentiator, not type size.
+- **Padding kept symmetric with StatCard (`space-lg`).** Radix tightens Callout below Card; Banner keeps the roomier rhythm because hero values (45 days) run larger than list text. Revisit only with screenshot evidence.
+- **Name vs M2 Banner.** Material's Banner is a top-of-screen informational strip with acknowledgment actions — a different pattern. Ours is the marketing sense (hero banner). The spec's Purpose line is the disambiguator; do not reshape this component toward alert-strip behavior (that is `Callout`).
+
+## Wiring notes
+
+**Composes from:**
+
+- `Text`: Label (label-small) and Footnote (body-small). Value uses the display-medium token ramp directly.
+
+**Used by (planned):**
+
+- TMA user-console referral balance hero, home status hero (wash variant), subscription heroes — replacing Card-plus-StatCard nesting in each.
+
+**State boundaries:**
+
+- Owned by Banner: the wash surface, the label/value/footnote stack, the CSS classes.
+- Owned by the consumer: the copy, the `aria-label`, the surrounding page.
+
+**Boundary rules:**
+
+- App-owned data: copy, aria-label.
+- DS-owned visuals: wash, radius, padding, slot classes.

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

@@ -3,17 +3,12 @@ title: Blockquote
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/blockquote/Blockquote.tsx
-css_path: packages/d4gger-design-system/src/styles/components/blockquote.css
-props_path: packages/d4gger-design-system/src/components/blockquote/blockquote.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Blockquote.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on: []
 ---
 
 # Blockquote
 
-> 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
 
@@ -127,7 +122,7 @@ Rules:
 
 ## Playground demo spec
 
-The demo file at `demo_path` exposes the component to the playground. The playground lives at `apps/playground/app/` (Next.js app router, no per-component routes today). The `demo_path` recorded here is the current playground root; the spec assumes a single shared page that renders all components. Per-component routes are an aspirational target and not yet present in the repo.
+`Blockquote` is registered in `apps/playground/lib/registry/typography.tsx` under the `blockquote` key. The registry entry imports `blockquotePropDefs` and renders the component with a sample quotation. Per-component route: `/docs/blockquote`.
 
 **Default story:**
 
@@ -147,7 +142,7 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the default accent rule color tracks `data-accent-color` (it should resolve to the current `primary` token at runtime).
+- Renders inside a `Theme` wrapper with `accentColor="rift"`, `accentColor="warp"`, and `accentColor="ray"`. Asserts the default accent rule color tracks `data-accent-color` (it should resolve to the current `primary` token at runtime).
 
 **A11y story:**
 

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

@@ -3,20 +3,13 @@ title: Box
 status: canonical
 category: Foundations
 archetype: layout-primitive
-package_path: packages/d4gger-design-system/src/layout/Layout.tsx
 component_path: packages/d4gger-design-system/src/components/box/Box.tsx
-css_path: packages/d4gger-design-system/src/styles/components/box.css
-props_path: packages/d4gger-design-system/src/layout/layout.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Box.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/layout.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Box
 
-> Source of truth: the package source at `package_path`. The spec 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
 
@@ -48,7 +41,7 @@ No slots: flat export. `Box` is a single forwardRef that renders a host element
 | `pr` | `ResponsiveValue<SpaceToken \| string>` | `undefined` | no | Right padding. | yes (initial, sm, md, lg, xl, 2xl) |
 | `pb` | `ResponsiveValue<SpaceToken \| string>` | `undefined` | no | Bottom padding. | yes (initial, sm, md, lg, xl, 2xl) |
 | `pl` | `ResponsiveValue<SpaceToken \| string>` | `undefined` | no | Left padding. | yes (initial, sm, md, lg, xl, 2xl) |
-| `margin` | `ResponsiveValue<number \| string>` | `undefined` | no | All-sides margin. Resolves `--dsx-box-margin`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `margin` | `ResponsiveValue<number \| string>` | `undefined` | no | All-sides margin. Resolves `--dsx-box-margin` through `resolveSpace` (token values map to `var(--dsx-space-*)`); numeric values resolve to `px`. | yes (initial, sm, md, lg, xl, 2xl) |
 | `m` | `ResponsiveValue<SpaceToken \| string>` | `undefined` | no | All-sides margin. Resolves `--dsx-r-m`. | yes (initial, sm, md, lg, xl, 2xl) |
 | `mx` | `ResponsiveValue<SpaceToken \| string>` | `undefined` | no | Inline-axis margin. Resolves `--dsx-r-mx`. | yes (initial, sm, md, lg, xl, 2xl) |
 | `my` | `ResponsiveValue<SpaceToken \| string>` | `undefined` | no | Block-axis margin. Resolves `--dsx-r-my`. | yes (initial, sm, md, lg, xl, 2xl) |

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

@@ -3,13 +3,6 @@ title: Breadcrumb
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/breadcrumb/Breadcrumb.tsx
-css_path: packages/d4gger-design-system/src/styles/components/breadcrumb.css
-props_path: packages/d4gger-design-system/src/components/breadcrumb/breadcrumb.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Breadcrumb.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/navigation.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Link
   - Separator
@@ -17,7 +10,7 @@ depends_on:
 
 # Breadcrumb
 
-> Source of truth: the package source at `package_path`. The spec 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/{button-group.md → components/button-group.md}

@@ -3,20 +3,13 @@ title: ButtonGroup
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/buttonGroup/ButtonGroup.tsx
-css_path: packages/d4gger-design-system/src/styles/components/button-group.css
-props_path: packages/d4gger-design-system/src/components/buttonGroup/buttonGroup.props.ts
-test_path: packages/d4gger-design-system/src/test/components/ButtonGroup.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:
   - Button
 ---
 
 # ButtonGroup
 
-> 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
 
@@ -52,7 +45,7 @@ The root renders a `<div role="group">`. Children of the group share the first/l
 Rules:
 
 - `Omit<HTMLAttributes<HTMLDivElement>, ...>` is not applied; the type is a direct extension, so any `<div>` prop is forwarded.
-- The component does not own the buttons themselves. The consumer is responsible for sizing each `Button` to match the group's `size` token, and for keyboard semantics on every child.
+- The component does not own the buttons themselves. The group drives children min-height from its own `data-size`; the consumer remains responsible for keyboard semantics on every child.
 
 ## CSS class contract
 
@@ -62,7 +55,7 @@ Rules:
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-size` | `sm`, `md`, `lg` | `.dsx-button-group[data-size='sm'\|'md'\|'lg']` does not exist today; size is enforced by the children's own `data-size` hooks | `button-group.css` |
+| `data-size` | `sm`, `md`, `lg` | `.dsx-button-group[data-size='sm'\|'md'\|'lg'] > *` sets the matching density min-height token on every direct child, so the three sizes differ without consumer sizing | `button-group.css` |
 | (variant) | `default`, `outline` | `.dsx-button-group--default`, `.dsx-button-group--outline` | `button-group.css` |
 
 **Slot classes:**
@@ -76,6 +69,7 @@ Rules:
 
 - The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size and variant are single-value only.
 - The component's CSS file is breakpoint-agnostic.
+- 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 action (proven 2026-09-23 in a definite 272px column: group caps at 272, `scrollWidth` 298 reachable by touch scroll).
 
 **Reduced motion:**
 
@@ -101,7 +95,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 Rules:
 
-- The component does not paint its own background, border, or shadow. Visual treatment is delegated to the children, which means the group's appearance is fully driven by the `Button` variant chosen for each child.
+- The component paints no background, border, or shadow of its own. In `default`, children render borderless (`border-color: transparent`) for the fused cluster; in `outline`, children keep their own joined borders, which read as the container edge. Beyond that, visual treatment is delegated to the children.
 
 ## Motion contract
 

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

@@ -3,20 +3,13 @@ title: Button
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/button/Button.tsx
-css_path: packages/d4gger-design-system/src/styles/components/button.css
-props_path: packages/d4gger-design-system/src/components/button/button.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Button.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/actions.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Spinner
 ---
 
 # Button
 
-> 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
 
@@ -37,9 +30,10 @@ No slots: flat export. The component renders a single `<button>` host element (o
 | `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'destructive' \| 'outline'` | `'primary'` | no | Visual treatment; writes `data-variant`. | no |
 | `size` | `'sm' \| 'md' \| 'lg' \| 'icon'` | `'md'` | no | Height and padding scale; writes `data-size`. The `icon` size produces a square hit target with zero padding for icon-only buttons. | no |
 | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` | no | Corner roundness; writes `data-radius`. | no |
-| `color` | `'amber' \| 'silver' \| 'bronze' \| string` | `undefined` | no | Accent color; writes `data-accent-color`. Free-form strings are accepted. | no |
+| `color` | `'rift' \| 'warp' \| 'ray' \| string` | `undefined` | no | Accent color; writes `data-accent-color`. Free-form strings are accepted. | no |
 | `highContrast` | `boolean` | `false` | no | When `true`, swaps to the high-contrast palette; writes `data-high-contrast="true"`. | no |
 | `loading` | `boolean` | `false` | no | When `true`, swaps the visible content for a centered spinner and disables interaction. Writes `data-loading="true"` and `aria-busy="true"` through `BaseButton`. | no |
+| `halo` | `boolean` | `false` | no | Opt-in resting accent ring (`data-halo`). Default buttons have no halo; focus-visible ring is unaffected. | no |
 | `leadingIcon` | `React.ReactNode` | `undefined` | no | Optional leading icon element rendered before the label. | no |
 | `trailingIcon` | `React.ReactNode` | `undefined` | no | Optional trailing icon element rendered after the label. | no |
 | `asChild` | `boolean` | `false` | no | Renders the button through `Slot`; consumer supplies the host element. `type` is dropped in this mode. | no |
@@ -66,7 +60,8 @@ Rules:
 | `data-variant` | `primary`, `secondary`, `ghost`, `destructive`, `outline` | `.dsx-button:where([data-variant='primary'])` etc. | `button.css` |
 | `data-size` | `sm`, `md`, `lg`, `icon` | `.dsx-button[data-size='sm']` etc. | `button.css` |
 | `data-radius` | `none`, `sm`, `md`, `lg`, `full` | `.dsx-button[data-radius='none']` etc. | `button.css` |
-| `data-accent-color` | `amber`, `silver`, `bronze` (or any custom string) | `.dsx-button[data-accent-color='...']` (CSS hook) | `button.css` |
+| `data-accent-color` | `rift`, `warp`, `ray` (or any custom string) | `.dsx-button[data-accent-color='...']` (CSS hook) | `button.css` |
+| `data-halo` | `true` | Resting accent ring on every variant (`.dsx-button:where([data-variant='…'])[data-halo='true']`; hover/active keep it, no shadow morph without it) | `button.css` |
 | `data-high-contrast` | `true` | `.dsx-button:where([data-variant='primary'])[data-high-contrast='true']` etc. (variant-specific HC overrides) | `button.css` |
 | `data-loading` | `true` | `.dsx-button[data-loading='true']` | `button.css` (writes to cursor and spinner positioning) |
 | `data-disabled` | `true` | `.dsx-button[data-disabled='true']` | `button.css` |
@@ -114,18 +109,18 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | `text-decoration` | `var(--dsx-typography-label-large-text-decoration)` | Underline treatment. |
 | `transition` | `var(--dsx-motion-duration-fast, 150ms) var(--dsx-motion-easing-standard, ease)` | Animated state transitions. |
 | `cursor` | `var(--dsx-cursor-pointer, pointer)` (default), `var(--dsx-cursor-disabled, not-allowed)` (disabled), `var(--dsx-cursor-wait, wait)` (loading) | Pointer affordance. |
-| Background (primary) | `var(--dsx-accent-track)` | Primary fill. |
-| Text (primary) | `var(--dsx-accent-contrast)` | Primary text. |
-| Border (primary) | `var(--dsx-accent-track)` | Primary edge. |
-| Box shadow (primary) | `var(--dsx-shadow-gold-glow)` | Primary elevation. |
+| Background (primary) | `var(--dsx-color-accent-track)` | Primary fill (ramp step 9). |
+| Text (primary) | `var(--dsx-color-accent-contrast)` | Primary text. |
+| Border (primary) | `var(--dsx-color-accent-track)` | Primary edge. |
+| Box shadow (primary) | `var(--dsx-shadow-accent-ring)` | Resting halo — locked 2026-09-22 for every variant (was primary-only; settles the 2026-09-05 remove-halo proposal toward keep-and-extend). |
 | Box shadow (primary HC) | `var(--dsx-shadow-accent-glow)` | High-contrast primary elevation. |
-| Background (primary HC) | `var(--dsx-accent-indicator)` | High-contrast primary fill. |
+| Background (primary HC) | `var(--dsx-color-accent-indicator)` | High-contrast primary fill. |
 | Text (primary HC) | `var(--dsx-color-on-high-contrast)` | High-contrast primary text. |
-| Background (primary hover) | `linear-gradient(var(--dsx-effect-hover-primary), var(--dsx-effect-hover-primary)), var(--dsx-accent-track)` | Primary hover overlay. |
-| Box shadow (primary hover) | `var(--dsx-shadow-gold-glow-strong)` | Primary hover elevation. |
-| Background (primary pressed) | `linear-gradient(var(--dsx-effect-pressed-primary), var(--dsx-effect-pressed-primary)), var(--dsx-accent-track)` | Primary pressed overlay. |
+| Background (primary hover) | `var(--dsx-color-accent-10)` | Hover = ramp step 10. No overlay, no shadow change. |
+| Box shadow (primary hover) | `var(--dsx-shadow-accent-ring)` | Unchanged on hover. |
+| Background (primary pressed) | `linear-gradient(var(--dsx-effect-pressed-primary), var(--dsx-effect-pressed-primary)), var(--dsx-color-accent-track)` | Pressed overlay on the step-9 fill. |
 | Background (secondary) | `var(--dsx-color-secondary)` | Secondary fill. |
-| Text (secondary) | `var(--dsx-color-on-secondary)` | Secondary text. |
+| Text (secondary) | `var(--dsx-color-on-secondary)` light / `var(--dsx-color-on-surface)` dark | Secondary text — dark ink on light, surface-white on dark. |
 | Border (secondary) | `var(--dsx-color-secondary)` | Secondary edge. |
 | Background (secondary HC) | `var(--dsx-color-secondary-container)` | High-contrast secondary fill. |
 | Text (secondary HC) | `var(--dsx-color-on-secondary-container)` | High-contrast secondary text. |
@@ -145,8 +140,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Background (destructive) | `var(--dsx-color-error)` | Destructive fill. |
 | Text (destructive) | `var(--dsx-color-on-error)` | Destructive text. |
 | Border (destructive) | `var(--dsx-color-error)` | Destructive edge. |
-| Background (destructive hover) | `linear-gradient(var(--dsx-effect-hover-secondary), var(--dsx-effect-hover-secondary)), var(--dsx-color-error)` | Destructive hover overlay. |
-| Background (destructive pressed) | `linear-gradient(var(--dsx-effect-pressed-primary), var(--dsx-effect-pressed-primary)), var(--dsx-color-error)` | Destructive pressed overlay. |
+| Background (destructive hover) | `var(--dsx-color-error-10)` | Hover = the error ramp's step 10. |
+| Background (destructive pressed) | `color-mix(in srgb, var(--dsx-color-error-10), var(--dsx-color-error-11) 35%)` | Pressed = mixed toward the darker step 11. |
 | Focus ring | `var(--dsx-shadow-focus-ring)` | Visible focus ring on `:focus-visible`. |
 | Disabled background | `var(--dsx-color-disabled-surface)` | Disabled fill. |
 | Disabled text | `var(--dsx-color-disabled-text)` | Disabled label. |
@@ -163,8 +158,12 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 Rules:
 
-- No raw color, spacing, radius, or motion values in `button.css`.
-- The `radius` prop has the prop def default `'md'`, but the package's `button.css` declares `border-radius: var(--dsx-rounded-full)` on the root. Consumers who set `radius="md"` still get the rounded-full shape unless they target the `data-radius` attribute selectors that override the root.
+- No raw color, spacing, radius, or motion values in `button.css`. Ramp-step tokens
+  (`--dsx-color-accent-10`, `--dsx-color-error-10/11`) are the interaction model itself,
+  not primitive leakage.
+- The `radius` prop defaults to `'md'` and every render writes `data-radius`, so the
+  `data-radius='md'` selector (not the root `border-radius: rounded-full`) decides the
+  default shape.
 
 ## Motion contract