@d4gger/design-system 3.0.1 → 4.0.1

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

@@ -46,14 +46,14 @@ A panel and cabinet shell navigation surface. The DS `Sidebar` exposes a provide
 | `Sidebar.MenuBadge` | `<span>` | `dsx-sidebar__menu-badge` plus the text Badge classes or the `--ring` / `--accent` modifier + `data-slot="sidebar-menu-badge"` + `data-state` | A count, proportional usage ring, or quiet accent value. Remains in the DOM but is visually hidden when the panel collapses. |
 | `Sidebar.MenuAction` | `<button>` (or `Slot` child when `asChild`) | `dsx-sidebar__menu-action dsx-button` + `data-slot="sidebar-menu-action"` + `data-state` | An action button revealed on hover. |
 | `Sidebar.MenuButton` | `<button>` (or `Slot` child when `asChild`) | `dsx-sidebar__menu-button dsx-button` + `dsx-sidebar__menu-button-text` (when children are a string or number) + `data-slot="sidebar-menu-button"` + `data-active` + `data-state` | A menu button. |
-| `Sidebar.MenuSkeleton` | `<div>` | `dsx-sidebar__menu-skeleton` + `dsx-skeleton dsx-skeleton--circle` (icon) + `dsx-skeleton dsx-skeleton--text-line` (label) + `data-slot="sidebar-menu-skeleton"` + `data-show-icon` + `data-state` | A loading placeholder for a menu row. |
+| `Sidebar.MenuSkeleton` | `<div>` | `dsx-sidebar__menu-skeleton` + `dsx-skeleton dsx-skeleton--circle` (icon) + `dsx-skeleton dsx-skeleton--text-line` (label) + `data-slot="sidebar-menu-skeleton"` + `data-show-icon` + `data-state` | A loading placeholder for a menu row. Inside a `Sidebar.MenuItem` (a flex row) it takes the item's width (`.dsx-sidebar__menu-item > .dsx-sidebar__menu-skeleton { flex: 1 }`); on its own it is as wide as its parent. |
 | `Sidebar.MenuSub` | `<ul>` | `dsx-sidebar__menu-sub` + `data-slot="sidebar-menu-sub"` + `data-state` | A nested menu list. |
 | `Sidebar.MenuSubItem` | `<li>` | `dsx-sidebar__menu-sub-item` + `data-slot="sidebar-menu-sub-item"` + `data-state` | A nested menu row. |
 | `Sidebar.MenuSubButton` | `<button>` (or `Slot` child when `asChild`) | `dsx-sidebar__menu-sub-button dsx-button` + `dsx-sidebar__menu-button-text` (when children are a string or number) + `data-slot="sidebar-menu-sub-button"` + `data-active` + `data-state` | A nested menu button. |
 | `Sidebar.MenuSubTrigger` | `<button>` (or `Slot` child when `asChild`) | `dsx-sidebar__menu-sub-trigger dsx-button` + `dsx-sidebar__menu-sub-trigger-chevron` (`chevron-right`, rotates 90° on open) + `data-slot="sidebar-menu-sub-trigger"` + `data-state` (`open` \| `closed`) + `aria-expanded` | The parent button that toggles a `Sidebar.MenuSub`. Composes the public `Collapsible` primitive. Decided in Direction #4 Q5; `mode="both"` is rejected. |
 | `Sidebar.Separator` | `<div role="separator" aria-orientation="horizontal">` | `dsx-sidebar__separator dsx-separator dsx-separator--decorative` + `data-slot="sidebar-separator"` + `data-state` | A horizontal divider. |
 | `Sidebar.Trigger` | `<button aria-label="Expand sidebar" \| "Collapse sidebar" \| "Pin sidebar" \| "Unpin sidebar">` | `dsx-sidebar__trigger dsx-button` + `dsx-button__icon` (panel-state glyph) + `dsx-sidebar__trigger-label` (text) + `data-slot="sidebar-trigger"` + `data-state` | A toggle button used inside the panel or the inset. Hover-preview mode uses dashed/solid panel semantics instead of directional chevrons. |
-| `Sidebar.mobile-trigger` (internal) | `<button aria-label="Open sidebar">` | `dsx-sidebar__mobile-trigger` + `data-slot="sidebar-mobile-trigger"` | The mobile sheet trigger, mounted by `Sidebar.Provider` when `mobile="sheet"` and the viewport is below `mobileBreakpoint`. |
+| `Sidebar.mobile-trigger` (internal) | `<button aria-label="Open sidebar">` | `dsx-sidebar__mobile-trigger` + `data-slot="sidebar-mobile-trigger"` | The mobile sheet trigger, mounted by `Sidebar.Provider` when `mobile="sheet"` and the viewport is below `mobileBreakpoint`, unless `mobileTrigger` is `false`. |
 | `Sidebar.SkipLink` | `<a>` | `dsx-sidebar__skip-link` | Focus-revealed skip link targeting `targetId` (`main` by default). |
 
 The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset` and `Sidebar.Trigger`. The source exports the full set through `Object.assign` on `Sidebar` (alias of `Sidebar.Root`), and also re-exports the named components individually. The spec records the runtime shape; the roster's slot list is the contract for canonical anatomy.
@@ -71,9 +71,11 @@ The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset`
 | `hoverExpand` | `boolean` | `false` | no | In icon mode, temporarily expands the collapsed rail on pointer hover or keyboard focus. The preview overlays the inset and never changes the persisted preference. `Escape` closes a keyboard-opened preview. | no |
 | `previewOpen` | `boolean` | `false` | no | Holds the temporary icon-mode preview open for a consumer-owned flyout or other adjacent interaction. It does not change the persisted preference. | no |
 | `mobile` | `'sheet' \| 'drawer' \| 'none'` | `'sheet'` | no | Mobile fallback mode. `sheet` mounts a `Sheet` trigger; `none` skips the mobile fallback. | no |
+| `mobileTrigger` | `boolean` | `true` | no | Whether the provider mounts its floating "Open sidebar" button in mobile sheet mode. Set `false` when the app opens the drawer from its own control, a header button or a dock item (`BottomDock`'s "More"), with `useSidebar().setMobileSheetOpen(true)`. The drawer, its own close button and its focus handling are unchanged; with `mobile="none"` the prop has no effect. Not written to the DOM. | no |
 | `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 |
 
@@ -106,7 +108,7 @@ The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset`
 
 ### `Sidebar.MenuSubTrigger`
 
-The parent button that toggles a `Sidebar.MenuSub`. Composes the public `Collapsible` primitive: the open state lives on a consumer-owned `Collapsible` root (`asChild` over the `MenuItem`), this trigger owns the click toggle and mirrors `open` / `onOpenChange` for hover timers, Arrow keys, and auto-open. `CollapsibleTrigger` is deliberately NOT in the composition (its span + chevron pair breaks Radix Slot's single-child rule). `CollapsibleContent` takes `forceMount` so the closed sub stays in the DOM and `openOnActive` can see an active descendant on mount. Direction #4 Q5 verdict: `click` is the default mode, `hover` is opt-in per trigger, `both` is rejected (hover/click race conditions). Hover mode is suppressed on coarse pointers and degrades to tap-to-toggle.
+The parent button that toggles a `Sidebar.MenuSub`. Composes the public `Collapsible` primitive: the open state lives on a consumer-owned `Collapsible` root (`asChild` over the `MenuItem`), this trigger owns the click toggle and mirrors `open` / `onOpenChange` for hover timers, Arrow keys, and auto-open. `CollapsibleTrigger` is deliberately NOT in the composition (its span + chevron pair breaks Radix Slot's single-child rule). `CollapsibleContent` takes `forceMount` so the closed sub stays in the DOM and `openOnActive` can see an active descendant on mount; a sub that mounts closed is hidden at rest by the Collapsible's motion styles (`collapsible.md` § Force-mounted content, G-14), and a collapsed one is out of the tab order. The trigger is a row like any `MenuButton` (same padding, icon column, fill and type: G-13). Direction #4 Q5 verdict: `click` is the default mode, `hover` is opt-in per trigger, `both` is rejected (hover/click race conditions). Hover mode is suppressed on coarse pointers and degrades to tap-to-toggle.
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
@@ -186,10 +188,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.
@@ -215,7 +218,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` |
@@ -265,6 +269,8 @@ Rules:
 
 - The CSS file collapses the panel through the `data-state` attribute. The mobile sheet fallback is mounted by `Sidebar.Provider` based on `window.innerWidth` and `matchMedia('(pointer: coarse)')`, gated by `mobileBreakpoint` and the `mobile` prop.
 - The component does not write `@media` rules; the mobile behavior is runtime-driven, not CSS-driven.
+- `dsx-sidebar__menu-sub-trigger` shares the base rule of `dsx-sidebar__menu-button` (display, `--dsx-space-sm` padding, transparent fill, no border, label type, `--dsx-shadow-focus-ring` on `:focus-visible`), so a parent row and a plain row have one geometry: the icon in the same column, no browser button fill when the parent is neither open nor active. Open and active states are the parent's own rules after it.
+- The mobile drawer (`dsx-sidebar__mobile-sheet`) is flush with the viewport on three sides, so it keeps the structural border on its free inline-end edge only (`border-block-width: 0`, `border-inline-start-width: 0`), and it does not scroll itself (`overflow: hidden`): the nav fills it (`height: 100%`) and its content area owns the scrolling. The base dialog surface that Drawer shares draws the border all round, which is right for a floating panel and wrong for a full-height sheet.
 
 **Reduced motion:**
 
@@ -284,9 +290,18 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Panel width (icon collapsed) | `var(--dsx-sidebar-width-collapsed)` | Persistent slim icon rail. |
 | Panel preview layout | `calc(var(--dsx-sidebar-width-collapsed) - var(--dsx-sidebar-width))` | Negative inline-end margin lets temporary expansion overlay rather than reflow the inset. |
 | Panel background | `var(--dsx-color-surface)` | Panel surface. |
-| Panel ambient effect | `var(--dsx-color-accent-9)` mixed with transparency | Optional subscription-aware accent wash without a literal starfield. |
+| Panel ambient effect | `var(--dsx-color-accent-9)` mixed with transparency at `var(--dsx-effect-ambient-strength)` (10% in dark, 16% in light), from the top-left corner, plus a second source at the foot: an ellipse anchored to the bottom edge at 0.9× the same strength | Optional subscription-aware accent wash without a literal starfield. The strength is theme-aware (G-16): the same wash read about half as strong on the pale light surface. The foot glow (G-17, 2026-10-05) lights the lower half the corner radial never reached (about 35% of the panel) and leaves the nav a calm middle. |
+| Trigger | transparent fill, `inset 0 0 0 var(--dsx-border-width-sm) var(--dsx-color-accent-7)` ring, `var(--dsx-color-accent-11)` glyph; hover fill `var(--dsx-color-accent-3)` and ring `var(--dsx-color-accent-8)` | A quiet outline (G-18, 2026-10-05). The raised disc it replaced (`surface-raised` fill, drop shadow) vanished on dark, where shadows do not read, and on the tinted panel. Scale jobs: border step 7, text step 11, one step up on hover. The focus ring still replaces the ring; the pin / unpin glyphs of hover-expand mode live in the same button. |
+| Active row wash (light) | `var(--dsx-color-accent-4)` on `MenuButton`, `MenuSubButton` and `MenuSubTrigger` when `data-active='true'`, under `:where([data-dsx-theme='light'])`; dark keeps `accent-3` at 50% | G-19 (2026-10-05): accent-3 at 50% over a tinted light panel is nearly the panel's colour, so in light the row was marked only by its underline and text. Step 4 is the scale's soft-component step. |
 | 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. |
@@ -358,7 +373,7 @@ Rules:
 - Offcanvas collapsed content is removed from interaction and the accessibility
   tree. The external recovery rail owns `aria-controls` and `aria-expanded`.
 - `Sidebar.GroupLabel` is a non-semantic `<div>`; consumers can set `role="heading"` plus `aria-level` when the label needs to be a heading.
-- The mobile sheet trigger (when mounted by `Sidebar.Provider`) is a button with `aria-label="Open sidebar"`.
+- The mobile sheet trigger (when mounted by `Sidebar.Provider`) is a button with `aria-label="Open sidebar"`. With `mobileTrigger={false}` the app's own control carries that role and must be a real button with its own accessible name. The drawer's own labels ("Close navigation", "Navigation") are fixed English strings today.
 - `useSidebar` returns a no-op fallback when the consumer renders a sidebar slot outside `Sidebar.Provider`, so the component never throws.
 
 **Keyboard:**
@@ -392,6 +407,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:**
@@ -402,19 +419,26 @@ 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:**
 
 - Renders a `MenuButton` with `isActive` and asserts `data-active="true"` plus the `dsx-sidebar-menu-button-active` class. Toggles the panel via the `Rail` click and asserts the `data-state` flips on the provider, the panel, the header, the footer, and the content. Renders a `MenuBadge` with text `12` and asserts the badge stays in the DOM when the panel collapses while CSS visually hides it.
 - Renders `MenuBadge variant="accent"` as quiet numeric metadata without the filled Badge surface; `variant="ring"` remains reserved for a genuine `value / max` ratio.
 
+**Mobile story:**
+
+- At a phone width in `mobile="sheet"` mode, asserts the floating "Open sidebar" button is mounted by default, is absent with `mobileTrigger={false}` (checked next to a default provider, because the drawer's chunk is lazy), and that an app control calling `useSidebar().setMobileSheetOpen(true)` still opens the drawer. The registry has no phone-width fixture for this: the drawer is a portal bound to the window, so `Sidebar.test.tsx` and the `frontend` user-shell render carry it. `src/test/styles/sidebar-mobile-sheet.test.ts` guards the sheet's three CSS rules (free-edge border only, no own scroll, nav sized to the sheet); jsdom has no layout, so the scrollbar and outline themselves are proved in the browser (`docs/feature/design-system/sidebar-sheet-chrome/verification.md`).
+
 **Composition story:**
 
 - Renders a `Sidebar.Content` with two `Sidebar.Group` blocks, each containing a `GroupLabel`, a `GroupContent`, and a `Menu` with `MenuItem` and `MenuButton` rows. Adds a `Sidebar.Separator` between the groups and a `Sidebar.MenuSub` with `Sidebar.MenuSubItem` and `Sidebar.MenuSubButton` rows in one of the menus. Asserts every slot renders the right `dsx-sidebar__*` class.
+- `src/test/styles/sidebar-sub-trigger-row.test.ts` guards the shared row base of `MenuButton` and `MenuSubTrigger` (padding, fill, border, focus ring): the parent row sat 8px right of the others and showed a grey button fill when idle (G-13, 2026-10-05). `Collapsible.test.tsx` guards the closed force-mounted panel (G-14).
+- `src/test/styles/shell-look-pass.test.ts` guards the ambient wash's second source (G-17), the outline trigger and the order of its focus ring (G-18), and the light active-row wash with its (0,2,0) selector and source order (G-19); `apps/playground/tests/user-shell-frame-browser.spec.ts` measures all three on the user-shell frame for Rift, Warp and Ray in both themes.
 
 **Token story:**
 
-- Sidebar does not own a `data-accent-color` hook, so the token story is omitted. The active menu button background tracks `var(--dsx-color-accent-surface)` and the active text tracks `var(--dsx-color-accent-indicator)`, which are theme-aware.
+- Sidebar does not own a `data-accent-color` hook, so the token story is omitted. The active row's wash is `var(--dsx-color-accent-3)` at 50% in dark and `var(--dsx-color-accent-4)` in light (G-19), and its text tracks `var(--dsx-color-accent-indicator)`, which is theme-aware.
 
 **A11y story:**
 
@@ -427,6 +451,7 @@ Rules:
 | `defaultExpanded` | boolean | `true` |
 | `hoverExpand` | boolean | `false` |
 | `previewOpen` | boolean | `false` |
+| `variant` | select | `default` |
 
 ## Wiring notes
 
@@ -447,7 +472,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-5)` | Spotlight: below dialogs, above all menus (B4 Q3). |
-| Toast gap | `var(--dsx-space-md)` | Gap between icon, title, description, and buttons. |
+| 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/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,7 +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 vertical rail rules in `stepper.css` are the layout engine of record; keep them in sync with `timeline.css`.
+- 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:**