@d4gger/design-system 2.7.0 → 3.0.0

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

@@ -3,25 +3,16 @@ title: Select
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/select/Select.tsx
-css_path: packages/d4gger-design-system/src/styles/components/select.css
-props_path: packages/d4gger-design-system/src/components/select/select.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Select.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-select (the entire state machine, the option list, the trigger / value / item / separator / group parts, the `role='combobox'` semantics, the portal, and the focus return to the trigger on close)"
   - ScrollArea (the `Select.Content` slot mounts a `ScrollArea` to host the option list, so long option sets scroll inside a token-aligned scroll viewport)
   - VisuallyHidden (the `Select.HiddenSelect` slot renders the hidden native `<select>` through `VisuallyHidden` for native form submission and autofill)
   - Icon (lucide-react `chevron-down` is the trigger trailing icon and lucide-react `check` is the item indicator glyph)
-  - "_internal/BaseDialog (the `PortalThemeBoundary` and `PortalThemeWrapper` helpers mirror the `data-dsx-*` attribute contract into the content portal)"
-  - "_internal/baseMenu.css (the shared menu shell, border, surface, and focus contract)"
 ---
 
 # Select
 
-> 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
 
@@ -37,12 +28,13 @@ A controlled option picker for known, medium-sized lists. Pairs the Radix Select
 |---|---|---|---|
 | `Select` (Root) | `@radix-ui/react-select` `Root` wrapped in `PortalThemeBoundary` and `SelectContext.Provider` | The Radix root. Owns open state and the value pipeline. | Reads `accentColor`, `size`, and `variant` into `SelectContext` so subcomponents can resolve them. |
 | `Select.Trigger` | `@radix-ui/react-select` `Trigger` | `dsx-select__trigger`, plus a trailing `dsx-select__icon` (lucide `chevron-down`) and a `dsx-select__value` (the `SelectValue` slot). Writes `data-size`, `data-variant`. | The button that opens the menu. Renders as a `<button>`. The `SelectValue` renders by default when no children are provided. |
-| `Select.Value` | `@radix-ui/react-select` `Value` | `dsx-select__value` | The displayed value. Honors `placeholder` when no value is selected. |
-| `Select.Content` | `@radix-ui/react-select` `Content` wrapped in `PortalThemeWrapper`, with a `ScrollArea` + `Viewport` for the option list | `dsx-select__content` on the popover, `dsx-select__scroll-area` on the `ScrollArea`, `dsx-select__viewport` on the inner viewport. Writes `data-size`, `data-variant`. | The floating menu. Renders into a portal. The `position` prop selects between `item-aligned` (default) and `popper`. |
+| `Select.Value` | `@radix-ui/react-select` `Value` inside a styled span | `dsx-select__value` on the outer single-line text slot | The displayed value. Honors `placeholder` when no value is selected; the wrapper preserves ellipsis styling because Radix drops `className` on `Value`, and mirrors the rendered text into `title` (kept in sync with a MutationObserver) so ellipsized long values stay discoverable on hover. |
+| `Select.Content` | `@radix-ui/react-select` `Content` wrapped in `PortalThemeWrapper`, with a `ScrollArea` + `Viewport` for the option list | `dsx-select__content` on the popover, `dsx-select__scroll-area` on the `ScrollArea`, `dsx-select__viewport` on the inner viewport. Writes `data-size`, `data-variant`. | The floating menu. Renders into a portal. `popper` is the default so the panel aligns to the trigger start edge and mirrors the trigger width at minimum (`min-width: trigger-width`), growing to fit long option content up to the available viewport width (`width: max-content`, capped by `--radix-select-content-available-width`); `item-aligned` remains available for native-menu-style alignment. |
 | `Select.Group` | `@radix-ui/react-select` `Group` | n/a (no DS class) | A semantic group of items, used with `Select.ItemGroupLabel`. |
 | `Select.ItemGroupLabel` | `@radix-ui/react-select` `Label` | `dsx-select__group-label` | The label rendered at the top of a group. |
 | `Select.Label` | `@radix-ui/react-select` `Label` | `dsx-select__label` | A standalone label inside `Content`. |
-| `Select.Item` | `@radix-ui/react-select` `Item` | `dsx-select__item` (the row), `dsx-select__item-indicator` (the leading check slot), `dsx-select__item-text` (the text container) | A single option. The leading check appears only when the item is the selected value. |
+| `Select.Item` | `@radix-ui/react-select` `Item` | `dsx-select__item` (the row), `dsx-select__item-indicator` (the trailing check slot), `dsx-select__item-text` (the single-line text container rendered through `ItemText asChild`) | A single option. The trailing check appears only when the item is the selected value. Rows that fit stay single-line ellipsis; a row whose text exceeds the row box latches `data-overflow` (ResizeObserver, one-way) and wraps to a second line so the full text stays visible with the highlight spanning the full row. |
+| `Select.ItemMedia` | plain `<div>` | `dsx-select__item-media` | Optional leading media slot inside `Select.Item` (avatar, checkbox, icon). Fixed `size-lg` box, centered, non-shrinking; the row `gap` separates it from the text. `Select.Item` partitions media out of the text flow so it stays a direct flex child (and out of the trigger value display). |
 | `Select.Separator` | `@radix-ui/react-select` `Separator` | `dsx-select__separator` | Visual divider between groups. |
 | `Select.ValueText` | `@radix-ui/react-select` `ItemText` | `dsx-select__item-text` | Custom-renderable text container. Useful for embedding markup in the displayed value. |
 | `Select.HiddenSelect` | native `<select>` wrapped in `VisuallyHidden` | `dsx-select__hidden` (on the `<select>`) | Hidden native `<select>` for native form submission and autofill. Honors `name`, `disabled`, `required`, and an `options` array. |
@@ -54,8 +46,8 @@ A controlled option picker for known, medium-sized lists. Pairs the Radix Select
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot`. | no |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Trigger / content size. Writes `data-size` on `Select.Trigger` and `Select.Content` and resolves the `dsx-select-size-{sm,md,lg}` modifier class. | no |
-| `variant` | `'default' \| 'ghost'` | `'default'` | no | Trigger / content variant. Writes `data-variant` and resolves the `dsx-select-variant-{default,ghost}` modifier class. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Trigger density. Writes `data-size` on `Select.Trigger` and `Select.Content` and resolves the `dsx-select-size-{sm,md,lg}` modifier class (scoped to the trigger in CSS). The panel renders one row spec at every size — `size` changes trigger height and trigger type only. | no |
+| `variant` | `'default' \| 'ghost' \| 'vision'` | `'default'` | no | Trigger / content variant. Writes `data-variant`. `vision` is the direction-3 reference copy (12px panel, 40px rows, neutral wash, plain checks, sentence-case labels); the trigger keeps the default chrome. | no |
 | `accentColor` | `'default' \| 'primary'` | `'default'` | no | Accent color override. Writes `data-accent-color` on the trigger and content. | no |
 | (Radix `Select.Root` props) | n/a | n/a | no | All standard Radix Select root props (`value`, `defaultValue`, `onValueChange`, `open`, `defaultOpen`, `onOpenChange`, `name`, `disabled`, `required`, `dir`, `form`) are forwarded. | no |
 
@@ -83,7 +75,7 @@ When `asChild` is set, the trigger renders only the children. The trailing chevr
 | `asChild` | `boolean` | `false` | no | Renders the content through `Slot`. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Content size override. Resolved the same way as the trigger. | no |
 | `variant` | `'default' \| 'ghost'` | `'default'` | no | Content variant override. Resolved the same way as the trigger. | no |
-| `position` | `'item-aligned' \| 'popper'` | `'item-aligned'` | no | Radix positioning mode. `popper` uses `sideOffset={4}`; `item-aligned` uses `sideOffset={undefined}` (Radix default). | no |
+| `position` | `'item-aligned' \| 'popper'` | `'popper'` | no | Radix positioning mode. `popper` magnetizes under the trigger at trigger width with `sideOffset={4}` (the DS default — matches dropdown/combobox behavior); `item-aligned` is the native-macOS-menu mode that aligns to the active item. | no |
 | `sideOffset` | `number` | `position === 'popper' ? 4 : undefined` | no | Distance from the trigger. | no |
 | `data-size` | `'sm' \| 'md' \| 'lg'` | `undefined` | no | Direct data-attribute override. Wins over the resolved `size`. | no |
 | `data-variant` | `'default' \| 'ghost'` | `undefined` | no | Direct data-attribute override. Wins over the resolved `variant`. | no |
@@ -118,7 +110,7 @@ Rules:
 
 | Attribute / source | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-size` | `sm`, `md`, `lg` | `.dsx-select__trigger[data-size='sm'\|'md'\|'lg']` min-height and padding; `.dsx-select-size-{sm,md,lg}` | `select.css` |
+| `data-size` | `sm`, `md`, `lg` | `.dsx-select__trigger[data-size='sm'\|'md'\|'lg']` min-height, padding, and type; `.dsx-select-size-{sm,md,lg}` (trigger-scoped; the class also lands on content via prop extraction but has no panel-side rules). Panel rows are size-invariant by design. | `select.css` |
 | `data-variant` | `default`, `ghost` | `.dsx-select__trigger[data-variant='ghost']` transparent background; `.dsx-select-variant-ghost` | `select.css` |
 | `data-placeholder` | (Radix-native) | `.dsx-select__trigger[data-placeholder]` muted text | `select.css` |
 | `data-state` | `open`, `closed` (Radix-native) | `.dsx-select__trigger[data-state='open']` primary border + focus ring | `select.css` |
@@ -136,6 +128,7 @@ Rules:
 | `Select.Item` | `dsx-select__item` | `select.css` |
 | Item indicator | `dsx-select__item-indicator` | `select.css` |
 | Item text | `dsx-select__item-text` | `select.css` |
+| `Select.ItemMedia` | `dsx-select__item-media` | `select.css` |
 | `Select.Group` | (no DS class) | n/a |
 | `Select.ItemGroupLabel` | `dsx-select__group-label` | `select.css` |
 | `Select.Label` | `dsx-select__label` | `select.css` |
@@ -159,12 +152,12 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 | Property | Token | Role |
 |---|---|---|
-| Trigger min-height (md) | `var(--dsx-size-xl)` | Default control height. |
-| Trigger min-height (sm) | `var(--dsx-size-lg)` | Small control height. |
-| Trigger min-height (lg) | `calc(var(--dsx-size-xl) + var(--dsx-space-sm))` | Large control height. |
-| Trigger padding (md) | `var(--dsx-space-sm) var(--dsx-space-md)` | Default control padding. |
-| Trigger padding (sm) | `var(--dsx-space-xs) var(--dsx-space-sm)` | Small control padding. |
-| Trigger padding (lg) | `var(--dsx-space-md) var(--dsx-space-lg)` | Large control padding. |
+| Trigger min-height (md) | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Default control height. |
+| Trigger min-height (sm) | `var(--dsx-density-control-height-sm, var(--dsx-size-lg))` | Small control height. |
+| Trigger min-height (lg) | `var(--dsx-density-control-height-lg, var(--dsx-size-2xl))` | Large control height. |
+| Trigger padding (md) | density `control-padding-*` tokens | Default control padding. |
+| Trigger padding (sm) | density `control-padding-*-sm` tokens | Small control padding. |
+| Trigger padding (lg) | density `control-padding-*-lg` tokens | Large control padding. |
 | Trigger border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Resting edge. |
 | Trigger radius | `var(--dsx-rounded-md)` | Default corner roundness. |
 | Trigger background | `var(--dsx-color-surface)` | Resting surface. |
@@ -180,18 +173,18 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Content background | `var(--dsx-color-panel-translucent)` | Floating menu surface. |
 | Content border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Floating menu edge. |
 | Content radius | `var(--dsx-rounded-lg)` | Floating menu corner roundness. |
-| Content padding | `var(--dsx-space-xs)` | Floating menu inner gutter. |
-| Content min-width | `var(--radix-select-trigger-width, 200px)` | Radix CSS var fallback. |
+| Content padding | `var(--dsx-space-sm)` | Floating menu inner gutter. |
+| Content width / min-width / max-width | `max-content` / `var(--radix-select-trigger-width, 200px)` / `min(--radix-select-content-available-width, 40rem)` | Mirror-at-minimum with grow-to-fit; past 40rem (or the viewport edge) rows wrap via `data-overflow` instead of stretching the panel. The 40rem ceiling is a token candidate for the size batch. |
 | Content max-height | `var(--dsx-size-popover-max-width)` | Scroll ceiling (used by the inner ScrollArea). |
 | Content z-index | `var(--dsx-z-index-dropdown)` | Overlay stacking. |
 | Item min-height | `var(--dsx-size-lg)` | Default option height. |
-| Item padding | `var(--dsx-space-sm) var(--dsx-space-sm) var(--dsx-space-sm) calc(var(--dsx-space-lg) + var(--dsx-space-sm))` | Option padding (right side reserves room for the leading check indicator). |
+| Item padding | density-aware block/inline tokens with trailing indicator reservation | Option padding; the right side reserves room for the trailing check indicator. |
 | Item border | `0` | Items are borderless. |
 | Item radius | `var(--dsx-rounded-md)` | Option corner roundness. |
 | Item background | `transparent` | Resting option surface. |
 | Item text | `var(--dsx-color-on-surface)` | Option label. |
 | Item typography | `var(--dsx-typography-body-medium-*)` | Option label ramp. |
-| Item indicator left | `var(--dsx-space-sm)` | Indicator gutter. |
+| Item indicator right | `var(--dsx-space-sm)` | Indicator gutter. |
 | Item indicator size | `var(--dsx-size-md)` | Indicator tile size. |
 | Group label padding | `var(--dsx-space-xs) var(--dsx-space-sm)` | Group label gutter. |
 | Group label color | `var(--dsx-color-on-surface-variant)` | Group label fill. |
@@ -244,7 +237,7 @@ Rules:
 
 **Color and meaning:**
 
-- Selected state is communicated by the leading check icon, the `data-state="checked"` Radix attribute, and the option's `aria-selected`. The trigger's text changes too. Color is not the only signal.
+- Selected state is communicated by the trailing check icon, the `data-state="checked"` Radix attribute, and the option's `aria-selected`. The trigger's text changes too. Color is not the only signal.
 
 **Naming:**
 
@@ -258,7 +251,7 @@ Rules:
 
 **Variant story:**
 
-- Renders one `Select` per `variant` value (`default`, `ghost`). Asserts the matching `data-variant` attribute is set on the trigger.
+- Renders one `Select` per `variant` value (`default`, `ghost`, `vision`). Asserts the matching `data-variant` attribute is set on the trigger and portalled content.
 
 **Size story:**
 
@@ -273,6 +266,7 @@ Rules:
 
 - Renders `Select` with `Select.Group`, `Select.ItemGroupLabel`, and `Select.Item` rows. Asserts the group label has the `dsx-select__group-label` class.
 - Renders `Select.Item` with `Select.ValueText` to verify the `dsx-select__item-text` class is applied.
+- Renders `Select.Item` with `Select.ItemMedia` (avatar/checkbox) to verify the `dsx-select__item-media` class is applied and the row keeps single-line ellipsis.
 
 **Token story:**
 

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

@@ -3,20 +3,13 @@ title: Separator
 status: canonical
 category: Primitives
 archetype: radix-wrapper
-package_path: packages/d4gger-design-system/src/components/separator/Separator.tsx
-css_path: packages/d4gger-design-system/src/styles/components/separator.css
-props_path: packages/d4gger-design-system/src/components/separator/separator.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Separator.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:
   - '@radix-ui/react-separator (Root)'
 ---
 
 # Separator
 
-> 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/{shared.md → components/shared.md}

@@ -3,17 +3,12 @@ title: Shared
 status: canonical
 category: Foundations
 archetype: utility
-package_path: packages/d4gger-design-system/src/foundations/Shared.tsx
-test_path: packages/d4gger-design-system/src/test/foundations/Shared.test.ts
-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: []
 ---
 
 # Shared
 
-> 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
 
@@ -40,7 +35,7 @@ No slots: flat module export. Shared does not render any host element. It export
 | `ShadowTone` | type union | `'none' \| '1' \| '2' \| '3' \| '4' \| '5' \| '6' \| 'gold' \| 'gold-strong'`. |
 | `TextTone` | type union | `'default' \| 'muted' \| 'primary' \| 'secondary' \| 'success' \| 'error'`. |
 | `PolymorphicProps<T, OwnProps>` | generic type | `OwnProps & { as?: T; asChild?: boolean; children?: React.ReactNode; className?: string; style?: React.CSSProperties } & Omit<React.ComponentPropsWithoutRef<T>, keyof OwnProps \| 'as' \| 'asChild' \| 'children' \| 'className' \| 'style'>`. The canonical polymorphic prop bag for the foundations and the layout primitives. |
-| `withVars(style, vars)` | function | Merges a `React.CSSProperties` object with a `--*` CSS custom property map. Returns a typed `StyleWithVars` (a `React.CSSProperties` extended with `--*` keys). |
+| `withVars(style, vars)` | function | Merges a `React.CSSProperties` object with a `--*` CSS custom property map. Returns a typed `StyleWithVars` (a `React.CSSProperties` extended with `--*` keys). Precedence: `style` wins over `vars` on conflict — an entry in `style` overrides the same key in `vars`. |
 | `resolveSpace(token?)` | function | Returns `'0px'` for `'none'`, `var(--dsx-space-{token})` for numeric and named tokens, or the raw value for arbitrary input. Returns `undefined` when no token is supplied. |
 | `resolveRadius(token?)` | function | Returns `'0px'` for `'none'`, `var(--dsx-rounded-{token})` for known tokens, or the raw value. Returns `undefined` when no token is supplied. |
 | `resolveSurface(tone?)` | function | Returns `undefined` for `undefined` or `'transparent'`, otherwise `var(--dsx-color-{tone})`. |

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,15 @@ 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`
+
+| 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 +193,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 +208,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 +225,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 +247,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 +279,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 +295,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 +311,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; full MenuBadge→Badge absorption is owned by the chip-taxonomy brief. |
+| 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 +334,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 +351,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 +364,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 +384,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 +399,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 +412,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 +423,8 @@ Rules:
 | Prop | Control | Default |
 |---|---|---|
 | `defaultExpanded` | boolean | `true` |
+| `hoverExpand` | boolean | `false` |
+| `previewOpen` | boolean | `false` |
 
 ## Wiring notes
 
@@ -387,7 +445,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