@d4gger/design-system 2.7.0 → 3.0.1

package/dist/docs/{sidebar.md → components/sidebar.md}

@@ -3,17 +3,9 @@ title: Sidebar
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/sidebar/Sidebar.tsx
-css_path: packages/d4gger-design-system/src/styles/components/sidebar.css
-props_path: packages/d4gger-design-system/src/components/sidebar/sidebar.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Sidebar.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/navigation.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - "@radix-ui/react-slot (powers `asChild` on `Sidebar.Inset`, `Sidebar.MenuAction`, and `Sidebar.MenuButton`)"
-  - _internal/helpers/extractProps (turns the prop defs on `Sidebar`, `Sidebar.Inset`, `Sidebar.MenuAction`, `Sidebar.MenuButton`, and `Sidebar.MenuSkeleton` into merged class + style output)
-  - Icon (the `chevron-left` / `chevron-right` glyphs on the rail and trigger; the `menu` glyph on the mobile sheet trigger)
+  - Icon (the `chevron-left` / `chevron-right` glyphs for ordinary expansion, `panel-left-dashed` / `panel-left` for hover-preview docking, and `menu` for the mobile sheet trigger)
   - ScrollArea (wraps `Sidebar.Content` so the scroll surface matches the design system scrollbar)
   - Sheet (provides the mobile sheet fallback when the provider's `mobile` prop is `sheet`)
   - Badge (the `dsx-badge` / `dsx-badge--secondary` / `dsx-badge--sm` classes merged into `Sidebar.MenuBadge`)
@@ -23,11 +15,11 @@ depends_on:
 
 # Sidebar
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
-A panel and cabinet shell navigation surface. The DS `Sidebar` exposes a provider that owns the expanded / collapsed state and the persisted preference, a root that renders the panel, and a full set of subcomponents for headers, content, footers, groups, menus, submenus, badges, actions, skeletons, separators, a rail, a trigger, and a mobile sheet fallback. The roster calls it a panel and cabinet shell, not a route registry; routing, auth, nav data, and permissions are app-owned.
+A panel and cabinet shell navigation surface. The DS `Sidebar` exposes a provider that owns the expanded / collapsed state and the persisted preference, an optional slim-rail hover/focus preview that never overwrites that preference, a root that renders the panel, and a full set of subcomponents for headers, content, footers, groups, menus, submenus, badges, actions, skeletons, separators, a rail, a trigger, and a mobile sheet fallback. The roster calls it a panel and cabinet shell, not a route registry; routing, auth, nav data, and permissions are app-owned.
 
 ## Anatomy & slots
 
@@ -37,7 +29,7 @@ A panel and cabinet shell navigation surface. The DS `Sidebar` exposes a provide
 
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
-| `Sidebar.Provider` | `<div data-slot="sidebar-provider">` | `dsx-sidebar-provider` + `data-state` (`expanded` \| `collapsed`) + `data-collapsed` | The shell that owns the persisted expanded / collapsed state. Wraps the children in a `Sheet` when the device is mobile and the `mobile` prop is `sheet`. |
+| `Sidebar.Provider` | `<div data-slot="sidebar-provider">` | `dsx-sidebar-provider` + `data-state` (`expanded` \| `collapsed`) + `data-collapsed` | The shell that owns the persisted expanded / collapsed state. In mobile sheet mode, the Sidebar root moves into a `Sheet` while sibling inset content remains mounted. |
 | `Sidebar` (alias `Sidebar.Root`) | `<nav aria-label="Sidebar" data-slot="sidebar">` | `dsx-sidebar` + `data-state` + `data-collapsed` | The mounted panel. Offcanvas collapse adds `inert` and `aria-hidden`. |
 | `Sidebar.Inset` | `<main>` (or `Slot` child when `asChild`) | `dsx-sidebar__inset` + `data-slot="sidebar-inset"` + `data-state` | The main content area that sits next to the panel. |
 | `Sidebar.Rail` | `<button aria-label="Collapse sidebar" \| "Expand sidebar">` | `dsx-sidebar__rail` + `data-slot="sidebar-rail"` + `data-state` + `chevron-left` / `chevron-right` icon | The draggable edge that toggles the panel. |
@@ -51,15 +43,16 @@ A panel and cabinet shell navigation surface. The DS `Sidebar` exposes a provide
 | `Sidebar.GroupContent` | `<div>` | `dsx-sidebar__group-content` + `data-slot="sidebar-group-content"` + `data-state` | The menu body inside a group. |
 | `Sidebar.Menu` | `<ul>` | `dsx-sidebar__menu` + `data-slot="sidebar-menu"` + `data-state` | The list of menu items. |
 | `Sidebar.MenuItem` | `<li>` | `dsx-sidebar__menu-item` + `data-slot="sidebar-menu-item"` + `data-state` | A single row. |
-| `Sidebar.MenuBadge` | `<span>` | `dsx-sidebar__menu-badge dsx-badge dsx-badge--secondary dsx-badge--sm` + `data-slot="sidebar-menu-badge"` + `data-state` | A count or status badge. Collapses to a small dot when the panel collapses. |
+| `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.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">` | `dsx-sidebar__trigger dsx-button` + `dsx-button__icon` (chevron) + `dsx-sidebar__trigger-label` (text) + `data-slot="sidebar-trigger"` + `data-state` | A toggle button used inside the panel or the inset. |
+| `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.SkipLink` | `<a>` | `dsx-sidebar__skip-link` | Focus-revealed skip link targeting `targetId` (`main` by default). |
 
@@ -75,16 +68,21 @@ The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset`
 | `storageKey` | `string` | `'dsx-sidebar-state'` | no | localStorage or cookie key for the persisted state. Ignored when `storage` is `memory`. | no |
 | `storage` | `'localStorage' \| 'cookie' \| 'memory'` | `'localStorage'` | no | Persistence backend. | no |
 | `toggleShortcut` | `boolean` | `true` | no | Enables the global `Ctrl+B` / `Cmd+B` keyboard shortcut to toggle the panel. | no |
+| `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 |
 | `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 |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-sidebar-provider`. | no |
-| `children` | `React.ReactNode` | `undefined` | no | The sidebar children. When `mobile="sheet"` and the device is mobile, the children are mounted inside the `Sheet.Content` instead of inline. | 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 |
 
 ### `Sidebar` (alias `Sidebar.Root`)
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `defaultExpanded` | `boolean` | `true` | no | Initial expanded state when the root is rendered without a `Sidebar.Provider`. The `dsx-sidebar-default-expanded` class is also merged. | no |
+| `effect` | `'none' \| 'ambient'` | `'none'` | no | Optional token-driven accent wash on the panel surface. `ambient` remains restrained enough for navigation text in light and dark themes. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-sidebar`. | no |
 | `children` | `React.ReactNode` | `undefined` | no | The sidebar slots. | no |
 
@@ -106,6 +104,28 @@ The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset`
 | `className` | `string` | `undefined` | no | Extra classes appended to the slot class. | no |
 | `children` | `React.ReactNode` | (required) | yes | The button content. When the children are a string or number and `asChild` is not set, the content is wrapped in a `<span class="dsx-sidebar__menu-button-text" data-slot="sidebar-menu-button-text">`. | no |
 
+### `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.
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `mode` | `'click' \| 'hover'` | provider `defaultSubmenuMode` (`'click'`) | no | Toggle mode. `hover` opens on pointer enter after `hoverOpenDelay` and closes on pointer leave after `hoverCloseDelay`; clicking still toggles. | no |
+| `hoverOpenDelay` | `number` | `150` | no | Hover-open delay in ms. Only used when `mode` is `'hover'`. | no |
+| `hoverCloseDelay` | `number` | `250` | no | Hover-close delay in ms; longer than open so the pointer can cross the gap into the sub. Only used when `mode` is `'hover'`. | no |
+| `openOnActive` | `boolean` | provider `submenuOpenOnActive` (`true`) | no | Auto-opens when any descendant `Sidebar.MenuSubButton` has `isActive`. | no |
+| `open` | `boolean` | `undefined` | no | Controlled open state. | no |
+| `defaultOpen` | `boolean` | `undefined` | no | Uncontrolled initial open state. | no |
+| `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Controlled-mode change handler. | no |
+| `showChevron` | `boolean` | `true` | no | Renders the trailing `chevron-right` that rotates to down on open. Hidden in icon mode automatically. | no |
+| `isActive` | `boolean` | `false` | no | Marks the parent as the current page. Same meaning as `Sidebar.MenuButton`. | no |
+| `disabled` | `boolean` | `false` | no | Forwards to the Collapsible root. | no |
+| `tooltip` | `string` | `undefined` | no | Required when `asChild` is set (same rule as `Sidebar.MenuButton`). | no |
+| `asChild` | `boolean` | `false` | no | Renders the host through `Slot`. When `asChild` is set, `type` is omitted from the host. | 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-sidebar__menu-sub-trigger`. | no |
+| `children` | `React.ReactNode` | (required) | yes | The trigger content (icon + label). | no |
+
 ### `Sidebar.MenuAction`
 
 | Prop | Type | Default | Required | Description | Responsive |
@@ -128,6 +148,7 @@ The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset`
 |---|---|---|---|---|---|
 | `collapsedLabel` | `string` | `'Expand sidebar'` | no | `aria-label` and visible text when the panel is collapsed. | no |
 | `expandedLabel` | `string` | `'Collapse sidebar'` | no | `aria-label` and visible text when the panel is expanded. | no |
+| `iconOnly` | `boolean` | `false` | no | Visually hides the trigger label while preserving the accessible name. Intended for a visible compact trigger in a sidebar header. | no |
 | `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | no | Forwarded to the host `<button>`. | no |
 | `onClick` | `MouseEventHandler` | `undefined` | no | Click handler. The provider's toggle only fires if `event.defaultPrevented` is `false`. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-sidebar__trigger`. | no |
@@ -140,6 +161,17 @@ The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset`
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-sidebar__group-action`. | no |
 | `children` | `React.ReactNode` | (required) | yes | The action content. | no |
 
+### `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 |
+| `value` | `number` | `undefined` | no | Current value for the `ring` variant. | no |
+| `max` | `number` | `undefined` | no | Maximum value for the `ring` variant. Must be greater than zero; otherwise the component falls back to text. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Badge content for `text` and `accent`. | no |
+
 ### `Sidebar.Rail`
 
 Standard `<button>` props plus the click handler. The rail toggles the panel when the click is not `defaultPrevented`. The `aria-label` flips between `Expand sidebar` and `Collapse sidebar` based on the current `expanded` state.
@@ -163,6 +195,10 @@ Rules:
 - `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.
 - `Sidebar.Provider` debounces the resize handler (100 ms) and reads `window.matchMedia('(pointer: coarse)')` to detect coarse pointers. Mobile mode is `mobile !== 'none' && isMobile`.
 - Persistence is hydration-safe: the initial read runs in `useLayoutEffect` and the write runs in `useEffect`. The `memory` storage backend skips both the read and the write, so the state stays in React state only.
+- Panel transitions remain disabled until persisted storage hydration has committed. In hover-preview mode, pinning never transitions panel width: it animates only the preview's negative layout margin back to zero so the inset moves out smoothly without a 72px-to-272px panel sweep. A consumer-owned `previewOpen` interaction holds the existing preview open without changing layout reservation or the persisted pin preference.
+- `hoverExpand` is active only for desktop icon mode. Pointer entry or focus within the panel opens a temporary preview; pointer exit or focus leaving the panel closes it. The preview state is separate from the persisted expanded preference.
+- `MenuSubTrigger` hover mode is suppressed on coarse pointers (`(pointer: coarse)`) and degrades to tap-to-toggle, so touch users never get a stuck-open sub.
+- In icon-collapsed mode, a `MenuSubTrigger` with children renders a `DropdownMenu` flyout instead of the inline Collapsible (the shadcn-admin collapsed-dropdown pattern), so the icon rail keeps access to sub-items.
 
 ## CSS class contract
 
@@ -174,7 +210,14 @@ Rules:
 |---|---|---|---|
 | `data-state` | `expanded`, `collapsed` | `.dsx-sidebar[data-state='collapsed']`, plus `data-state` on every slot | `sidebar.css` |
 | `data-collapsed` | `true`, `false` | (paired with `data-state` for explicit collapsed semantics) | `sidebar.css` |
+| `data-hover-expand` | `true`, `false` | Enables the slim-rail hover/focus preview selectors. | `sidebar.css` |
+| `data-preview-expanded` | `true`, `false` | Distinguishes a temporary overlay preview from a manually pinned expanded state. | `sidebar.css` |
+| `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-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` |
 | `data-slot` | `sidebar-*` | (data-attribute hook used by the collapsed CSS to hide non-trigger children) | `sidebar.css` |
 | `data-persistent` | `true` | (data-attribute hook; elements with `data-persistent="true"` stay visible when the panel collapses) | `sidebar.css` |
@@ -184,6 +227,7 @@ Rules:
 | Source prop | Class | CSS file |
 |---|---|---|
 | `defaultExpanded` on `Provider` | `dsx-sidebar-provider-default-expanded` | `sidebar.css` |
+| `hoverExpand` on `Provider` | `dsx-sidebar-provider-hover-expand` | `sidebar.css` |
 | `defaultExpanded` on `Root` | `dsx-sidebar-default-expanded` | `sidebar.css` |
 | `isActive` on `MenuButton` / `MenuSubButton` | `dsx-sidebar-menu-button-active` | `sidebar.css` |
 | `showIcon` on `MenuSkeleton` | `dsx-sidebar-menu-skeleton-icon` | `sidebar.css` |
@@ -205,6 +249,7 @@ Rules:
 | `Sidebar.GroupContent` | `dsx-sidebar__group-content` | `sidebar.css` |
 | `Sidebar.Menu` | `dsx-sidebar__menu` | `sidebar.css` |
 | `Sidebar.MenuItem` | `dsx-sidebar__menu-item` | `sidebar.css` |
+| `Sidebar.MenuSubTrigger` | `dsx-sidebar__menu-sub-trigger` + `dsx-button` + `dsx-sidebar__menu-sub-trigger-chevron` | `sidebar.css` |
 | `Sidebar.MenuBadge` | `dsx-sidebar__menu-badge` (+ `dsx-badge dsx-badge--secondary dsx-badge--sm`) | `sidebar.css` |
 | `Sidebar.MenuAction` | `dsx-sidebar__menu-action` (+ `dsx-button`) | `sidebar.css` |
 | `Sidebar.MenuButton` | `dsx-sidebar__menu-button` (+ `dsx-button` + optional `dsx-sidebar__menu-button-text`) | `sidebar.css` |
@@ -236,9 +281,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Provider min-height | `100dvh` (CSS keyword) | Full-height shell. |
 | Panel width | `var(--dsx-sidebar-width, 256px)` | Expanded panel width with boot fallback. |
 | Panel width (offcanvas collapsed) | `0` | Mounted zero-width panel. |
-| Panel width (icon collapsed) | `var(--dsx-size-2xl, 48px)` | Persistent icon rail. |
+| 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 border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` (light: `var(--dsx-color-outline-variant)`) | Panel edge. |
+| 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. |
 | Panel motion duration | `var(--dsx-motion-duration-normal, 250ms)` | Width transition. |
 | Panel motion easing | `var(--dsx-motion-easing-standard, ease)` | Width easing. |
@@ -250,10 +297,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Rail hover color | `var(--dsx-color-on-surface)` | Rail hover color. |
 | Rail focus ring | `var(--dsx-shadow-focus-ring)` | `:focus-visible` ring. |
 | Header padding | `var(--dsx-space-md)` | Header gutter. |
-| Header border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Header bottom edge. |
+| Header border | `none` (CSS keyword) | Keeps the header visually continuous with the panel. |
 | Content padding | `var(--dsx-space-sm)` | Content gutter. |
 | Footer padding | `var(--dsx-space-md)` | Footer gutter. |
-| Footer border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Footer top edge. |
+| Footer border | `none` (CSS keyword) | Keeps the account footer visually continuous with the panel. |
 | Group gap | `var(--dsx-space-md)` | Gap between groups. |
 | Group label padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Group label gutter. |
 | Group label typography | `var(--dsx-typography-label-small-*)` (text-transform: uppercase; letter-spacing: `0.05em`) | Group label font. |
@@ -266,10 +313,12 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Menu button border radius | `var(--dsx-rounded-sm)` | Menu button corner roundness. |
 | Menu button typography | `var(--dsx-typography-label-large-*)` | Menu button font. |
 | Menu button hover background | `var(--dsx-effect-hover-ghost)` | Menu button hover. |
-| Menu button active background | `var(--dsx-effect-hover-primary)` | Active menu button. |
-| Menu button active color | `var(--dsx-color-primary)` | Active menu button text. |
-| Menu button active accent | `var(--dsx-color-primary)` (inset 3px shadow) | Active menu button edge. |
-| Menu sub padding | `0 0 0 var(--dsx-space-lg)` | Submenu indent. |
+| 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. 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. |
 | Menu sub button padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Submenu button gutter. |
 | Menu sub button color | `var(--dsx-color-on-surface-variant)` | Submenu button text. |
@@ -287,8 +336,9 @@ Rules:
 
 | Region | Token | Default | Reduced |
 |---|---|---|---|
-| Panel width | `var(--dsx-motion-duration-normal, 250ms) var(--dsx-motion-easing-standard, ease)` | Token-driven width transition | `transition: none`; focus transfer is immediate |
+| Panel width/layout | `var(--dsx-motion-duration-normal, 250ms) var(--dsx-motion-easing-standard, ease)` | Token-driven hover-preview and ordinary collapse transition; docking holds width stable and animates only layout margin | `transition: none`; focus transfer is immediate |
 | Menu action opacity | `var(--dsx-motion-duration-fast) var(--dsx-motion-easing-standard)` | 150ms ease | (same as above) |
+| Accent badge signal | `var(--dsx-motion-duration-shimmer) var(--dsx-motion-easing-in-out)` | Alternating glow pulse | `animation: none` |
 
 Rules:
 
@@ -303,7 +353,8 @@ Rules:
 - `Sidebar.Separator` is `role="separator"` with `aria-orientation="horizontal"`.
 - `Sidebar.Menu` is `role="list"`; `Sidebar.MenuItem` is `role="listitem"`.
 - `Sidebar.MenuButton` and `Sidebar.MenuSubButton` are buttons (`role="button"`). The active button carries `data-active="true"`. The text wrapper (`dsx-sidebar__menu-button-text`) is a non-semantic `<span>`.
-- `Sidebar.Rail` and `Sidebar.Trigger` are buttons with `aria-label` that flips between `Expand sidebar` and `Collapse sidebar` based on the current `expanded` state.
+- `Sidebar.MenuSubTrigger` is a button with `aria-expanded` and `data-state="open" | "closed"`. The trailing chevron is decorative (`aria-hidden`).
+- `Sidebar.Rail` flips between `Expand sidebar` and `Collapse sidebar`. `Sidebar.Trigger` uses those labels for ordinary collapse mode and `Pin sidebar` / `Unpin sidebar` while hover-preview docking is enabled.
 - 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.
@@ -315,9 +366,14 @@ Rules:
 | Key | Action |
 |---|---|
 | `Tab` | Moves focus through the panel and the inset. |
-| `Enter`, `Space` | Activates the focused button. |
+| `Enter`, `Space` | Activates the focused button. On a `MenuSubTrigger`, toggles the sub (Radix Collapsible trigger behavior). |
+| `ArrowRight` (`MenuSubTrigger` focused, sub closed) | Opens the sub and moves focus to the first `MenuSubButton`. |
+| `ArrowLeft` (`MenuSubButton` focused) | Closes the sub and returns focus to the parent `MenuSubTrigger`. |
+| `ArrowDown` (`MenuSubTrigger` focused, sub open) | Moves focus to the first `MenuSubButton` (extends the existing roving-tabindex handler). |
+| `Escape` (sub open) | Closes the sub and returns focus to the parent `MenuSubTrigger` (extends the existing `SidebarMenuSub` Escape-to-parent handler). |
 | `Ctrl+B` / `Cmd+B` | Toggles the panel when `Sidebar.Provider` mounts and `toggleShortcut` is `true`. The shortcut is global; the listener lives on `document`. |
 | `Escape` (mobile sheet) | Closes the sheet when `mobile="sheet"` and the device is mobile. |
+| `Escape` (hover preview) | Closes a temporary desktop icon-rail preview without changing the persisted preference. |
 
 **Focus:**
 
@@ -330,7 +386,7 @@ Rules:
 
 **Color and meaning:**
 
-- The active menu button is communicated by `data-active="true"`, the `dsx-sidebar-menu-button-active` modifier, the active background, the active text color, and the inset accent shadow. The collapsed badge collapses to a small dot; the text content is still announced to screen readers via the original text.
+- The active menu button is communicated by `data-active="true"`, the `dsx-sidebar-menu-button-active` modifier, the active background, and the active text color. Collapsed badges remain in the DOM but are visually hidden so the compact rail retains one aligned icon column.
 
 **Naming:**
 
@@ -345,10 +401,12 @@ Rules:
 **Variant story:**
 
 - 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.
 
 **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 (it collapses to a dot visually but the text is still announced).
+- 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.
 
 **Composition story:**
 
@@ -356,7 +414,7 @@ Rules:
 
 **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-effect-hover-primary)` and the active text tracks `var(--dsx-color-primary)`, which are theme-aware.
+- 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.
 
 **A11y story:**
 
@@ -367,6 +425,8 @@ Rules:
 | Prop | Control | Default |
 |---|---|---|
 | `defaultExpanded` | boolean | `true` |
+| `hoverExpand` | boolean | `false` |
+| `previewOpen` | boolean | `false` |
 
 ## Wiring notes
 
@@ -387,7 +447,7 @@ Rules:
 
 **State boundaries:**
 
-- Owned by `Sidebar`: the expanded / collapsed state, 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` and `data-collapsed` 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`, and `data-pinned-state` 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/{skeleton.md → components/skeleton.md}

@@ -3,19 +3,12 @@ title: Skeleton
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/skeleton/Skeleton.tsx
-css_path: packages/d4gger-design-system/src/styles/components/skeleton.css
-props_path: packages/d4gger-design-system/src/components/skeleton/skeleton.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Skeleton.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Skeleton
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{slider.md → components/slider.md}

@@ -3,20 +3,13 @@ title: Slider
 status: canonical
 category: Primitives
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/slider/Slider.tsx
-css_path: packages/d4gger-design-system/src/styles/components/slider.css
-props_path: packages/d4gger-design-system/src/components/slider/slider.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Slider.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/forms.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - '@radix-ui/react-slider (Root, Track, Range, Thumb — internal)'
 ---
 
 # Slider
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{slot.md → components/slot.md}

@@ -3,20 +3,13 @@ title: Slot
 status: canonical
 category: Primitives
 archetype: radix-wrapper
-package_path: packages/d4gger-design-system/src/components/slot/Slot.tsx
-css_path: (none — Slot is a passthrough utility)
-props_path: packages/d4gger-design-system/src/components/slot/slot.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Slot.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/utility.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - '@radix-ui/react-slot (Slot)'
 ---
 
 # Slot
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 

package/dist/docs/{sonner.md → components/sonner.md}

@@ -3,20 +3,13 @@ title: Sonner
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/sonner/Sonner.tsx
-css_path: packages/d4gger-design-system/src/styles/components/sonner.css
-props_path: packages/d4gger-design-system/src/components/sonner/sonner.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Sonner.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/overlay.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - sonner
 ---
 
 # Sonner
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -93,7 +86,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | 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 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. |
 | Success border | `var(--dsx-color-success)` | Success variant edge. |
 | Error background | `var(--dsx-color-error-container)` | Error variant surface. |

package/dist/docs/{sortable-list.md → components/sortable-list.md}

@@ -3,8 +3,6 @@ title: SortableList
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/sortableList/SortableList.tsx
-css_path: packages/d4gger-design-system/src/styles/components/sortable-list.css
 depends_on: ["@dnd-kit/core", "@dnd-kit/sortable", "@dnd-kit/utilities"]
 ---
 
@@ -18,6 +16,17 @@ Optional dnd-kit-backed vertical reordering for pointer, touch, and keyboard sen
 
 `SortableList.Root`, `Item`, `Handle`, and `Overlay`. Root receives ordered `ids`, optional `disabledIds`, localized announcements, and emits `{ ids, activeIndex, overIndex }`. Handles are visible named buttons. Cancellation does not emit, successful moves announce position, restore handle focus, and respect reduced motion. Persistence is consumer-owned.
 
+Reorder announcements render through the package `VisuallyHidden` primitive so
+the assertive live region remains available to assistive technology without
+creating a second package-owned hiding utility.
+
+The drag overlay renders the dragged item's own content (falling back to the
+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/{spinner.md → components/spinner.md}

@@ -3,20 +3,13 @@ title: Spinner
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/spinner/Spinner.tsx
-css_path: packages/d4gger-design-system/src/styles/components/spinner.css
-props_path: packages/d4gger-design-system/src/components/spinner/spinner.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Spinner.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Icon (loader)
 ---
 
 # Spinner
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -43,7 +36,9 @@ The icon is internal. The public surface is a single `Spinner` component.
 |---|---|---|---|---|---|
 | `asChild` | `boolean` | `false` | no | Renders the host through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Selects the size modifier class and the icon size; writes `data-size` on the host. | no |
-| `label` | `string` | `'Loading'` | no | Accessible label forwarded to `aria-label` on the host. Override for locale or context. | no |
+| `label` | `string` | `'Loading'` | no | Accessible label forwarded to `aria-label` on the host. Override for locale or context. With `value`, announces `"${label} ${value}%"`. Terminal states announce `Done` / `Error`. | no |
+| `value` | `number` | `undefined` | no | Determinate progress 0–100; renders the ring arc instead of the spinning icon. Read off props directly (not in the prop-def bag — same pattern as CopyButton's `value`). `>= 100` completes to `done`. | no |
+| `state` | `'loading' \| 'done' \| 'error'` | `'loading'` | no | Terminal states render a static check (success tones) or x (error tones) with no animation; writes `data-state`. | no |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-spinner`. | no |
 | `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host. | no |
 | `children` | `React.ReactNode` | `undefined` | no | Optional slotted content when `asChild` is set. | no |
@@ -66,12 +61,14 @@ Rules that apply to this row:
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | `data-size` | `sm`, `md`, `lg` | `dsx-spinner--sm`, `dsx-spinner--md`, `dsx-spinner--lg` | `spinner.css` |
+| `data-state` | `loading`, `done`, `error` | `.dsx-spinner[data-state='done']` (success tones, static icon), `.dsx-spinner[data-state='error']` (error tones, static icon) | `spinner.css` |
 
 **Slot classes:**
 
 | Slot | Class | CSS file |
 |---|---|---|
 | Spinner icon | `dsx-spinner__icon` | `spinner.css` |
+| Determinate ring | `dsx-spinner__ring`, `dsx-spinner__ring-track`, `dsx-spinner__ring-fill` | `spinner.css` |
 
 **Responsive behavior:**
 
@@ -79,7 +76,9 @@ Rules that apply to this row:
 
 **Reduced motion:**
 
-- The CSS file does not declare a reduced-motion block for the spin animation. The component relies on the global `prefers-reduced-motion` stylesheet. Consumers that need to fully pause the animation should layer a media-query override or replace `Spinner` with a static placeholder for the affected users.
+- `spinner.css` collapses the indeterminate spin to `animation: none` under
+  `@media (prefers-reduced-motion: reduce)`. Determinate, done, and error states are
+  static and need no guard.
 
 ## Token mapping
 

package/dist/docs/{stack.md → components/stack.md}

@@ -3,13 +3,6 @@ title: Stack
 status: canonical
 category: Foundations
 archetype: layout-primitive
-package_path: packages/d4gger-design-system/src/layout/Layout.tsx
-css_path: packages/d4gger-design-system/src/styles/components/flex.css
-props_path: packages/d4gger-design-system/src/layout/layout.props.ts
-test_path: packages/d4gger-design-system/src/test/foundations/Layout.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/layout.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Box
   - Flex
@@ -17,11 +10,11 @@ depends_on:
 
 # Stack
 
-> Source of truth: the package source at `package_path`. The spec mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
-A flex-based stack primitive with a single `gap` token and a `direction` default of `column`. `Stack` is a thin extension of `Flex` optimized for vertical or horizontal child stacking in product surfaces. It is the only layout primitive that does not have a `components/` mirror; it lives exclusively under `foundations/`.
+A flex-based stack primitive with a single `gap` token and a `direction` default of `column`. `Stack` is a thin extension of `Flex` optimized for vertical or horizontal child stacking in product surfaces. It is the only layout primitive that does not have a `components/` mirror; it lives in `src/layout/Layout.tsx` (re-exported via `src/foundations/index.ts`).
 
 ## Anatomy & slots
 

package/dist/docs/{stat-card.md → components/stat-card.md}

@@ -3,13 +3,6 @@ title: StatCard
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/statCard/StatCard.tsx
-css_path: packages/d4gger-design-system/src/styles/components/stat-card.css
-props_path: packages/d4gger-design-system/src/components/statCard/statCard.props.ts
-test_path: packages/d4gger-design-system/src/test/components/StatCard.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Card
   - Text
@@ -19,7 +12,7 @@ depends_on:
 
 # StatCard
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -72,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
 
@@ -82,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):
 
@@ -106,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:**
 
@@ -216,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:**