@d4gger/design-system 3.0.1 → 4.0.1

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,26 +18,29 @@ 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`. |
+| `Alert.Action` | `<div>` | Slot class | Trailing action container (typically a Button or IconButton). Writes `dsx-alert__action`. A direct child of `Alert` is hoisted out of the content container into one `dsx-alert__actions` group: the group trails the row, and wraps below the text as a whole, under the text, when the alert is narrow. |
 
 **Internal layout:**
 
-The root renders a flex row with three regions, in this order:
+The root renders a flex row of two columns, in this order:
 
 1. An icon container (`<span aria-hidden="true" class="dsx-alert__icon">`) that holds the resolved icon. The icon is hidden when `icon === null` and replaced wholesale when `icon` is a `ReactNode`.
-2. A content container (`<div class="dsx-alert__content">`) that wraps whatever the consumer passes as children (typically `Alert.Title` and `Alert.Description`).
-3. The optional `Alert.Action` slot, if the consumer composes it as a child.
+2. A main column (`<div class="dsx-alert__main">`), a wrapping flex row, that holds:
+   1. a content container (`<div class="dsx-alert__content">`) that wraps whatever the consumer passes as children (typically `Alert.Title` and `Alert.Description`);
+   2. when there is at least one direct-child `Alert.Action`, one actions group (`<div class="dsx-alert__actions">`) that holds each of them, in order.
 
-The `Alert.Action` slot is independent of the rest of the layout; the consumer can place it inside the content area or as a sibling of `Alert.Title` / `Alert.Description` to control alignment.
+A direct-child `Alert.Action` is hoisted out of the content container (`Alert.Title` and `Alert.Description` stay inside it), also when the root is an `asChild` host. The group trails the row (the content grows to push it to the end). Only the main column wraps (`flex-wrap`), so when the text would fall under its readable width the group drops below it as a whole and starts at the text column, under the text and not under the icon; the actions never split across rows. The group has no auto margin, because that would push a wrapped group to the far edge. An action the consumer nests in their own wrapper is not hoisted and stays in the content container. (G-15, 2026-10-05.)
+
+With a trailing action, the icon, the first line of text and the action share one centre at any width: all three get a control-height row (`var(--dsx-size-lg)`), and the first line's box is that tall (`::first-line`). An alert without an action is laid out as before.
 
 ## Props contract
 
@@ -46,7 +48,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 |
@@ -64,6 +66,12 @@ The `Alert.Action` slot is independent of the rest of the layout; the consumer c
 
 `Alert.Title` and `Alert.Description` also accept the standard HTML attributes for their host elements (`<h5>` and `<p>` respectively). `Alert.Action` accepts standard `<div>` attributes.
 
+**`Alert.Description` own prop:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `lineClamp` | `number` | `undefined` | no | Clamp the text to this many lines; the rest is clipped with an ellipsis. Only a whole number of 1 or more clamps; anything else (0, a negative, a fraction, `NaN`) leaves the text unclamped. Writes `data-line-clamp` and the custom property `--dsx-alert-line-clamp` on the description (a consumer `style` is kept); the prop name itself is not written to the DOM. Whether the text is clipped, and how to reveal it, is the consumer's: measure the element (`scrollHeight > clientHeight`) and drop the prop to show everything. | no |
+
 **Variant default icons (when `icon` is `undefined`):**
 
 | `variant` | Icon `name` |
@@ -77,16 +85,17 @@ 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` |
+| `data-line-clamp` (on `Alert.Description`) | a whole number of 1 or more | `.dsx-alert__description[data-line-clamp]` | `alert.css` |
 
 **Slot classes:**
 
@@ -94,14 +103,16 @@ The icon is rendered with `size="md"` and `strokeWidth="var(--dsx-icon-stroke-wi
 |---|---|---|
 | `Alert` (root) | `dsx-alert` | `alert.css` |
 | Root icon container | `dsx-alert__icon` | `alert.css` |
+| Root main column (content and actions) | `dsx-alert__main` | `alert.css` |
 | Root content container | `dsx-alert__content` | `alert.css` |
+| Root actions group | `dsx-alert__actions` | `alert.css` |
 | `Alert.Action` | `dsx-alert__action` | `alert.css` |
 | `Alert.Title` | `dsx-alert__title` | `alert.css` |
 | `Alert.Description` | `dsx-alert__description` | `alert.css` |
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. `size`, `variant`, `color`, and `highContrast` are single-value only.
+- The component does not write `@media` rules. `size`, `variant`, `color`, and `highContrast` are single-value only. The action wrap is intrinsic (`flex-wrap` on the main column), not a breakpoint, so it follows the alert's own width, not the window's.
 
 **Reduced motion:**
 
@@ -121,12 +132,16 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Root text color | `var(--dsx-color-on-surface)` | Default text color |
 | Icon / action minimum size | `var(--dsx-size-md)` | Icon and action slot dimensions |
 | Icon / action color | `currentColor` | Inherits the alert surface color |
+| Content basis | `min(calc(var(--dsx-size-xl) * 5), calc(100% - var(--dsx-size-md) - var(--dsx-space-md)))` | The readable width the text keeps before a trailing action wraps below it; the `min()` stops it forcing the text under the icon in a very narrow alert |
+| Control row (with an action) | `var(--dsx-size-lg)` | Min height of the icon and action, and the line box of the first line, so the three share a centre |
+| Clamped first line (with an action) | `padding-block-start: calc((var(--dsx-size-lg) - 1lh) / 2)` | `::first-line` cannot reach into the `-webkit-box` a clamped description is, so the first line is centred on the control row with padding instead |
+| Line clamp | `--dsx-alert-line-clamp` (written by the component from `lineClamp`) | The number of lines the description keeps; read by `-webkit-line-clamp` |
 | Title type ramp | `var(--dsx-typography-label-large-*)` | Title text scale |
 | Description type ramp | `var(--dsx-typography-body-medium-*)` | Description text scale |
 | 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 +174,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:**
 
@@ -187,11 +202,15 @@ The component has no motion. It is a static inline surface.
 
 **Composition story:**
 
-- Renders an alert with `Alert.Title`, `Alert.Description`, and `Alert.Action` populated. Asserts the `dsx-alert__title`, `dsx-alert__description`, and `dsx-alert__action` classes are present.
+- Renders an alert with `Alert.Title`, `Alert.Description`, and `Alert.Action` populated. Asserts the `dsx-alert__title`, `dsx-alert__description`, and `dsx-alert__action` classes are present, and that the action sits in the one `dsx-alert__actions` group after the content container inside `dsx-alert__main`, not inside the content (several actions share the one group). `src/test/styles/alert-wrap-layout.test.ts` guards the rules that make the group wrap as a whole under the text column. A second composition nests the action in the consumer's own wrapper and asserts it stays in the content.
+
+**Clamp story:**
+
+- Renders an alert whose `Alert.Description` has `lineClamp={2}` and a long text, with a trailing action. Asserts `data-line-clamp="2"` and the `--dsx-alert-line-clamp` property; the registry row shows the text clipped to two lines with an ellipsis and the icon, first line and action on one centre. A value that is not a whole number of 1 or more leaves the text unclamped (tested).
 
 **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 +229,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 +246,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.
+A trailing action shares the row with the text and wraps below it, at the alert's start edge, when the text would drop under its readable width. 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

@@ -26,9 +26,9 @@ A hero mass: one label, one headline value, and an optional footnote over an acc
 | 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.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>` | Muted footnote + class | Renders `Text` body-small. Writes `dsx-banner__footnote`. Optional. |
+| `Banner.Footnote` | `<span>` | Compact footnote + class | Renders `Text` body-small with paired container ink. Writes `dsx-banner__footnote`. Optional. |
 
 ## Props contract
 
@@ -69,18 +69,18 @@ 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) |
+| 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-surface-variant)` | Muted label on wash |
+| 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-surface)` | Value ink on wash |
+| 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-surface-variant)` | Muted footnote on wash |
+| Footnote color | `var(--dsx-color-on-primary-container)` | Paired footnote ink on wash |
 
 ## Motion contract
 
@@ -98,7 +98,7 @@ None — no transitions, no animation. Pressed/`focus-visible` states do not app
 
 **Color and meaning:**
 
-- The wash is decorative; label/value text carries all meaning with `on-surface` contrast.
+- 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
 

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
 

package/dist/docs/components/bottom-dock.md

@@ -0,0 +1,146 @@
+---
+title: BottomDock
+status: canonical
+category: Components
+archetype: composite
+depends_on:
+  - "@radix-ui/react-slot (powers `asChild` on `BottomDock` and `BottomDock.Item`)"
+  - VisuallyHidden (keeps an inactive item's label in the accessible name while it is not drawn)
+---
+
+# BottomDock
+
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
+
+## Purpose
+
+A floating pill of primary destinations for phone widths — the phone counterpart of the `Sidebar`
+panel. It holds a handful of navigation items (four destinations plus a "More" item is the norm), marks
+the current one, and sits above the page bottom edge with the safe-area inset respected. It is
+navigation-agnostic: the app owns the routes, the active-page detection and what "More" does (usually
+opening the mobile `Sidebar` drawer through `useSidebar().setMobileSheetOpen(true)`).
+
+It is **not** a full-width tab bar (`TabNav`, `Tabs`) and not a toolbar. Use it only for primary
+navigation at phone widths; render it conditionally (the component writes no breakpoints).
+
+Wild references (decisions in `docs/feature/design-system/shell-chrome-c/decisions.md`): Material 3
+navigation bar (2–5 destinations; the selected destination always shows its label), Apple HIG tab bar
+(at most five tabs; labels recommended; badges), MUI `BottomNavigation` (`showLabels`).
+
+## Anatomy & slots
+
+**Parent:** `BottomDock`. The root is `<nav aria-label="Bottom navigation">`. Items are direct children.
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `BottomDock` | `<nav>` (or `Slot` child when `asChild`) | `dsx-bottom-dock` + `data-slot="bottom-dock"` + `data-placement` + `data-labels` | The floating pill and landmark. |
+| `BottomDock.Item` | `<button type="button">` (or `Slot` child when `asChild`, e.g. a router link) | `dsx-bottom-dock__item` + `data-slot="bottom-dock-item"` + `data-active` + `data-label` + `aria-current="page"` when active | One destination or action. |
+| `BottomDock.Icon` | `<span aria-hidden="true">` | `dsx-bottom-dock__icon` + `data-slot="bottom-dock-icon"` | Wraps the glyph (an `Icon`); decorative. |
+| `BottomDock.Label` | `<span>` | `dsx-bottom-dock__label` + `data-slot="bottom-dock-label"` | The destination name. When the item's label is hidden by the `labels` mode it renders through `VisuallyHidden`, so it stays in the accessible name. |
+| `BottomDock.Badge` | `<span>` | `dsx-bottom-dock__badge` + `data-slot="bottom-dock-badge"` | A count; with no children it renders as a dot. Position-only — the badge text, if any, is the consumer's. |
+
+## Props contract
+
+### `BottomDock`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `placement` | `'fixed' \| 'contained'` | `'fixed'` | no | `fixed` pins the dock to the viewport bottom and adds `--dsx-safe-area-inset-bottom`; `contained` positions it absolutely inside the nearest positioned ancestor (demos, framed compositions). | no |
+| `labels` | `'active' \| 'always' \| 'none'` | `'active'` | no | `active`: only the current item draws its label (Material 3); `always`: every item draws its label (HIG-style); `none`: no label is drawn and the items are icon-only, for widths where five labels do not fit (about 340px and below), picked by the app by width. Hidden labels stay in the accessible name in every mode. | no |
+| `asChild` | `boolean` | `false` | no | Renders the host through `Slot`. | no |
+| `aria-label` | `string` | `'Bottom navigation'` | no | The landmark name; override with product copy. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-bottom-dock`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | `BottomDock.Item` rows. | no |
+
+### `BottomDock.Item`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `isActive` | `boolean` | `false` | no | Marks the current destination. Writes `aria-current="page"` and `data-active="true"`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the host through `Slot`. When set, `type` is omitted. | no |
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | no | Forwarded to the host `<button>`. Omitted when `asChild` is set. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-bottom-dock__item`. | no |
+| `children` | `React.ReactNode` | (required) | yes | `BottomDock.Icon`, `BottomDock.Label`, optionally `BottomDock.Badge`. | no |
+
+`BottomDock.Icon`, `BottomDock.Label` and `BottomDock.Badge` accept standard `<span>` attributes plus `className` and `children`.
+
+Rules:
+
+- Guidance, not enforcement: up to five items; in practice four destinations plus "More".
+- An item without a `BottomDock.Label` must carry its own `aria-label`.
+- `BottomDock.Item` reads the dock's `labels` mode and its own `isActive` to write `data-label="visible" | "hidden"`; `BottomDock.Label` reads that to decide whether to render through `VisuallyHidden`.
+
+## CSS class contract
+
+**Root class:** `dsx-bottom-dock`
+
+| Attribute | Allowed values | Hook | CSS file |
+|---|---|---|---|
+| `data-placement` | `fixed`, `contained` | `.dsx-bottom-dock:where([data-placement='contained'])` switches to absolute positioning | `bottom-dock.css` |
+| `data-labels` | `active`, `always`, `none` | `none` shares the width between icon-only items (`.dsx-bottom-dock:where([data-labels='none']) .dsx-bottom-dock__item`); the visible/hidden decision is per item through `data-label` | `bottom-dock.css` |
+| `data-active` | `true` | `.dsx-bottom-dock__item:where([data-active='true'])` — the opaque accent container | `bottom-dock.css` |
+| `data-label` | `visible`, `hidden` | recorded on the item for consumers and tests; the hidden label is removed from the layout through `VisuallyHidden` | `bottom-dock.css` |
+| `data-slot` | `bottom-dock-*` | hooks | `bottom-dock.css` |
+
+**Slot classes:** `dsx-bottom-dock`, `dsx-bottom-dock__item`, `dsx-bottom-dock__icon`,
+`dsx-bottom-dock__label`, `dsx-bottom-dock__badge`.
+
+No `data-variant`, `data-size`, `data-accent-color`, `data-radius` or `data-high-contrast` is written
+(contract profile: none). `data-radius` in particular is never used as a local attribute name (see
+`component-contract.md`).
+
+**Responsive behavior:** none in CSS — the app renders the dock only at phone widths.
+
+**Reduced motion:** the item's colour/background transition is removed under `prefers-reduced-motion: reduce`.
+
+## Token mapping
+
+| Property | Token | Role |
+|---|---|---|
+| Position (fixed) | `inset-inline: var(--dsx-space-3)`; `inset-block-end: calc(var(--dsx-space-3) + var(--dsx-safe-area-inset-bottom, 0px))` | floating gap + safe area |
+| Stacking | `var(--dsx-z-index-fixed)` | above sticky chrome, below overlays and modals |
+| Surface | `var(--dsx-color-panel-translucent)` + `var(--dsx-effect-panel-glass-backdrop-filter)` | the glass panel precedent (dropdown-menu, command) |
+| Border | `var(--dsx-border-width-sm) solid var(--dsx-panel-border-color)` | structural edge |
+| Shadow | `var(--dsx-panel-shadow)` | floating elevation |
+| Radius | `var(--dsx-rounded-xl)` | pill |
+| Padding / gap | `var(--dsx-space-xs)` | inner rhythm |
+| Item min size | `calc(var(--dsx-size-xl) + var(--dsx-space-xs))` (44px at default density) | touch target |
+| Item radius | `var(--dsx-rounded-lg)` | follows the global radius setting |
+| Item colour | `var(--dsx-color-on-surface-variant)` | inactive |
+| Item hover | `var(--dsx-effect-hover-ghost)` | hover surface |
+| Item active | `var(--dsx-color-primary-container)` / `var(--dsx-color-on-primary-container)` | opaque accent container (DESIGN.md) |
+| Label type | `var(--dsx-typography-label-small-*)` | compact label; a label wider than its item truncates with an ellipsis (the full text stays in the accessible name) rather than overflowing the pill |
+| Badge | `var(--dsx-color-primary)` / `var(--dsx-color-on-primary)` | count or dot |
+| Focus ring | `var(--dsx-shadow-focus-ring)` | `:focus-visible` |
+| Motion | `var(--dsx-motion-duration-fast) var(--dsx-motion-easing-standard)` | colour transition |
+
+Rules: no raw colour, spacing, radius or motion values in `bottom-dock.css`.
+
+## Accessibility
+
+- `BottomDock` is a named `nav` landmark.
+- The current item has `aria-current="page"`; the active state is also carried by the container fill and the visible label (not colour alone). With `labels="none"` no label is visible, so the container fill (the opaque primary container, not the accent colour alone) and `aria-current` carry it, and every label stays in the accessible name.
+- Every item has an accessible name: its `BottomDock.Label` (kept in the DOM through `VisuallyHidden` when not drawn) or its own `aria-label`.
+- Touch targets are at least 44px; focus is a visible ring; the whole dock is reachable in normal tab order.
+- A badge with text is part of the item's accessible name ("Devices 3"); an empty dot badge adds nothing. Place the badge inside `BottomDock.Icon` to sit on the glyph (the icon wrapper is `aria-hidden`, so a count placed there is not announced).
+
+## Playground demo spec
+
+**Default story:** four `BottomDock.Item`s (icon + label) in a `contained` dock, the first active.
+**Variant stories:** `labels="always"` and `labels="none"` beside the default `active`; `placement="contained"` is the demo default. The `none` fixture sits in a 320px-wide frame with five items.
+**State stories:** an active item; an item with a count badge; an item with a dot badge; keyboard focus.
+**Composition story:** the dock with a "More" item that opens a `Sidebar` drawer (mobile) — documented, driven by `useSidebar()`.
+**Token story:** inside `Theme` with each of the five accents (the active container and the badge vary by accent).
+**A11y story:** `BottomDock.test.tsx` runs `vitest-axe`.
+
+| Prop | Control | Default |
+|---|---|---|
+| `placement` | select | `contained` (demo) |
+| `labels` | select | `active` |
+
+## Wiring notes
+
+**Composes from:** `@radix-ui/react-slot`, `VisuallyHidden`.
+
+**State boundaries:** owned by `BottomDock`: nothing persistent — only the derived `data-label`.
+Owned by the consumer: routes, the active item, the badge counts, the "More" action, when the dock is shown.