@d4gger/design-system 3.0.1 → 4.0.0

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

@@ -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'` | `'active'` | no | `active`: only the current item draws its label (Material 3); `always`: every item draws its label (HIG-style). Hidden labels stay in the accessible name. | 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` | recorded for consumers and tests; 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).
+- 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"` beside the default `active`; `placement="contained"` is the demo default.
+**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.

package/dist/docs/components/box.md

@@ -179,42 +179,11 @@ Box has no motion. The motion section is intentionally empty.
 
 - Box is not interactive and does not require an accessible name on its own. When Box wraps an interactive element, the interactive element's accessible name is the source.
 
-## Playground demo spec
-
-**Default story:**
-
-- Renders `Box` with no extra props and a child node. Asserts the root class is `dsx-box` and the host element is a `div`.
-
-**Padding story:**
-
-- Renders `Box padding="md"` and `Box p="md"` side by side. Asserts the matching `dsx-r-p-md` class and that `--dsx-box-padding` plus `--dsx-r-p` resolve to `var(--dsx-space-md)`.
-
-**Surface story:**
-
-- Renders `Box surface="surface-raised" border borderTone="strong" radius="md" shadow="2"`. Asserts that the `dsx-box` root class is present and the inline style carries the resolved CSS variables for surface, border, and shadow.
-
-**Responsive story:**
+The padding matrix uses outlined content bounds and the surface matrix uses actual Box surface props. The live example offers sm/md/lg padding controls (8/16/24px) around a fixed inner surface.
 
-- Renders `Box padding={{ initial: 'sm', md: 'lg' }} display={{ initial: 'flex', lg: 'grid' }}`. Asserts the `dsx-r-p-sm`, `md:dsx-r-p-lg`, and breakpoint variants for `display` resolve.
-
-**Token story:**
-
-- Box does not honor `data-accent-color`; surface tones come from `var(--dsx-color-*)` and respond to the active `Theme` wrapper automatically. Render `Box` inside a `Theme` with `accentColor="silver"` and `accentColor="bronze"`. The story asserts the surface variables come from the theme, not the brand color.
-
-**A11y story:**
-
-- Use `vitest-axe` against the rendered `Box`. The default story is a non-semantic `div` with no axe-critical content; tests assert no violations on the default render.
-
-**Props exposed in the playground controls:**
+## Playground demo spec
 
-| Prop | Control | Default |
-|---|---|---|
-| `display` | select | `block` |
-| `padding` | select | `md` |
-| `radius` | select | `md` |
-| `surface` | select | `surface` |
-| `border` | boolean | `false` |
-| `shadow` | select | `none` |
+The matrix exposes padding sm/md/lg and three neutral surfaces. Every cell outlines the content bounds inside a Box with an actual padding/surface prop. The live example changes padding between 8/16/24px around an unchanged inner project surface. It uses native Buttons with aria-pressed and remains bounded at 320px.
 
 ## Wiring notes
 

package/dist/docs/components/breadcrumb.md

@@ -112,7 +112,7 @@ Rules:
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. `size` is single-value only; the prop def is not `responsive: true`.
+- The component does not use width breakpoints. `size` is single-value only; the prop def is not `responsive: true`.
 
 **Reduced motion:**
 
@@ -127,17 +127,18 @@ Rules:
 | Link radius | `var(--dsx-rounded-md)` | Rounded tap area. |
 | Link color | `var(--dsx-color-on-surface)` | Default link. |
 | Link hover background | `var(--dsx-effect-hover-ghost)` | Hover. |
-| Link hover color | `var(--dsx-color-primary)` | Hover. |
+| Link hover color | `var(--dsx-color-accent-indicator)` | Hover. |
 | Link focus ring | `var(--dsx-shadow-focus-ring)` | Visible focus. |
 | Link disabled opacity | `var(--dsx-opacity-disabled)` | Disabled state. |
-| Page color | `var(--dsx-color-high-contrast)` | Current page text. |
+| Page background | `var(--dsx-color-accent-surface)` | Subtle current-page fill. |
+| Page color | `var(--dsx-color-accent-indicator)` | Current page text. |
 | Separator color | `var(--dsx-color-on-surface-variant)` | Divider. |
 | Typography (link and page) | `var(--dsx-typography-body-medium-*)` | Body copy. |
 
 Rules:
 
 - No raw color, spacing, radius, or motion values in `breadcrumb.css`.
-- The breadcrumb does not honor `data-accent-color`; the hover color uses `var(--dsx-color-primary)` directly because the active page is the only state the consumer needs to see in the accent color.
+- Breadcrumb inherits the active theme accent roles: hover/current-page foreground uses accent-indicator and the current-page fill uses accent-surface.
 
 ## Motion contract
 
@@ -176,7 +177,7 @@ Rules:
 
 **Color and meaning:**
 
-- The current page is communicated by `aria-current` and the high-contrast text color. The color is not the only signal.
+- The current page is communicated by `aria-current` and the accent foreground and current-page label. The color is not the only signal.
 
 **Naming:**
 
@@ -185,6 +186,8 @@ Rules:
 
 ## Playground demo spec
 
+Size scales the link/page typography and padding: sm uses body-small and space-xs; md retains body-medium with space-xs/space-sm; lg uses body-large and space-sm/space-md. Link targets have a minimum 24px height, and long labels wrap within the available container.
+
 **Default story:**
 
 - Renders a `Breadcrumb` with three items: Home (link), Products (link), Keyboard (page). Asserts the root has `dsx-breadcrumb` and `data-size="md"`. Asserts the page has `aria-current="page"`.
@@ -273,7 +276,7 @@ Rules:
 | `<Link text>` | typography | `var(--dsx-typography-body-medium-*)` | Typography | `typography` |
 | `<Link text>` | color | `var(--dsx-color-on-surface)` | Color | `fills` |
 | `<Page text>` | typography | `var(--dsx-typography-body-medium-*)` | Typography | `typography` |
-| `<Page text>` | color | `var(--dsx-color-high-contrast)` | Color | `fills` |
+| `<Page text>` | color | `var(--dsx-color-accent-indicator)` | Color | `fills` |
 | `<Separator icon>` | color | `var(--dsx-color-on-surface-variant)` | Color | `fills` |
 
 ### State transformations
@@ -281,8 +284,8 @@ Rules:
 | State | Link fill | Link background |
 |---|---|---|
 | `default` | `var(--dsx-color-on-surface)` | `transparent` |
-| `hover` | `var(--dsx-color-primary)` | `var(--dsx-effect-hover-ghost)` |
-| `focus-visible` | `var(--dsx-color-primary)` | `var(--dsx-shadow-focus-ring)` |
+| `hover` | `var(--dsx-color-accent-indicator)` | `var(--dsx-effect-hover-ghost)` |
+| `focus-visible` | `var(--dsx-color-accent-indicator)` | `var(--dsx-shadow-focus-ring)` |
 | `disabled` | `var(--dsx-color-on-surface)` with `var(--dsx-opacity-disabled)` | `transparent` |
 
 ### Variant model
@@ -295,3 +298,5 @@ Rules:
 - [ ] Token bindings resolve at the values `DESIGN.md` describes.
 - [ ] Component is promoted to Main Component under `Components`.
 - [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
+
+Current-page text pairs accent-indicator with accent-surface, retaining readable foreground contrast in both appearances.