@d4gger/design-system 3.0.0 → 4.0.0

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.

package/dist/docs/components/button-group.md

@@ -45,7 +45,7 @@ The root renders a `<div role="group">`. Children of the group share the first/l
 Rules:
 
 - `Omit<HTMLAttributes<HTMLDivElement>, ...>` is not applied; the type is a direct extension, so any `<div>` prop is forwarded.
-- The component does not own the buttons themselves. The consumer is responsible for sizing each `Button` to match the group's `size` token, and for keyboard semantics on every child.
+- The component does not own the buttons themselves. The group drives children min-height from its own `data-size`; the consumer remains responsible for keyboard semantics on every child.
 
 ## CSS class contract
 
@@ -55,7 +55,7 @@ Rules:
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-size` | `sm`, `md`, `lg` | `.dsx-button-group[data-size='sm'\|'md'\|'lg']` does not exist today; size is enforced by the children's own `data-size` hooks | `button-group.css` |
+| `data-size` | `sm`, `md`, `lg` | `.dsx-button-group[data-size='sm'\|'md'\|'lg'] > *` sets the matching density min-height token on every direct child, so the three sizes differ without consumer sizing | `button-group.css` |
 | (variant) | `default`, `outline` | `.dsx-button-group--default`, `.dsx-button-group--outline` | `button-group.css` |
 
 **Slot classes:**
@@ -69,6 +69,7 @@ Rules:
 
 - The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size and variant are single-value only.
 - The component's CSS file is breakpoint-agnostic.
+- Narrow containers: the root caps at `max-width: 100%` with `overflow-x: auto` — the fused frame cannot wrap, so an over-wide group scrolls instead of hard-clipping its last action (proven 2026-09-23 in a definite 272px column: group caps at 272, `scrollWidth` 298 reachable by touch scroll).
 
 **Reduced motion:**
 
@@ -94,7 +95,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 Rules:
 
-- The component does not paint its own background, border, or shadow. Visual treatment is delegated to the children, which means the group's appearance is fully driven by the `Button` variant chosen for each child.
+- The component paints no background, border, or shadow of its own. In `default`, children render borderless (`border-color: transparent`) for the fused cluster; in `outline`, children keep their own joined borders, which read as the container edge. Beyond that, visual treatment is delegated to the children.
 
 ## Motion contract
 

package/dist/docs/components/button.md

@@ -61,7 +61,7 @@ Rules:
 | `data-size` | `sm`, `md`, `lg`, `icon` | `.dsx-button[data-size='sm']` etc. | `button.css` |
 | `data-radius` | `none`, `sm`, `md`, `lg`, `full` | `.dsx-button[data-radius='none']` etc. | `button.css` |
 | `data-accent-color` | `rift`, `warp`, `ray` (or any custom string) | `.dsx-button[data-accent-color='...']` (CSS hook) | `button.css` |
-| `data-halo` | `true` | `.dsx-button:where([data-variant='primary'])[data-halo='true']` (resting accent ring; hover/active keep it, no shadow morph without it) | `button.css` |
+| `data-halo` | `true` | Resting accent ring on every variant (`.dsx-button:where([data-variant='…'])[data-halo='true']`; hover/active keep it, no shadow morph without it) | `button.css` |
 | `data-high-contrast` | `true` | `.dsx-button:where([data-variant='primary'])[data-high-contrast='true']` etc. (variant-specific HC overrides) | `button.css` |
 | `data-loading` | `true` | `.dsx-button[data-loading='true']` | `button.css` (writes to cursor and spinner positioning) |
 | `data-disabled` | `true` | `.dsx-button[data-disabled='true']` | `button.css` |
@@ -112,7 +112,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Background (primary) | `var(--dsx-color-accent-track)` | Primary fill (ramp step 9). |
 | Text (primary) | `var(--dsx-color-accent-contrast)` | Primary text. |
 | Border (primary) | `var(--dsx-color-accent-track)` | Primary edge. |
-| Box shadow (primary) | `var(--dsx-shadow-accent-ring)` | Resting halo — open decision vs the 2026-09-05 remove-halo proposal. |
+| Box shadow (primary) | `var(--dsx-shadow-accent-ring)` | Resting halo — locked 2026-09-22 for every variant (was primary-only; settles the 2026-09-05 remove-halo proposal toward keep-and-extend). |
 | Box shadow (primary HC) | `var(--dsx-shadow-accent-glow)` | High-contrast primary elevation. |
 | Background (primary HC) | `var(--dsx-color-accent-indicator)` | High-contrast primary fill. |
 | Text (primary HC) | `var(--dsx-color-on-high-contrast)` | High-contrast primary text. |

package/dist/docs/components/callout.md

@@ -16,7 +16,7 @@ depends_on: []
 
 ## Purpose
 
-A bordered inline notice: an icon, a message, and an optional trailing action column. Distinct from `Alert` (in-page flow banner) and `Toast`/`Sonner` (transient) — `Callout` is a persistent, bordered box, most often used for contextual tips, warnings, or dismissible product notices.
+A bordered inline notice: an icon, a message, and an optional action row. Distinct from `Alert` (in-page flow banner) and `Toast`/`Sonner` (transient) — `Callout` is a persistent, bordered box, most often used for contextual tips, warnings, or dismissible product notices.
 
 ## Anatomy & slots
 
@@ -26,10 +26,10 @@ A bordered inline notice: an icon, a message, and an optional trailing action co
 
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
-| `Callout.Root` | `<div>` | `dsx-callout` | 3-column grid: `auto 1fr auto` (icon, text, actions). |
+| `Callout.Root` | `<div>` | `dsx-callout` | Two-column grid: icon plus minmax(0, 1fr) content. Title, text and actions stack in column 2. |
 | `Callout.Icon` | `<div>` | `dsx-callout__icon` | Grid column 1. Sized by the `size` prop. |
 | `Callout.Text` | `<p>` | `dsx-callout__text` | Grid column 2. The message body. |
-| `Callout.Actions` | `<div>` | `dsx-callout__actions` | Grid column 3. **Optional** — a callout with no actions renders correctly; the 3rd grid track collapses to 0 width when nothing occupies it. Holds a dismiss button and/or other actions. |
+| `Callout.Actions` | `<div>` | `dsx-callout__actions` | Optional wrapping action row in content column 2, below title/text. Without an Icon, all content uses column 1. |
 
 ## Props contract
 
@@ -94,7 +94,9 @@ Rules that apply to this row:
 
 Rules:
 
-- No raw color, spacing, or radius values in `callout.css`. The action column introduced no new tokens — it reuses `--dsx-space-xs` for its internal gap.
+- No raw color, spacing, or radius values in `callout.css`. The action row introduces no new tokens — it reuses `--dsx-space-xs` for its internal gap.
+
+When no `Callout.Icon` is rendered, Title, Text and Actions occupy the first grid column. No empty icon gutter is reserved.
 
 ## Motion contract
 
@@ -178,7 +180,7 @@ Rules:
 
 **State boundaries:**
 
-- Owned by `Callout`: the root class, variant/size modifier classes, the grid layout, and the three slot classes.
+- Owned by `Callout`: the root class, variant/size modifier classes, the grid layout, and its slot classes.
 - Owned by the consumer: the message content, which action(s) render inside `Callout.Actions`, and any dismissal state/persistence (e.g. per-user dismissal tracked on the backend, per the `dashboard_notices` ask this slot was added for).
 
 **Boundary rules:**
@@ -193,7 +195,7 @@ Rules:
 ### Root board
 
 - **Name**: `Components / Callout`.
-- **Layout**: `Grid`, columns `auto 1fr auto`, gap per `size`.
+- **Layout**: `Grid`, columns `auto minmax(0, 1fr)`, gap per `size`.
 
 ### Layer tree
 
@@ -217,4 +219,13 @@ Rules:
 
 - [ ] Token bindings resolve at the values `DESIGN.md` describes.
 - [ ] Component is promoted to Main Component under `Components`.
-- [ ] Grid renders correctly with `Actions` present and absent (3rd column collapses to 0 width when empty).
+- [ ] Grid renders with optional Title, Icon and Actions; actions wrap below copy.
+
+## Overlay review composition
+
+`Callout.Title` is an existing h3 slot with class `dsx-callout__title`. Its
+heading, Text and wrapping Actions stack beside an Icon that spans the rows.
+Without Icon the root becomes a single column. Text has margin=0 and
+min-width=0; long copy wraps. Existing tone values info/warning/success/danger
+select semantic border and icon colors; highContrast uses the high-contrast
+foreground. `/docs/callout` shows all tones and real dismiss/restore actions.

package/dist/docs/components/card.md

@@ -93,6 +93,7 @@ The normalization is a one-way mapping: `outline` is the only variant that produ
 **Responsive behavior:**
 
 - The component does not write `@media` rules. `size`, `variant`, and `radius` are single-value only.
+- The root can shrink within its parent and is capped at the available width. Unbroken headings and identifiers wrap without truncation; Content and Footer retain their wrapping layout.
 
 **Reduced motion:**
 
@@ -131,9 +132,9 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Surface (filled) | `var(--dsx-color-surface)` | Filled surface (no shadow) |
 | Surface (outline) | `transparent` (plus `--dsx-effect-panel-solid-backdrop-filter`) | Compatibility outline surface |
 | Active / selected surface | `var(--dsx-color-accent-surface)` | Active / selected card |
-| Active / selected border | `var(--dsx-color-accent-indicator)` | Active / selected card edge |
+| Active / selected edge | `var(--dsx-boundary-selected-ring)` | Local accent-indicator 2px inset ring on every variant, including legacy outline; physical border is transparent, including under an outer light Theme |
 | High-contrast surface | `var(--dsx-color-high-contrast-container)` | High-contrast card |
-| High-contrast border | `var(--dsx-color-high-contrast-border)` | High-contrast card edge |
+| High-contrast edge | `var(--dsx-boundary-high-contrast-ring)` | Local 2px inset ring; physical border is transparent |
 | High-contrast text | `var(--dsx-color-high-contrast)` | High-contrast text |
 | Hover border | `var(--dsx-color-outline-variant)` | Hover border color |
 | Hover background | `var(--dsx-effect-hover-layer)` over surface-raised | Hover surface |
@@ -147,6 +148,13 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 The component is static. Hover state changes are instant; no transition is applied.
 
+Selected and high-contrast edges survive hover. For the color-role repair,
+the owning spec explicitly permits the narrow `baseCard.css` selector change:
+exclude selected/high-contrast cards from generic hover and static-accent
+edge/hover paint, and exclude selected cards from the light glass shadow override. This
+keeps the shared engine from replacing their inset rings; Alert and FileUpload
+behavior is unchanged by these Card-only exclusions.
+
 ## Accessibility
 
 **Roles:**