@d4gger/design-system 3.0.0 → 4.0.0

package/dist/docs/component-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "packageVersion": "3.0.0",
+  "packageVersion": "4.0.0",
   "generatedFrom": "docs/design-system",
   "components": [
     {
@@ -435,6 +435,22 @@
       "status": "canonical",
       "documentation": "./components/article-nodes.md"
     },
+    {
+      "name": "Banner",
+      "slug": "banner",
+      "category": "Components",
+      "archetype": "composite",
+      "status": "canonical",
+      "documentation": "./components/banner.md"
+    },
+    {
+      "name": "BottomDock",
+      "slug": "bottom-dock",
+      "category": "Components",
+      "archetype": "composite",
+      "status": "canonical",
+      "documentation": "./components/bottom-dock.md"
+    },
     {
       "name": "Breadcrumb",
       "slug": "breadcrumb",
@@ -563,14 +579,6 @@
       "status": "canonical",
       "documentation": "./components/context-menu.md"
     },
-    {
-      "name": "ControlGroup",
-      "slug": "control-group",
-      "category": "Components",
-      "archetype": "composite",
-      "status": "canonical",
-      "documentation": "./components/control-group.md"
-    },
     {
       "name": "CopyField",
       "slug": "copy-field",

package/dist/docs/components/accordion.md

@@ -107,7 +107,7 @@ Rules:
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. The motion and layout are single-value only.
+- The component does not use width breakpoints. The motion and layout are single-value only.
 
 **Reduced motion:**
 
@@ -132,7 +132,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Trigger color | `var(--dsx-color-on-surface)` | Closed trigger text |
 | Trigger padding | `var(--dsx-space-md)` | Internal gutter |
 | Trigger label type | `var(--dsx-typography-label-large-font-family)`, `var(--dsx-typography-label-large-font-size)` | Trigger text ramp |
-| Trigger open color | `var(--dsx-color-primary)` | Open trigger text |
+| Trigger open color | `var(--dsx-color-accent-indicator)` | Open trigger text |
 | Trigger focus ring | `var(--dsx-shadow-focus-ring)` | Focus indicator |
 | Chevron size | `var(--dsx-space-lg)` | Chevron icon size |
 | Chevron transition | `var(--dsx-motion-duration-fast) var(--dsx-motion-easing-in-out)` | Rotate transition |
@@ -183,42 +183,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 - `Accordion.Trigger` is the interactive element; the consumer's `children` become the button's accessible name. `Accordion.Header` should be associated with its `Content` via Radix's pairing, not via consumer-supplied `aria-*` attributes.
 
-## Playground demo spec
-
-**Default story:**
-
-- Renders `Accordion` with `type="single"`, `collapsible`, and two items. Asserts the root class is `dsx-accordion` and triggers render with the chevron icon.
-
-**State story:**
-
-- Renders with `type="single"`, `defaultValue="item-1"`. Asserts the open trigger carries `data-state="open"` and the open content is visible.
-- Renders with `type="multiple"`, `defaultValue={["item-1", "item-2"]}`. Asserts both items expand at once.
-
-**Disabled story:**
-
-- Renders the root with `disabled`. Asserts every trigger is disabled and `useAccordionStyles()` reports `disabled: true` to descendants.
-
-**Composition story:**
+The live example groups project questions with single-open behavior, separate multiple-open disclosures and a disabled item. Warp and ray examples start expanded so accent-indicator text and chevrons are visible; no global alpha/token values change.
 
-- Renders the default trigger and asserts exactly one built-in indicator.
-- Renders `indicator={false}` and a custom indicator node to demonstrate the supported ownership choices.
-- Compatibility tests keep `Accordion.ItemBody` and `Accordion.ItemIndicator` available without presenting them as the canonical composition.
-
-**Token story:**
-
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Accordion does not track `data-accent-color`; the story asserts the open trigger color continues to resolve through `var(--dsx-color-primary)`.
-
-**A11y story:**
-
-- Uses `vitest-axe` against the rendered default story. Asserts no axe violations.
-
-**Props exposed in the playground controls:**
+## Playground demo spec
 
-| Prop | Control | Default |
-|---|---|---|
-| `type` | select | `single` |
-| `collapsible` | boolean | `true` |
-| `disabled` | boolean | `false` |
+The matrix presents a working two-item single-open accordion. The live example has a project-question accordion (one initially open, one closed, one disabled), a multiple-open example with a no-indicator trigger, and warp/ray disclosures initialized open. Open labels and chevrons consume accent-indicator. Keyboard and pointer actions change aria-expanded and reveal the corresponding content.
 
 ## Wiring notes
 

package/dist/docs/components/alert.md

@@ -4,7 +4,6 @@ status: canonical
 category: Components
 archetype: composite
 depends_on:
-  - Card
   - Icon
   - Button
 ---
@@ -19,13 +18,13 @@ An inline status, warning, or info banner that lives in the page flow. Use Alert
 
 ## Anatomy & slots
 
-**Parent:** `Alert` (alias of `AlertRoot`). The root is a thin wrapper around `CardRoot`; it composes the card surface and adds the alert-specific layout, icon, and content slots.
+**Parent:** `Alert` (alias of `AlertRoot`). The root owns a static status surface, using the existing shared card surface tokens without a clickable Card host. Icon, content and actions retain their named slots. With `asChild`, one consumer element becomes the host and its children are wrapped in the content slot; icon and forwarded ref remain on that same host.
 
 **Slots:**
 
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
-| `Alert` (root) | `<div>` (or `Slot` host) | `CardRoot` + class | Renders the surface as a Card and overlays the alert-specific class. Writes `dsx-alert`, `data-variant`, `data-size`, `data-high-contrast`, `data-accent-color`. Defaults `role` to `"alert"`; consumers can override with a custom `role` prop. |
+| `Alert` (root) | `<div>` (or `Slot` host) | Static surface + class | Writes `dsx-alert`, `data-variant`, `data-size`, `data-high-contrast`, `data-accent-color`. Defaults `role` to `"alert"`; consumers can override with a custom `role` prop. Hovering the status surface does not change its semantic color or elevation. |
 | `Alert.Title` | `<h5>` (or `Slot` host) | Slot class | Title text. Writes `dsx-alert__title`. |
 | `Alert.Description` | `<p>` (or `Slot` host) | Slot class | Description text. Writes `dsx-alert__description`. |
 | `Alert.Action` | `<div>` | Slot class | Trailing action container (typically a Button or IconButton). Writes `dsx-alert__action`. |
@@ -46,7 +45,7 @@ The `Alert.Action` slot is independent of the rest of the layout; the consumer c
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `variant` | `'default' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | no | Visual tone; writes `data-variant`. The base CSS sets a color per variant; `default` and `warning` use the primary palette, `destructive` uses the error palette, and `success` uses the success palette. | no |
+| `variant` | `'default' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | no | Visual tone; writes `data-variant`. The base CSS sets a color per variant; `default` uses the primary palette and `warning` uses the warning palette, `destructive` uses the error palette, and `success` uses the success palette. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Padding scale; writes `data-size`. | no |
 | `color` | `string` | `undefined` | no | Free-form accent override; writes `data-accent-color` when provided. | no |
 | `highContrast` | `boolean` | `false` | no | When `true`, swaps the surface and border to `var(--dsx-color-high-contrast-container)` and `var(--dsx-color-high-contrast-border)`; writes `data-high-contrast="true"`. | no |
@@ -77,14 +76,14 @@ The icon is rendered with `size="md"` and `strokeWidth="var(--dsx-icon-stroke-wi
 
 ## CSS class contract
 
-**Root class:** `dsx-alert` (composed on top of the Card root class)
+**Root class:** `dsx-alert` (static native or Slot host; no interactive Card class)
 
 **Modifier classes** (driven by `data-*` attributes written by the component):
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | `data-variant` | `default`, `destructive`, `success`, `warning` | `.dsx-alert[data-variant='destructive']`, `.dsx-alert[data-variant='error']`, `.dsx-alert[data-variant='success']`, `.dsx-alert[data-variant='warning']` | `baseCard.css` |
-| `data-size` | `sm`, `md`, `lg` | (inherits Card size) | `baseCard.css` |
+| `data-size` | `sm`, `md`, `lg` | `.dsx-alert[data-size=…]` | `alert.css` |
 | `data-accent-color` | any string | (no rule in `alert.css`; attribute is forwarded) | n/a |
 | `data-high-contrast` | `true` | `.dsx-alert[data-high-contrast='true']` | `baseCard.css` |
 
@@ -126,7 +125,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Description opacity | `var(--dsx-opacity-subtle, 0.85)` | Subtle fade for description text |
 | Destructive surface | `var(--dsx-color-error-container)`, `var(--dsx-color-on-error-container)`, `var(--dsx-color-error)` (border) | Destructive palette |
 | Success surface | `var(--dsx-color-success-container)`, `var(--dsx-color-on-success-container)`, `var(--dsx-color-success)` (border) | Success palette |
-| Warning surface | `var(--dsx-color-primary-container)`, `var(--dsx-color-on-primary-container)`, `var(--dsx-color-primary)` (border) | Warning palette (primary palette) |
+| Warning surface | `var(--dsx-color-warning-container)`, `var(--dsx-color-on-warning-container)`, `var(--dsx-color-warning)` (border) | Warning palette |
 | High-contrast surface | `var(--dsx-color-high-contrast-container)`, `var(--dsx-color-high-contrast-border)`, `var(--dsx-color-high-contrast)` (text) | High-contrast palette |
 
 ## Motion contract
@@ -159,7 +158,7 @@ The component has no motion. It is a static inline surface.
 
 **Color and meaning:**
 
-- Variant tone is communicated by both color and icon: `success` uses the success palette and a `check-circle` icon, `destructive` uses the error palette and an `alert-triangle` icon, `warning` uses the primary palette and an `alert-triangle` icon, and `default` uses the base palette and an `info` icon.
+- Variant tone is communicated by both color and icon: `success` uses the success palette and a `check-circle` icon, `destructive` uses the error palette and an `alert-triangle` icon, `warning` uses the warning palette and an `alert-triangle` icon, and `default` uses the base palette and an `info` icon.
 
 **Naming:**
 
@@ -191,7 +190,7 @@ The component has no motion. It is a static inline surface.
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Asserts the destructive and success surfaces are unchanged because they read from the error and success palettes, not the accent palette.
+- Renders inside a `Theme` wrapper with `accentColor="astral"` and `accentColor="spark"`. Asserts the destructive and success surfaces are unchanged because they read from the error and success palettes, not the accent palette.
 
 **A11y story:**
 
@@ -210,7 +209,7 @@ The component has no motion. It is a static inline surface.
 
 **Composes from:**
 
-- `Card` (`CardRoot`): the alert root is a `CardRoot asChild` wrapper. The alert inherits the card surface treatment and the Card size, variant, and high-contrast data attributes.
+- `baseCard.css`: supplies the existing static Alert surface, semantic status palettes and high-contrast treatment. The root does not participate in interactive Card hover styling.
 - `Icon`: renders the variant default icon and any consumer-supplied icon node.
 - `@radix-ui/react-slot`: enables `asChild` on the root and on `Alert.Title` / `Alert.Description`.
 
@@ -227,3 +226,11 @@ The component has no motion. It is a static inline surface.
 
 - App-owned data: the alert message text, the action, the dismiss/timeout behavior, and the analytics events.
 - DS-owned visuals: token bindings, slot classes, icon name resolution, and the surface palette per variant.
+
+## Overlay review composition
+
+Content has min-width=0 and wraps long copy; the optional icon does not shrink.
+Actions wrap and align to the content start. Light-mode semantic borders retain
+warning/success/error roles after the shared card base rules. Default accent
+styling and highContrast remain token-driven. `/docs/alert` demonstrates all
+four tones, reconnect feedback and dismiss/restore through real actions.

package/dist/docs/components/article-nodes.md

@@ -3,7 +3,7 @@ title: ArticleNodes
 status: canonical
 category: Components
 archetype: adapter-backed
-depends_on: ["@tiptap/core", "@tiptap/extension-image", "@tiptap/extension-table", "@tiptap/extension-code-block-lowlight", "lowlight"]
+depends_on: ["@tiptap/core", "@tiptap/react", "@tiptap/extension-image", "@tiptap/extension-table", "@tiptap/extension-code-block-lowlight", "lowlight"]
 ---
 
 # ArticleNodes
@@ -22,6 +22,63 @@ The package exports `ArticleImage`, `ArticleEmbed`, `BeforeAfterComparison`, and
 
 Read-side renderers are available from the root and `components` barrels and from the dedicated `@d4gger/design-system/article-nodes` subpath. Tiptap-backed authoring extensions are isolated at `@d4gger/design-system/article-extensions`, so importing the root package never requires the optional Tiptap peers.
 
+## Read renderer contracts
+
+- `ArticleImage` accepts native image attributes and optional React-node `caption`.
+  Its root is a figure; `className` and native attributes belong to the image.
+  Alt defaults to an empty string. A supplied caption renders as figcaption.
+- `ArticleEmbed` accepts `url`, optional `isAllowed(canonicalUrl)` and optional
+  `render(canonicalUrl)`, plus native div attributes. Only absolute HTTP(S) URLs
+  survive canonicalization. Rejected URLs render `Embed unavailable` with role
+  alert; no render callback or link is emitted. Without a render callback an
+  allowed URL is a native anchor. The allowed root carries `data-dsx-url`.
+- `BeforeAfterComparison` accepts both sources and alt values, optional React-node
+  labels (defaults `Before`/`After`) and native figure attributes. It is a two-column
+  comparison, not an interactive slider. Images scale within zero-minimum tracks;
+  the minimum child width and scroll container preserve reachability in very tight hosts.
+- `ArticlePoll` accepts a persistent `pollId`, optional question/options and
+  controlled `state` (`loading`, `ready`, `error`, `voted`, `closed`; default `ready`).
+  `onLoad(pollId)` runs on mount and when the ID or callback changes.
+  `onVote(pollId, optionId)` runs only through enabled ready-state options.
+  Vote totals are optional display metadata, not package-owned tally state.
+  Loading sets `aria-busy`; error renders an alert; loading/closed options are disabled; legacy voted options are disabled. Controlled selection permits vote changes.
+
+## Paint and accessibility
+
+Media retain figure/caption semantics and consumer-supplied alt text. Embed/poll
+shells use raised surface, semantic outline, medium radius/padding and small gaps.
+Long labels and URLs wrap. Poll options compose the existing outline Button at
+large size through `dsx-article-poll__option`; Button owns keyboard activation,
+focus, disabled paint and target dimensions (44px at comfortable density).
+No renderer introduces component breakpoints, portal behavior or motion.
+
 ## Playground demo spec
 
-Show each renderer, missing media, invalid embed, comparison at mobile width, and poll loading, error, ready, and voted states.
+`/docs/article-nodes` composes `blocks-examples.tsx` through the display registry:
+local loaded image/caption, distinct extra-relay/direct-route comparison, a
+consumer-rendered link preview, invalid/disallowed embeds, an app-owned unavailable
+media Callout and poll loading/error/ready/voted states. The ready poll updates its
+results and can reset. The app fallback example does not add a package image-error API.
+
+## Authoring enhancement — approved 2026-10-04
+
+The optional article extension bundle supplies editable React node views for
+image/caption, embed, comparison, callout and poll, plus video, material reference
+and platform tabs. Block controls are visible on touch: edit, move up/down and
+remove; inline fields update node attributes. Block mutation controls track editor editability, and mutation callbacks guard
+read-only state. Node-view UI is absent from saved HTML. `createArticleExtensions({ editable: false })` disables authoring node views.
+Inline variables/mentions remain opt-in editor extensions, outside article policy.
+
+Media retain optional `mediaId` alongside consumer-resolved `src`. Apps own URL
+refresh, uploads, allowlists and conversion into versioned backend documents.
+Poll nodes retain `pollId`, `question`, stable option `id`/`label` records and
+`multiple`. Apps supply IDs at insertion. Platform tabs contain editable block
+content and a `platform` key, and preserve that structure in HTML/JSON.
+
+Read exports add `ArticleVideo`, `ArticlePlatformTabs` and `ArticleMaterialLink`.
+Video uses native controls and optional caption; tabs accept keyed content and
+controlled selection; references expose an explicit unavailable state without a
+resolved href. `ArticlePoll` adds controlled `selection`, `multiple`,
+`onSelectionChange`, `onSubmit`, `onRetract`, optional `totalVotes` and closed state.
+It displays supplied results before/after voting and supports change/retract. The
+existing `onVote` immediate single-choice path remains the default.

package/dist/docs/components/aspect-ratio.md

@@ -103,34 +103,11 @@ Rules:
 
 - No accessible name is required by default. Consumers that constrain focusable media (video, iframe) should supply an `aria-label` on the inner element or a labelled wrapper.
 
-## Playground demo spec
-
-**Default story:**
-
-- Renders `AspectRatio` with `ratio={16 / 9}` and a fixed width, so the height is computed automatically. Asserts the root class is `dsx-aspect-ratio`.
-
-**Composition story** (for `asChild`):
-
-- Renders AspectRatio with `asChild` wrapping a `<div>` element. Asserts the host element is `DIV` and the `dsx-aspect-ratio` class is preserved.
-
-**State story:**
-
-- Renders AspectRatio with `ratio={1}`, `ratio={4 / 3}`, and `ratio={16 / 9}`. Asserts the rendered height matches the width divided by the supplied ratio.
+The live example shows the same inline SVG landscape cropped at 16:9, 1:1 and 4:3. All three frames have equal widths within the same row; the gallery stacks on narrow screens.
 
-**Token story:**
-
-- N/A. AspectRatio does not consume `data-accent-color`; the story documents that the rounded corner is token-driven and visually unchanged across accents.
-
-**A11y story:**
-
-- Uses `vitest-axe` against the rendered default aspect ratio. Asserts there are no axe violations.
-
-**Props exposed in the playground controls:**
+## Playground demo spec
 
-| Prop | Control | Default |
-|---|---|---|
-| `asChild` | boolean | `false` |
-| `ratio` | number | `1` |
+The ratio matrix and live example use the same SVG landscape with cover cropping. The live gallery uses equal track widths for 16:9, 1:1 and 4:3, stacks at narrow widths, and labels each media use. Width is owned by the parent frame, never the inner Radix height box.
 
 ## Wiring notes
 

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>` | Compact normal-case label + class | Renders `Text` label-small; the Banner slot owns the paired container ink. 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>` | Compact footnote + class | Renders `Text` body-small with paired container ink. 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-primary-container)` | Opaque soft accent container (wash variant); no additional alpha dilution. |
+| 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-primary-container)` | Paired label ink on wash |
+| Value typography | `var(--dsx-typography-display-medium-*)` | Headline value type scale |
+| Value color | `var(--dsx-color-on-primary-container)` | Paired value ink on wash |
+| Footnote typography | `var(--dsx-typography-body-small-*)` | Footnote type scale |
+| Footnote color | `var(--dsx-color-on-primary-container)` | Paired footnote ink 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 the paired `on-primary-container` contrast. Typography distinguishes label, value and footnote without reducing their color 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/components/blockquote.md

@@ -12,7 +12,7 @@ depends_on: []
 
 ## Purpose
 
-A styled block quotation surface that renders a `<blockquote>` element with token-aligned typography, a left accent rule, and three tone variants for default, muted, and inverse contexts.
+A styled block quotation surface that renders a `<blockquote>` element with token-aligned typography, a 1px logical-start accent rule, and three tone variants for default, muted, and inverse contexts.
 
 ## Anatomy & slots
 
@@ -65,10 +65,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Property | Token | Role |
 |---|---|---|
-| Padding (left) | `var(--dsx-space-lg)` | Inset gutter for the accent rule. |
-| Border (left, default) | `var(--dsx-border-width-xl)` + `var(--dsx-color-primary)` | Default accent rule. |
-| Border (left, muted) | `var(--dsx-color-outline-variant)` | Muted accent rule. |
-| Border (left, inverse) | `var(--dsx-color-on-inverse-background)` | Inverse-context accent rule. |
+| Padding (inline start) | `var(--dsx-space-lg)` | Inset gutter for the accent rule. |
+| Border (inline start, default) | `var(--dsx-boundary-divider-width)` + `var(--dsx-color-accent-border)` | Default accent rule. |
+| Border (inline start, muted) | `var(--dsx-color-outline-variant)` | Muted accent rule. |
+| Border (inline start, inverse) | `var(--dsx-color-on-inverse-background)` | Inverse-context accent rule. |
 | Font family | `var(--dsx-typography-body-large-font-family)`, sans-serif fallback | Body type ramp. |
 | Font size | `var(--dsx-typography-body-large-font-size)` | Body type ramp. |
 | Line height | `var(--dsx-typography-body-large-line-height)` | Body type ramp. |
@@ -79,6 +79,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 Rules:
 
 - The accent rule and the text color are the only painted values; both come from tokens.
+- The default rule consumes the decorative accent-border role: step 8 in light appearance and step 11 in dark appearance. It is a 1px border on Blockquote itself, not a nested Separator. The muted rule remains a neutral outline-variant.
 - Tokens come from `DESIGN.md` and the generated `tokens.css`. The `body-large` typography token set is the only ramp Blockquote consumes.
 - Font style is hard-coded to `italic` in CSS; this is a visual convention, not a token, and is not overridable through a prop.
 
@@ -142,7 +143,7 @@ Rules:
 
 **Token story:**
 
-- 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).
+- Renders inside a `Theme` wrapper with all five accents (rift, warp, ray, astral and spark). Asserts the default accent rule color tracks `data-accent-color` (it should resolve to the current `accent-border` token at runtime).
 
 **A11y story:**
 
@@ -169,13 +170,13 @@ Rules:
 
 **State boundaries:**
 
-- Owned by Blockquote: the root class, the tone modifier class, the typography and color tokens, and the left accent rule.
+- Owned by Blockquote: the root class, the tone modifier class, the typography and color tokens, and the 1px logical-start accent rule.
 - Owned by the consumer: the quotation body, the optional `cite` URL, and the host element when `asChild` is set.
 
 **Boundary rules:**
 
 - App-owned data: the source attribution, the optional author display name, the surrounding prose context, and the host element when `asChild` is set.
-- DS-owned visuals: token bindings (`--dsx-space-lg`, `--dsx-border-width-xl`, `--dsx-color-primary`, `--dsx-color-outline-variant`, `--dsx-color-on-inverse-background`, `--dsx-color-on-surface-variant`, `--dsx-typography-body-large-*`), the `dsx-blockquote` root class, and the `dsx-blockquote--{tone}` modifier classes.
+- DS-owned visuals: token bindings (`--dsx-space-lg`, `--dsx-boundary-divider-width`, `--dsx-color-accent-border`, `--dsx-color-outline-variant`, `--dsx-color-on-inverse-background`, `--dsx-color-on-surface-variant`, `--dsx-typography-body-large-*`), the `dsx-blockquote` root class, and the `dsx-blockquote--{tone}` modifier classes.
 
 ## Penpot build recipe
 
@@ -201,20 +202,20 @@ The package does not yet publish a Penpot asset for Blockquote. Recipe is visual
 
 | Shape | Property | Token | Token type | Penpot property name |
 |---|---|---|---|---|
-| Root | stroke (left) | `--dsx-color-primary` | Color | `strokes` |
+| Root | stroke (logical start) | `--dsx-color-accent-border` | Color | `strokes` |
 | Root | padding (start) | `--dsx-space-lg` | Spacing | `padding` |
 | Root | typography | `--dsx-typography-body-large-*` | Typography | `typography` |
-| Root (muted) | stroke (left) | `--dsx-color-outline-variant` | Color | `strokes` (state) |
-| Root (inverse) | stroke (left) | `--dsx-color-on-inverse-background` | Color | `strokes` (state) |
+| Root (muted) | stroke (logical start) | `--dsx-color-outline-variant` | Color | `strokes` (state) |
+| Root (inverse) | stroke (logical start) | `--dsx-color-on-inverse-background` | Color | `strokes` (state) |
 | Root (inverse) | text fill | `--dsx-color-on-inverse-background` | Color | `fills` (state) |
 
 ### State transformations
 
 | State | Root stroke | Text fill | Border width |
 |---|---|---|---|
-| `default` | `--dsx-color-primary` | `--dsx-color-on-surface-variant` | `--dsx-border-width-xl` |
-| `muted` | `--dsx-color-outline-variant` | `--dsx-color-on-surface-variant` | `--dsx-border-width-xl` |
-| `inverse` | `--dsx-color-on-inverse-background` | `--dsx-color-on-inverse-background` | `--dsx-border-width-xl` |
+| `default` | `--dsx-color-accent-border` | `--dsx-color-on-surface-variant` | `--dsx-boundary-divider-width` |
+| `muted` | `--dsx-color-outline-variant` | `--dsx-color-on-surface-variant` | `--dsx-boundary-divider-width` |
+| `inverse` | `--dsx-color-on-inverse-background` | `--dsx-color-on-inverse-background` | `--dsx-boundary-divider-width` |
 
 ### Variant model