@d4gger/design-system 3.0.0 → 4.0.0

package/dist/docs/components/separator.md

@@ -28,7 +28,7 @@ No slots: flat export. The component renders a single Radix `SeparatorPrimitive.
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | no | Sets `data-orientation` on the host and the matching CSS rule. | no |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Reserved hook for the `data-size` attribute. The current CSS only uses the orientation attribute to size the line; `data-size` is the contract for future per-size thickness overrides. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Retained data-size hook; all sizes paint the canonical 1px non-emphasis divider. | no |
 | `variant` | `'default' \| 'decorative'` | `'default'` | no | When `'decorative'`, applies the `dsx-separator--decorative` modifier class. | no |
 | `color` | `string` | `undefined` | no | Free-form accent color name forwarded to `data-accent-color` on the host. | no |
 | `decorative` | `boolean` | `true` | no | Radix boolean: when true, the host is given `role="none"` and removed from the accessibility tree's semantic structure. When false, the host keeps `role="separator"`. | no |
@@ -39,7 +39,7 @@ Rules that apply to this row:
 
 - The component extends `React.ComponentPropsWithoutRef<typeof SeparatorPrimitive.Root>`, so every standard Radix `Separator.Root` attribute is forwarded.
 - `decorative` is the Radix accessibility opt-out. `Separator` defaults to `decorative={true}`; pass `decorative={false}` to expose the separator to assistive tech as a thematic break. The default is intentional: most separators are visual-only and the default should not add noise to the accessibility tree.
-- The CSS file does not yet read `data-size`; the attribute is the public contract for future per-size thickness overrides and is asserted by the test suite.
+- Size does not alter divider thickness; the 1px policy applies at every size.
 
 ## CSS class contract
 
@@ -51,8 +51,8 @@ Rules that apply to this row:
 |---|---|---|---|
 | `data-orientation` | `horizontal`, `vertical` | `.dsx-separator[data-orientation='horizontal']`, `.dsx-separator[data-orientation='vertical']` | `separator.css` |
 | (no attribute) | (presence) | `dsx-separator--decorative` when `variant === 'decorative'` | `separator.css` |
-| `data-size` | `sm`, `md`, `lg` | reserved for future thickness overrides | `separator.css` (no rule yet) |
-| `data-accent-color` | (any accent token name) | reserved for future accent overrides | `separator.css` (no rule yet) |
+| `data-size` | `sm`, `md`, `lg` | retained attribute; fixed 1px paint | `separator.css` |
+| `data-accent-color` | (any accent token name) | decorative accent-border paint | `separator.css` |
 
 **Slot classes:** none.
 
@@ -72,9 +72,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 |---|---|---|
 | Background (default) | `var(--dsx-control-separator-color-strong)` | Default line color. |
 | Background (decorative) | `var(--dsx-color-separator-muted)` | Muted line color for the `decorative` variant. |
+| Background (explicit color) | `var(--dsx-color-accent-border)` | Decorative accent rule; overrides the neutral variant color. |
 | Margin block (horizontal) | `var(--dsx-space-sm)` | Vertical breathing room around a horizontal line. |
 | Margin inline (vertical) | `var(--dsx-space-xs)` | Horizontal breathing room around a vertical line. |
-| Border width | `var(--dsx-border-width-md)` (default `var(--dsx-border-width-sm)`) | The painted line thickness. |
+| Border width | `var(--dsx-boundary-divider-width)` | The painted line thickness. |
 | Min height (vertical) | `var(--dsx-size-lg)` | Minimum line length for the vertical orientation. |
 
 Rules:
@@ -82,6 +83,7 @@ Rules:
 - No raw color, spacing, radius, or motion values in `separator.css`. The line is a `background` of the host; it is not a border.
 - The default and decorative variants use different tokens. The decorative token is intentionally lighter; the default token is the strong control line color.
 - Alpha is not used. The line colors are solid.
+- Neutral default/decorative dividers deliberately retain their gray colors across accents. Explicit accent dividers use accent-border: step 8 in light appearance and step 11 in dark appearance. Readable ink, focus and selection retain accent-indicator. Neutral aliases rebind to the nearest appearance and gray boundary.
 
 ## Motion contract
 
@@ -120,49 +122,11 @@ Rules:
 
 - The separator does not need an accessible name. The Radix primitive handles `aria-hidden` and `role` based on `decorative`. Pair a non-decorative separator with surrounding landmarks (headings, sections) so the thematic break is announced in context.
 
-## Playground demo spec
-
-**Default story:**
-
-- Renders `Separator`. Asserts the host has `dsx-separator`, `data-orientation="horizontal"`, and `role="none"` (the default `decorative` flag strips the semantic role from the accessibility tree).
-
-**Orientation story** (one per orientation):
-
-- Renders Separator with `orientation="horizontal"` and `orientation="vertical"`. Asserts the matching `data-orientation` attribute and the matching CSS rule (width vs height).
-
-**Size story** (one per size):
-
-- Renders Separator with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` value on the host. The current CSS does not switch the painted thickness per size; the story documents that the attribute is the contract for future overrides.
-
-**Variant story** (one per variant):
-
-- Renders Separator with `variant="default"` and `variant="decorative"`. Asserts the `dsx-separator--decorative` modifier class is present on the decorative variant and absent on the default.
-
-**State story:**
+Matrix cells place each orientation between text, rather than rendering a free-floating line. Live examples show horizontal section division, vertical metadata division, decorative tone and the reserved data-accent-color hook.
 
-- Renders Separator with `decorative={false}`. Asserts the host has `role="separator"` instead of `role="none"`. For a non-decorative vertical separator, asserts `aria-orientation="vertical"` is also on the host.
-
-**Composition story:**
-
-- Renders Separator inside a `Flex` row to verify the vertical orientation has a meaningful min height and does not collapse to zero.
-
-**Token story:**
-
-- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the line color is unchanged across accents (the current CSS does not read `data-accent-color`; the story documents the contract for future accent overrides).
-
-**A11y story:**
-
-- Uses `vitest-axe` against a rendered default Separator. Asserts there are no axe violations.
-
-**Props exposed in the playground controls:**
+## Playground demo spec
 
-| Prop | Control | Default |
-|---|---|---|
-| `orientation` | select (`horizontal`, `vertical`) | `horizontal` |
-| `size` | select (`sm`, `md`, `lg`) | `md` |
-| `variant` | select (`default`, `decorative`) | `default` |
-| `color` | text | (empty) |
-| `decorative` | boolean | `true` |
+Matrix cells place horizontal or vertical lines between Overview and Details text with a bounded 220px frame. All size hooks remain shown and paint the canonical 1px thickness. The live example includes a horizontal section divider, vertical metadata divider, decorative tone, and an accent line using color="inherit" through the existing data-accent-color hook. The semantic divider uses decorative={false}; the other lines are decorative.
 
 ## Wiring notes
 

package/dist/docs/components/sidebar.md

@@ -74,6 +74,7 @@ The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset`
 | `mobileBreakpoint` | `number` | `768` | no | Viewport width below which the provider treats the device as mobile. The provider also matches `(pointer: coarse)`. | no |
 | `defaultSubmenuMode` | `'click' \| 'hover'` | `'click'` | no | Default toggle mode for every `Sidebar.MenuSubTrigger` under this provider. Individual triggers override per-section. | no |
 | `submenuOpenOnActive` | `boolean` | `true` | no | Default for `openOnActive` on every `Sidebar.MenuSubTrigger` under this provider. | no |
+| `variant` | `'default' \| 'floating'` | `'default'` | no | `floating` draws the inline panel as a rounded, bordered, shadowed glass surface set off from the viewport edge, with a gap around it and between it and the inset, over whatever the page paints behind. It never applies to the mobile drawer: while the sidebar renders as the drawer, the variant has no visual effect and `data-variant` reads `default`. Specified for `collapsible="icon"` and `"none"`; with `"offcanvas"` a collapsed panel hides without a border sliver, and the recovery rail keeps its default look. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-sidebar-provider`. | no |
 | `children` | `React.ReactNode` | `undefined` | no | Provider children. In mobile sheet mode, each Sidebar root preserves its named `<nav>` wrapper, classes, and consumer props inside `Sheet.Content`; sibling inset content remains inline. | no |
 
@@ -163,6 +164,8 @@ The parent button that toggles a `Sidebar.MenuSub`. Composes the public `Collaps
 
 ### `Sidebar.MenuBadge`
 
+Dual pattern (F6 brief): inline row badges compose `Badge` (`secondary`, `sm`) directly inside the menu button; `MenuBadge` is the dedicated primitive for the absolute count / collapse-aware case and the `ring` / `accent` identities. Example row-value composition: `MenuButton` + `<Badge variant="secondary" size="sm">12</Badge>` — no `MenuBadge` needed.
+
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `variant` | `'text' \| 'ring' \| 'accent'` | `'text'` | no | `text` composes the compact secondary Badge, `ring` visualizes `value / max`, and `accent` renders quiet glowing numeric metadata without a filled chip. | no |
@@ -184,10 +187,11 @@ Standard React HTML attributes plus the `role="separator"` and `aria-orientation
 
 ### `useSidebar` hook
 
-Returns the `SidebarContext` value or a no-op fallback (`expanded: true`, `setExpanded: () => {}`, `mobileSheetOpen: false`, `setMobileSheetOpen: () => {}`, `isMobile: false`) when the consumer renders a sidebar slot outside `Sidebar.Provider`.
+Returns the `SidebarContext` value or a no-op fallback (`expanded: true`, `setExpanded: () => {}`, `mobileSheetOpen: false`, `setMobileSheetOpen: () => {}`, `isMobile: false`, `variant: 'default'`) when the consumer renders a sidebar slot outside `Sidebar.Provider`.
 
 Rules:
 
+- `variant` is the variant in effect, not the raw prop: `floating` only while the sidebar renders inline. The provider and the root write it as `data-variant`; `Sidebar.Inset` is deliberately unmarked and keeps no surface of its own, so the page behind the panel shows through.
 - The `data-state` and `data-collapsed` attributes are written by `getSidebarDataAttributes` and applied to the `Provider`, the `Root`, and every slot that reads from `useSidebar()`. The `data-state` value is `expanded` or `collapsed`.
 - `Sidebar.MenuButton` and `Sidebar.MenuSubButton` write `data-active` when `isActive` is `true` and wrap string or number children in `<span class="dsx-sidebar__menu-button-text">`. The wrapping span is omitted when `asChild` is set.
 - `Sidebar.Provider` registers a `keydown` listener on `document` for the toggle shortcut. The listener is removed on cleanup and is a no-op when `toggleShortcut` is `false`. The shortcut is `Ctrl+B` on Windows and Linux, `Cmd+B` on macOS.
@@ -213,7 +217,8 @@ Rules:
 | `data-pinned-state` | `expanded`, `collapsed` | Records the persisted/manual state while `data-state` may temporarily be `expanded` for a preview. | `sidebar.css` |
 | `data-transitions-ready` | `true`, `false` | Prevents persisted state hydration from replaying panel motion on route remount. | `sidebar.css` |
 | `data-effect` | `none`, `ambient` | Selects the Sidebar surface effect. | `sidebar.css` |
-| `data-variant` | `ring`, `accent` | Marks a proportional ring or quiet accent `MenuBadge`; text badges omit the attribute. | `sidebar.css` |
+| `data-variant` (provider, root) | `default`, `floating` | `.dsx-sidebar-provider:where([data-variant='floating'])`, `.dsx-sidebar[data-variant='floating']`: glass panel, offset and gap. Always written; `floating` only while the sidebar renders inline. | `sidebar.css` |
+| `data-variant` (`MenuBadge`) | `ring`, `accent` | Marks a proportional ring or quiet accent `MenuBadge`; text badges omit the attribute. | `sidebar.css` |
 | `data-active` | `true` | `.dsx-sidebar__menu-button[data-active='true']`, `.dsx-sidebar__menu-sub-button[data-active='true']` | `sidebar.css` |
 | `data-state` (sub-trigger) | `open`, `closed` | `:where(.dsx-sidebar__menu-sub-trigger[data-state='open']) > .dsx-sidebar__menu-sub-trigger-chevron { transform: rotate(90deg) }` with `transition-transform` (`:where` keeps it at 0,1,0) | `sidebar.css` |
 | `data-show-icon` | `true`, `false` | (icon visibility inside the skeleton) | `sidebar.css` |
@@ -285,6 +290,13 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Panel ambient effect | `var(--dsx-color-accent-9)` mixed with transparency | Optional subscription-aware accent wash without a literal starfield. |
 | Panel border | `none` (CSS keyword) | The slim shell uses surface contrast and elevation instead of a boxed edge. |
 | Panel shadow | `var(--dsx-effect-shadow-1)` | Panel elevation. |
+| Floating: provider padding and gap | `var(--dsx-space-3)` | The space around the panel and between the panel and the inset. Never a sidebar margin: the preview and pin-docking motion animate `margin-inline-end` and `width`. |
+| Floating: panel offset and height | `var(--dsx-space-3)` (`top`), `calc(100dvh - var(--dsx-space-3) - var(--dsx-space-3))` (`height`) | Keeps the sticky panel inside the same inset on every side. |
+| Floating: panel background | `var(--dsx-color-panel-translucent)` | Glass surface; the ambient effect's gradient still paints over it. |
+| Floating: panel backdrop | `var(--dsx-effect-panel-glass-backdrop-filter)` | Glass blur. |
+| Floating: panel border | `var(--dsx-border-width-sm) solid var(--dsx-panel-border-color)` | Glass edge; dropped (`border-width: 0`) when an `offcanvas` panel is collapsed so a zero-width panel leaves no sliver. |
+| Floating: panel radius | `var(--dsx-rounded-xl)` | Follows the global radius setting. |
+| Floating: panel shadow | `var(--dsx-panel-shadow)` | Floating elevation. |
 | Panel motion duration | `var(--dsx-motion-duration-normal, 250ms)` | Width transition. |
 | Panel motion easing | `var(--dsx-motion-easing-standard, ease)` | Width easing. |
 | Inset flex | `1` (CSS keyword) | Fill remaining width. |
@@ -314,7 +326,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Menu button active background | `color-mix(accent-3 50%, transparent)` | Sidebar-owned middle wash: 40% vanishes on spark-light, 60% shouts on saturated accents (warp/ray) — structure (inset underline) carries the rest of selection, no primary fill. |
 | Menu button active color | `var(--dsx-color-accent-indicator)` | Active menu button text and icon. |
 | Ring badge label typography | `var(--dsx-typography-label-small-*)` | Complete compact UI typography, including family, line height, spacing, case, decoration, and tabular numerals. |
-| Accent badge metadata | `var(--dsx-typography-label-small-*)`, `var(--dsx-color-accent-indicator)`, `var(--dsx-color-accent-9)` | Badge-geometry pill (full radius, Badge padding, fill-matched hairline, accent-surface fill) with a visible accent halo + pulse; full MenuBadge→Badge absorption is owned by the chip-taxonomy brief. |
+| Accent badge metadata | `var(--dsx-typography-label-small-*)`, `var(--dsx-color-accent-indicator)`, `var(--dsx-color-accent-9)` | Badge-geometry pill (full radius, Badge padding, fill-matched hairline, accent-surface fill) with a visible accent halo + pulse. Dual pattern (F6 brief): inline row badges compose `Badge` directly; `MenuBadge` survives for the absolute count/collapse-aware case plus the glow + pulse identity, which has no Badge equivalent. |
 | Accent badge motion | `var(--dsx-motion-duration-shimmer)`, `var(--dsx-motion-easing-in-out)` | Continuous opacity and text-shadow pulse; removed under reduced motion. |
 | Menu sub padding | `0 0 0 calc(lg + sm)` | Indent budget: sub text lands exactly under the parent label (label x=40, was 32). |
 | Menu sub gap | `var(--dsx-space-xs)` | Gap inside submenu. |
@@ -390,6 +402,8 @@ Rules:
 
 - The panel landmark has a default `aria-label="Sidebar"`. The rail and trigger have default `aria-label` values (`Expand sidebar` / `Collapse sidebar`). Override the labels when the panel needs product-specific copy.
 
+Submenu parent triggers use `--dsx-rounded-sm`, matching navigation rows rather than the Button pill radius. The playground lab composes Sidebar.Inset with content that changes on navigation and utility actions, so active state has a visible result. The demo bounds its navigation height to 560px and reserves header clearance for the mobile menu control. Routing remains app-owned.
+
 ## Playground demo spec
 
 **Default story:**
@@ -400,6 +414,7 @@ Rules:
 
 - Renders the provider with `defaultExpanded={false}`. Asserts `data-state="collapsed"`, `data-collapsed="true"`, and the `dsx-sidebar-default-expanded` class on the panel.
 - Renders a composed fixture with `effect="ambient"` alongside the default `none` surface so the optional token-driven accent wash is visible in the Playground.
+- Renders the provider with `variant="floating"` and asserts `data-variant="floating"` on the provider and the root, no `data-variant` on `Sidebar.Inset`, and `data-variant="default"` while the sidebar renders as the mobile drawer. The docs lab toggles `default` / `floating` over the brand haze (`dsx-brand-ambient`), because a glass panel only reads as glass over something.
 
 **State story:**
 
@@ -425,6 +440,7 @@ Rules:
 | `defaultExpanded` | boolean | `true` |
 | `hoverExpand` | boolean | `false` |
 | `previewOpen` | boolean | `false` |
+| `variant` | select | `default` |
 
 ## Wiring notes
 
@@ -445,7 +461,7 @@ Rules:
 
 **State boundaries:**
 
-- Owned by `Sidebar`: the expanded / collapsed state, the temporary hover/focus preview, the persisted state in localStorage or cookies, the mobile detection, the global `Ctrl+B` / `Cmd+B` shortcut, the active menu button flag, the `data-state`, `data-collapsed`, `data-preview-expanded`, and `data-pinned-state` attributes, and the `data-active` attribute.
+- Owned by `Sidebar`: the expanded / collapsed state, the temporary hover/focus preview, the persisted state in localStorage or cookies, the mobile detection, the global `Ctrl+B` / `Cmd+B` shortcut, the active menu button flag, the `data-state`, `data-collapsed`, `data-preview-expanded`, `data-pinned-state` and `data-variant` attributes, and the `data-active` attribute.
 - Owned by the consumer: the route map, the active-page detection, the disabled reasons, the auth and permissions policy, and the persistence target.
 
 **Boundary rules:**

package/dist/docs/components/sonner.md

@@ -65,7 +65,7 @@ The CSS file also targets `[data-sonner-toaster]` and `[data-sonner-toast]` dire
 **Responsive behavior:**
 
 - The component does not write `@media` rules. None of its prop defs are `responsive: true`.
-- The component's CSS file is breakpoint-agnostic, but the toaster layout shifts to a full-width style under `max-width: 640px` so mobile viewports receive a sensible default.
+- The package stylesheet uses an intrinsic viewport width cap at every width; it has no width media queries. The adapter retains its own positioning rules and mobileOffset API.
 
 **Reduced motion:**
 
@@ -81,32 +81,33 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Toaster z-index | `var(--dsx-z-index-toast)` | Toast stack. |
 | Toaster gap | `var(--dsx-space-md)` | Space between toasts. |
 | Toaster padding | `var(--dsx-space-md)` | Inner gutter. |
-| Toast padding block | `var(--dsx-space-sm)` | Toast vertical padding. |
+| Toast padding block | `var(--dsx-space-md)` | Toast vertical padding. |
 | Toast padding inline | `var(--dsx-space-md)` | Toast horizontal padding. |
 | Toast background | `var(--dsx-color-surface)` | Resting toast surface. |
 | Toast radius | `var(--dsx-rounded-md)` | Toast corner roundness. |
 | Toast border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Toast edge. |
-| Toast shadow | `var(--dsx-shadow-elevation-2)` | Toast elevation. |
-| Toast gap | `var(--dsx-space-md)` | Gap between icon, title, description, and buttons. |
+| Toast shadow | `var(--dsx-shadow-elevation-5)` | Spotlight: below dialogs, above all menus (B4 Q3). |
+| Toast gap | `var(--dsx-space-sm)` | Gap between icon, body and close; action row below. |
 | Success border | `var(--dsx-color-success)` | Success variant edge. |
 | Error background | `var(--dsx-color-error-container)` | Error variant surface. |
 | Error border | `var(--dsx-color-error)` | Error variant edge. |
 | Error text | `var(--dsx-color-on-error-container)` | Error variant text. |
-| Warning border | `var(--dsx-color-tertiary)` | Warning variant edge. |
-| Info border | `var(--dsx-color-secondary)` | Info variant edge. |
+| Warning border | `var(--dsx-color-warning)` | Warning variant edge. |
+| Info border | `var(--dsx-color-info)` | Info variant edge. |
 | Title typography | `var(--dsx-typography-label-large-*)` | Toast title. |
+| Title line-height | `var(--dsx-size-md)` | First line centred with the 24px icon/Close boxes. |
 | Title text | `var(--dsx-color-on-surface)` | Default title color. |
 | Description typography | `var(--dsx-typography-body-medium-*)` | Toast description. |
 | Description text | `var(--dsx-color-on-surface-variant)` | Default description color. |
 | Action, cancel, close | `var(--dsx-color-on-surface-variant)` | Default button text. |
-| Action, cancel, close padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Button padding. |
+| Action / cancel padding and height | `var(--dsx-space-xs) var(--dsx-space-sm)`, minimum `--dsx-size-lg` | Labelled controls below the message. |
+| Close dimensions / padding | `--dsx-size-md`, `0` | 24px box at the trailing top edge. |
 | Action, cancel, close radius | `var(--dsx-rounded-sm)` | Button corner roundness. |
 | Action, cancel, close hover background | `var(--dsx-color-high-contrast-container)` | Hover affordance. |
 | Action, cancel, close hover text | `var(--dsx-color-high-contrast)` | Hover affordance. |
 | Error title, description, close text | `var(--dsx-color-on-error-container)` | Error variant text. |
-| Mobile width | `calc(100vw - var(--dsx-size-md))` | Mobile max width. |
-| Mobile padding | `var(--dsx-space-sm)` | Mobile padding. |
-| Mobile inset | `var(--dsx-space-3)` | Mobile offset. |
+
+The first row places an optional icon, a shrinkable message body and a trailing Close in separate columns. The title line-height uses size-md (24px), aligning its first line with the centres of the 24px icon and Close boxes, including wrapped titles. Action and cancel controls occupy a second row below the message, preserving readable label widths. Without an icon, the message starts in the first column.
 
 ## Motion contract
 
@@ -131,7 +132,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Focus:**
 
-- Visible focus ring via the host application's focus styles. The DS does not add a custom focus ring; apps that need a custom ring can target the action, cancel, and close buttons from the host.
+- Action, cancel and close controls have the package focus ring and a minimum 24px control box. Actions retain their intrinsic label width; the text column shrinks and wraps within the available toast width.
 
 **Reduced motion:**
 
@@ -165,7 +166,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the toaster host renders inside the wrapper and the variant borders continue to render with the package tokens.
+- Renders inside a `Theme` wrapper with `accentColor="rift"`, `accentColor="astral"`, and `accentColor="spark"`. Asserts the toaster host renders inside the wrapper and the variant borders continue to render with the package tokens.
 
 **Props exposed in the playground controls:**
 
@@ -186,7 +187,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Used by:**
 
-- `NotificationCenter`: composes `Sonner` plus `Toast`, `Card`, and `DataList` for the inbox-style notification surface. The pattern-level `NotificationCenter` is the intended product composition; `Sonner` itself is a leaf surface.
+- Consumers compose transient notifications with `Sonner`; `NotificationCenter` is a separate inbox surface and does not render this adapter internally.
 
 **State boundaries:**
 
@@ -228,8 +229,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Success toast | stroke | `var(--dsx-color-success)` | Color | `strokes` |
 | Error toast | fill | `var(--dsx-color-error-container)` | Color | `fills` |
 | Error toast | stroke | `var(--dsx-color-error)` | Color | `strokes` |
-| Warning toast | stroke | `var(--dsx-color-tertiary)` | Color | `strokes` |
-| Info toast | stroke | `var(--dsx-color-secondary)` | Color | `strokes` |
+| Warning toast | stroke | `var(--dsx-color-warning)` | Color | `strokes` |
+| Info toast | stroke | `var(--dsx-color-info)` | Color | `strokes` |
 | Title | text fill | `var(--dsx-color-on-surface)` | Color | `fills` |
 | Description | text fill | `var(--dsx-color-on-surface-variant)` | Color | `fills` |
 | Error title, description | text fill | `var(--dsx-color-on-error-container)` | Color | `fills` |
@@ -241,8 +242,8 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | `default` | `var(--dsx-color-surface)` | `var(--dsx-color-outline)` | `var(--dsx-color-on-surface)` |
 | `success` | `var(--dsx-color-surface)` | `var(--dsx-color-success)` | `var(--dsx-color-on-surface)` |
 | `error` | `var(--dsx-color-error-container)` | `var(--dsx-color-error)` | `var(--dsx-color-on-error-container)` |
-| `warning` | `var(--dsx-color-surface)` | `var(--dsx-color-tertiary)` | `var(--dsx-color-on-surface)` |
-| `info` | `var(--dsx-color-surface)` | `var(--dsx-color-secondary)` | `var(--dsx-color-on-surface)` |
+| `warning` | `var(--dsx-color-surface)` | `var(--dsx-color-warning)` | `var(--dsx-color-on-surface)` |
+| `info` | `var(--dsx-color-surface)` | `var(--dsx-color-info)` | `var(--dsx-color-on-surface)` |
 
 ### Variant model
 
@@ -257,3 +258,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 - [ ] 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.
+
+## Overlay review fixture
+
+`/docs/sonner` owns one Toaster in its live example; matrix buttons use that
+host rather than mounting duplicates. One action emits one notification.
+Save draft with undo updates visible feedback through its action callback.
+The adapter retains its preferred width, capped by viewport minus
+dialog-viewport-gap. Package padding remains space-md at every width.

package/dist/docs/components/sortable-list.md

@@ -25,6 +25,8 @@ raw id when the item cannot be resolved). Disabled items keep a focusable
 handle marked `aria-disabled`; the handle shows `cursor: not-allowed` and the
 row stays dimmed, and dnd-kit never lifts a disabled item.
 
+Successful reordering restores focus to that list's handle. Repeated item IDs in another SortableList do not capture focus, and a content button before the handle is not used as the focus target.
+
 Import `SortableList` from `@d4gger/design-system/sortable-list`. It is intentionally absent from the root and `components` barrels so consumers that do not use reordering are not required to install the optional `@dnd-kit/*` peers.
 
 ## Playground demo spec

package/dist/docs/components/stat-card.md

@@ -65,7 +65,7 @@ Each slot also accepts the standard HTML attributes for its host element. `StatC
 Rules:
 
 - The component does not emit `data-radius`, `data-accent-color`, or `data-high-contrast`. The contract calls for `data-variant` and `data-size` only.
-- The `Trend` icon is always rendered; consumers that want an icon-free trend should pass an empty `children` and use `asChild` to override the host.
+- The `Trend` icon is always rendered, including with `asChild`; consumer children provide the label rather than replacing the icon.
 
 ## CSS class contract
 
@@ -75,8 +75,8 @@ Rules:
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-variant` | `surface`, `ghost` | (no rule in `stat-card.css`; attribute is informational) | n/a |
-| `data-size` | `sm`, `md`, `lg` | (no rule in `stat-card.css`; attribute is informational) | n/a |
+| `data-variant` | `surface`, `ghost` | `.dsx-stat-card[data-variant='ghost']` removes the surface background | `stat-card.css` |
+| `data-size` | `sm`, `md`, `lg` | `.dsx-stat-card[data-size='sm'|'lg']` changes padding; Metric.Value inherits the size for typography | `stat-card.css`, `metric.css` |
 
 **Trend modifier classes** (driven by the `trend` prop def):
 
@@ -99,6 +99,7 @@ Rules:
 **Responsive behavior:**
 
 - The component does not write `@media` rules. `size`, `variant`, and `trend` are single-value only.
+- Metric's containment keeps long values within the card; Footer and Trend wrap intrinsically. Number formatting remains consumer-owned.
 
 **Reduced motion:**
 
@@ -209,7 +210,7 @@ The component is static.
   `dsx-stat-card*` class, prop, export, trend icon, and rendered host element.
 - `Card` remains the conceptual surface parent; StatCard keeps its own
   `dsx-stat-card` surface class for backward compatibility.
-- `Text`, `Badge`, `Icon`: the typical content of the value, footer, and trend slots. StatCard does not import any of these; the consumer supplies the nodes.
+- `Icon` is imported for the internal trend glyph. Consumers supply value/footer content, including optional Text or Badge nodes.
 
 **Used by:**
 

package/dist/docs/components/stepper.md

@@ -38,7 +38,7 @@ A multi-step wizard or progress indicator that pairs a numbered indicator with a
 
 - The root is a flex container. In `orientation="horizontal"` (the default) it is a `flex-direction: row` with `align-items: center`. In `orientation="vertical"` it is a `flex-direction: column` with `align-items: flex-start`.
 - `Stepper.Item` is a flex container. In horizontal orientation the item itself flips to `flex-direction: column` so the indicator sits above the label / description. In vertical orientation the item stays in a `flex-direction: row` and is `width: 100%` so the indicator, label, description, and content lay out side by side.
-- `Stepper.Indicator` is a circular `var(--dsx-size-md)` badge with a 1px outline. It uses the `label-medium` type ramp. State colors (complete, current, error, disabled) are applied via the parent `Item`'s modifier class.
+- `Stepper.Indicator` is a circular `var(--dsx-stepper-indicator-size)` badge with a 1px outline. It uses the `label-medium` type ramp. State colors (complete, current, error, disabled) are applied via the parent `Item`'s modifier class.
 - `Stepper.Separator` is the connector. In horizontal orientation it is a `flex: 1` bar that fills the available space; in vertical orientation it is a `var(--dsx-border-width-lg)` wide, `var(--dsx-space-lg)` tall bar offset to the right of the indicator.
 
 ## Props contract
@@ -107,36 +107,11 @@ These slots accept only `asChild` plus the standard HTML attribute surface for t
 
 ## Token mapping
 
-Every CSS value the component paints is a `var(--dsx-*)` token.
+Indicator diameter is a component-local size variable: sm → `var(--dsx-size-md)` (24px), md → `var(--dsx-size-lg)` (32px), lg → `var(--dsx-size-xl)` (40px). The same variable anchors both orientations’ connectors. Labels/descriptions wrap within their column.
 
-| Property | Token | Role |
-|---|---|---|
-| Item gap | `var(--dsx-space-sm)` | Gap between indicator and label / description |
-| Indicator size | `var(--dsx-size-md)` | Indicator width and height |
-| Indicator border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Indicator edge |
-| Indicator background | `var(--dsx-color-surface)` | Indicator surface |
-| Indicator radius | `var(--dsx-rounded-full)` | Circular indicator |
-| Indicator type ramp | `var(--dsx-typography-label-medium-*)` | Indicator number |
-| Indicator text color | `var(--dsx-color-on-surface-variant)` | Indicator text |
-| Complete indicator | `var(--dsx-color-success)` (border + background), `var(--dsx-color-on-success)` (text) | Success palette |
-| Current indicator | `var(--dsx-color-primary)` (border + background), `var(--dsx-color-on-primary)` (text) | Primary palette |
-| Error indicator | `var(--dsx-color-error)` (border + background), `var(--dsx-color-on-error)` (text) | Error palette |
-| Disabled item | `var(--dsx-opacity-disabled)` | Disabled opacity |
-| Label type ramp | `var(--dsx-typography-label-large-*)` | Label text |
-| Label color | `var(--dsx-color-on-surface)` | Default label color |
-| Pending / disabled label | `var(--dsx-color-on-surface-variant)` | Pending / disabled label color |
-| Description color | `var(--dsx-color-on-surface-variant)` | Description text |
-| Description type ramp | `var(--dsx-typography-body-medium-*)` | Description text |
-| Separator height | `var(--dsx-border-width-lg)` | Default connector thickness |
-| Separator background | `var(--dsx-color-outline-variant)` | Default connector color |
-| Separator radius | `var(--dsx-rounded-full)` | Connector roundness |
-| Separator min-width | `var(--dsx-space-md)` | Min horizontal connector length |
-| Horizontal separator offset | `margin-top: calc(var(--dsx-size-md) / 2 - var(--dsx-border-width-lg) / 2)`, `margin-left: var(--dsx-space-sm)`, `margin-right: var(--dsx-space-sm)` | Alignment with the indicator centerline |
-| Vertical separator width | `var(--dsx-border-width-lg)` | Vertical connector thickness |
-| Vertical separator height | `var(--dsx-space-lg)` | Vertical connector length |
-| Vertical separator offset | `flex: 0`, `margin-left: calc(var(--dsx-size-md) / 2 - var(--dsx-border-width-lg) / 2)`, `min-height: var(--dsx-space-lg)` | Centered alignment with the indicator centerline |
-| Complete-separator color | `var(--dsx-color-primary)` | Connector after a complete step |
-| Content margin-top | `var(--dsx-space-lg)` | Panel offset |
+Horizontal items share equal widths; each non-final item draws a connector from the indicator edge to the next item. Vertical items draw a connector from the indicator bottom through the item padding. `Stepper.Separator` remains a supported DOM slot and is visually hidden in both shipped orientations.
+
+Indicators retain state tokens: complete uses success/on-success; current uses primary/on-primary; error uses error/on-error; pending uses surface/outline/on-surface-variant. Disabled opacity uses opacity-disabled. Connector thickness uses border-width-lg, resting color outline-variant, completed color primary. Labels and descriptions use label-large/body-medium typography. Item gap uses space-sm; horizontal column gap uses space-lg.
 
 ## Motion contract
 
@@ -183,9 +158,9 @@ The component has no motion. State transitions (complete / current / pending / e
 The vertical `Stepper` layout previously had two visual defects:
 
 1. The `.dsx-stepper--vertical .dsx-stepper__separator` override did not reset the base `flex: 1`, causing the separator to grow along the main axis in vertical orientation.
-2. The `margin-left` was `calc(var(--dsx-size-md) / 2)` without subtracting half the separator width, offsetting the connector from the indicator centerline.
+2. The `margin-left` was `calc(var(--dsx-stepper-indicator-size) / 2)` without subtracting half the separator width, offsetting the connector from the indicator centerline.
 
-Both issues are now fixed: the vertical override sets `flex: 0` and uses `margin-left: calc(var(--dsx-size-md) / 2 - var(--dsx-border-width-lg) / 2)` to center the connector under the indicator.
+Both issues are now fixed: the vertical override sets `flex: 0` and uses `margin-left: calc(var(--dsx-stepper-indicator-size) / 2 - var(--dsx-border-width-lg) / 2)` to center the connector under the indicator.
 
 ## Playground demo spec
 
@@ -229,6 +204,7 @@ Both issues are now fixed: the vertical override sets `flex: 0` and uses `margin
 **Used by:**
 
 - App-level onboarding flows, multi-step forms, and wizard navigation. The roster explicitly calls out that `Stepper` is a composite, not a pattern, and that it must compose primitive `Indicator + Separator + Label` parts rather than a parallel visual shell.
+- Timeline (rail recipe consumer, CSS contract only — no component dependency): Timeline reuses the vertical rail geometry (dot-column centering calc, marker-bottom anchor, size-aware offsets, active-state recolor) for its left rail and centered alternate spine, while keeping its own Item/Marker/Content/Connector API, its own event states, and its own (non-progressbar) semantics. The components share the rail recipe but own their size variables independently.
 
 **State boundaries:**
 

package/dist/docs/components/strong.md

@@ -105,7 +105,7 @@ Rules:
 
 ## Playground demo spec
 
-`Strong` is registered in `apps/playground/lib/registry/typography.tsx` under the `strong` key. The registry entry imports `strongPropDefs` and renders the component with a sample strong span. Per-component route: `/docs/strong`.
+`Strong` is registered in `apps/playground/lib/registry/typography.tsx` under the `strong` key. The registry entry imports `strongPropDefs` and renders the component with a sample strong span. Per-component route: `/docs/strong`. The live example uses English and Russian sentence context plus a slotted span.
 
 **Default story:**