@d4gger/design-system 2.7.0

package/dist/docs/sidebar.md

@@ -0,0 +1,396 @@
+---
+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)
+  - 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`)
+  - Separator (the `dsx-separator dsx-separator--decorative` classes merged into `Sidebar.Separator`)
+  - Button (the `dsx-button` class merged into `Sidebar.GroupAction`, `Sidebar.MenuAction`, `Sidebar.MenuButton`, `Sidebar.MenuSubButton`, and `Sidebar.Trigger`)
+---
+
+# 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.
+
+## 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.
+
+## Anatomy & slots
+
+**Parent:** `Sidebar` (alias of `Sidebar.Root`). The root is `<nav aria-label="Sidebar">` and renders inside a `Sidebar.Provider` context. The public surface also includes `Sidebar.SkipLink`, the provider's `collapsible` and `nested` props, and the `useSidebar` hook.
+
+**Slots:**
+
+| 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` (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. |
+| Provider recovery rail | `<button aria-label="Expand sidebar">` | `dsx-sidebar__recovery-rail` + `data-slot="sidebar-recovery-rail"` | Provider-owned offcanvas recovery outside the zero-width panel. |
+| `Sidebar.Header` | `<div>` | `dsx-sidebar__header` + `data-slot="sidebar-header"` + `data-state` | The top region. Children with `data-persistent="true"` remain visible when the panel collapses. |
+| `Sidebar.Content` | `ScrollArea` (Radix-backed) | `dsx-sidebar__content` + `dsx-sidebar__content-viewport` + `data-slot="sidebar-content"` + `data-state` | The scrollable middle region. |
+| `Sidebar.Footer` | `<div>` | `dsx-sidebar__footer` + `data-slot="sidebar-footer"` + `data-state` | The bottom region. Same `data-persistent` behavior as the header. |
+| `Sidebar.Group` | `<div>` | `dsx-sidebar__group` + `data-slot="sidebar-group"` + `data-state` | A labelled cluster. |
+| `Sidebar.GroupLabel` | `<div>` | `dsx-sidebar__group-label` + `data-slot="sidebar-group-label"` + `data-state` | A section heading inside a group. |
+| `Sidebar.GroupAction` | `<button>` (or `Slot` child when `asChild`) | `dsx-sidebar__group-action dsx-button` + `data-slot="sidebar-group-action"` + `data-state` | An action button rendered at the end of the group row. |
+| `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.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.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.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). |
+
+The roster's `Parent / Slots` column lists every slot above plus `Sidebar.Inset` and `Sidebar.Trigger`. The source exports the full set through `Object.assign` on `Sidebar` (alias of `Sidebar.Root`), and also re-exports the named components individually. The spec records the runtime shape; the roster's slot list is the contract for canonical anatomy.
+
+## Props contract
+
+### `Sidebar.Provider`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `defaultExpanded` | `boolean` | `true` | no | Initial expanded state. The `dsx-sidebar-provider-default-expanded` class is also merged. | no |
+| `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 |
+| `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 |
+| `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 |
+
+### `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 |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-sidebar`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The sidebar slots. | no |
+
+### `Sidebar.Inset`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the host through `Slot`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-sidebar__inset`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | The main content. | no |
+
+### `Sidebar.MenuButton` and `Sidebar.MenuSubButton`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `isActive` | `boolean` | `false` | no | Marks the button as the current page. Writes `data-active="true"` and merges the `dsx-sidebar-menu-button-active` class. | 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 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.MenuAction`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `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-action`. | no |
+| `children` | `React.ReactNode` | (required) | yes | The action content. | no |
+
+### `Sidebar.MenuSkeleton`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `showIcon` | `boolean` | `true` | no | Renders an icon-shaped skeleton circle when `true`. Writes `data-show-icon`. The class `dsx-sidebar-menu-skeleton-icon` is also merged. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-sidebar__menu-skeleton`. | no |
+
+### `Sidebar.Trigger`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `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 |
+| `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 |
+
+### `Sidebar.GroupAction`
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | no | Forwarded to the host `<button>`. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-sidebar__group-action`. | no |
+| `children` | `React.ReactNode` | (required) | yes | The action content. | 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.
+
+### `Sidebar.Header`, `Sidebar.Footer`, `Sidebar.Group`, `Sidebar.GroupLabel`, `Sidebar.GroupContent`, `Sidebar.Menu`, `Sidebar.MenuItem`, `Sidebar.MenuSub`, `Sidebar.MenuSubItem`
+
+Standard React HTML attributes (`<div>` or `<ul>` / `<li>` accordingly) plus `className` and `children`.
+
+### `Sidebar.Separator`
+
+Standard React HTML attributes plus the `role="separator"` and `aria-orientation="horizontal"` defaults written by the source.
+
+### `useSidebar` hook
+
+Returns the `SidebarContext` value or a no-op fallback (`expanded: true`, `setExpanded: () => {}`, `mobileSheetOpen: false`, `setMobileSheetOpen: () => {}`, `isMobile: false`) when the consumer renders a sidebar slot outside `Sidebar.Provider`.
+
+Rules:
+
+- The `data-state` and `data-collapsed` attributes are written by `getSidebarDataAttributes` and applied to the `Provider`, the `Root`, and every slot that reads from `useSidebar()`. The `data-state` value is `expanded` or `collapsed`.
+- `Sidebar.MenuButton` and `Sidebar.MenuSubButton` write `data-active` when `isActive` is `true` and wrap string or number children in `<span class="dsx-sidebar__menu-button-text">`. The wrapping span is omitted when `asChild` is set.
+- `Sidebar.Provider` registers a `keydown` listener on `document` for the toggle shortcut. The listener is removed on cleanup and is a no-op when `toggleShortcut` is `false`. The shortcut is `Ctrl+B` on Windows and Linux, `Cmd+B` on macOS.
+- `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.
+
+## CSS class contract
+
+**Root class:** `dsx-sidebar` (panel) and `dsx-sidebar-provider` (shell)
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `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-active` | `true` | `.dsx-sidebar__menu-button[data-active='true']`, `.dsx-sidebar__menu-sub-button[data-active='true']` | `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` |
+
+**Modifier classes (prop-def-derived):**
+
+| Source prop | Class | CSS file |
+|---|---|---|
+| `defaultExpanded` on `Provider` | `dsx-sidebar-provider-default-expanded` | `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` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Sidebar.Provider` | `dsx-sidebar-provider` | `sidebar.css` |
+| `Sidebar` | `dsx-sidebar` | `sidebar.css` |
+| `Sidebar.Inset` | `dsx-sidebar__inset` | `sidebar.css` |
+| `Sidebar.Rail` | `dsx-sidebar__rail` | `sidebar.css` |
+| `Sidebar.Header` | `dsx-sidebar__header` | `sidebar.css` |
+| `Sidebar.Content` | `dsx-sidebar__content` + `dsx-sidebar__content-viewport` | `sidebar.css` |
+| `Sidebar.Footer` | `dsx-sidebar__footer` | `sidebar.css` |
+| `Sidebar.Group` | `dsx-sidebar__group` | `sidebar.css` |
+| `Sidebar.GroupLabel` | `dsx-sidebar__group-label` | `sidebar.css` |
+| `Sidebar.GroupAction` | `dsx-sidebar__group-action` (+ `dsx-button`) | `sidebar.css` |
+| `Sidebar.GroupContent` | `dsx-sidebar__group-content` | `sidebar.css` |
+| `Sidebar.Menu` | `dsx-sidebar__menu` | `sidebar.css` |
+| `Sidebar.MenuItem` | `dsx-sidebar__menu-item` | `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` |
+| `Sidebar.MenuSkeleton` | `dsx-sidebar__menu-skeleton` (+ `dsx-skeleton` variants) | `sidebar.css` |
+| `Sidebar.MenuSub` | `dsx-sidebar__menu-sub` | `sidebar.css` |
+| `Sidebar.MenuSubItem` | `dsx-sidebar__menu-sub-item` | `sidebar.css` |
+| `Sidebar.MenuSubButton` | `dsx-sidebar__menu-sub-button` (+ `dsx-button` + optional `dsx-sidebar__menu-button-text`) | `sidebar.css` |
+| `Sidebar.Separator` | `dsx-sidebar__separator` (+ `dsx-separator dsx-separator--decorative`) | `sidebar.css` |
+| `Sidebar.Trigger` | `dsx-sidebar__trigger` (+ `dsx-button` + `dsx-button__icon` + `dsx-sidebar__trigger-label`) | `sidebar.css` |
+| Mobile sheet trigger (internal) | `dsx-sidebar__mobile-trigger` | `sidebar.css` |
+
+**Responsive behavior:**
+
+- The CSS file collapses the panel through the `data-state` attribute. The mobile sheet fallback is mounted by `Sidebar.Provider` based on `window.innerWidth` and `matchMedia('(pointer: coarse)')`, gated by `mobileBreakpoint` and the `mobile` prop.
+- The component does not write `@media` rules; the mobile behavior is runtime-driven, not CSS-driven.
+
+**Reduced motion:**
+
+- The CSS file gates the panel width transition and the menu action opacity transition behind the standard `var(--dsx-motion-duration-*)` and `var(--dsx-motion-easing-*)` tokens.
+- Under `prefers-reduced-motion: reduce`, those transitions are removed and focus transfers synchronously between the panel trigger and the recovery rail.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Provider display | `flex` (CSS keyword) | Shell layout. |
+| 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 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 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. |
+| Inset flex | `1` (CSS keyword) | Fill remaining width. |
+| Rail width / min-height | `var(--dsx-size-lg)` | Rail touch target. |
+| Rail border radius | `var(--dsx-rounded-sm)` | Rail corner roundness. |
+| Rail color | `var(--dsx-color-on-surface-variant)` | Rail icon color. |
+| Rail hover background | `var(--dsx-effect-hover-ghost)` | Rail hover surface. |
+| 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. |
+| 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. |
+| 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. |
+| Group label color | `var(--dsx-color-on-surface-variant)` | Group label color. |
+| Group content gap | `var(--dsx-space-xs)` | Gap inside group content. |
+| Menu gap | `var(--dsx-space-xs)` | Gap between menu items. |
+| Menu action opacity | `0` (default) / `1` (hover / focus-within) | Reveal on hover. |
+| Menu action motion | `var(--dsx-motion-duration-fast, 150ms) var(--dsx-motion-easing-standard, ease)` | Opacity transition. |
+| Menu button padding | `var(--dsx-space-sm)` | Menu button gutter. |
+| 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 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. |
+| Menu skeleton gap | `var(--dsx-space-sm)` | Skeleton row gap. |
+| Menu skeleton icon size | `var(--dsx-size-sm)` | Skeleton icon diameter. |
+| Separator | `var(--dsx-color-outline)` | Separator color. |
+| Mobile trigger size | `var(--dsx-size-lg)` | Mobile trigger touch target. |
+| Focus ring | `var(--dsx-shadow-focus-ring)` | `:focus-visible` ring. |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in `sidebar.css`. The light-theme border override uses `var(--dsx-color-outline-variant)` instead of `var(--dsx-color-outline)`.
+
+## Motion contract
+
+| 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 |
+| Menu action opacity | `var(--dsx-motion-duration-fast) var(--dsx-motion-easing-standard)` | 150ms ease | (same as above) |
+
+Rules:
+
+- The motion tokens live in `DESIGN.md`; the CSS only references them. There is no `MOTION_TRANSITIONS` JS preset for this composite; the source does not bind framer-motion.
+
+## Accessibility
+
+**Roles:**
+
+- `Sidebar` is a named navigation landmark through `<nav aria-label="Sidebar">`.
+- `Sidebar.Inset` is `role="main"`.
+- `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.
+- Offcanvas collapsed content is removed from interaction and the accessibility
+  tree. The external recovery rail owns `aria-controls` and `aria-expanded`.
+- `Sidebar.GroupLabel` is a non-semantic `<div>`; consumers can set `role="heading"` plus `aria-level` when the label needs to be a heading.
+- The mobile sheet trigger (when mounted by `Sidebar.Provider`) is a button with `aria-label="Open sidebar"`.
+- `useSidebar` returns a no-op fallback when the consumer renders a sidebar slot outside `Sidebar.Provider`, so the component never throws.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus through the panel and the inset. |
+| `Enter`, `Space` | Activates the focused button. |
+| `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. |
+
+**Focus:**
+
+- The CSS file paints a `var(--dsx-shadow-focus-ring)` ring on `:focus-visible` for the rail and the menu buttons. The ring stays visible on dark and light surfaces.
+
+**Reduced motion:**
+
+- The CSS removes Sidebar and recovery-rail transitions under
+  `prefers-reduced-motion`; focus transfers immediately.
+
+**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.
+
+**Naming:**
+
+- The panel landmark has a default `aria-label="Sidebar"`. The rail and trigger have default `aria-label` values (`Expand sidebar` / `Collapse sidebar`). Override the labels when the panel needs product-specific copy.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Sidebar.Provider` with a `Sidebar` containing a `Sidebar.Header`, a `Sidebar.Content` with a `Sidebar.Menu` of three `Sidebar.MenuItem` / `Sidebar.MenuButton` rows, and a `Sidebar.Footer`. Asserts the panel is `role="complementary"`, the `data-state` is `expanded`, and the menu buttons render with `dsx-sidebar__menu-button dsx-button`.
+
+**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.
+
+**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).
+
+**Composition story:**
+
+- Renders a `Sidebar.Content` with two `Sidebar.Group` blocks, each containing a `GroupLabel`, a `GroupContent`, and a `Menu` with `MenuItem` and `MenuButton` rows. Adds a `Sidebar.Separator` between the groups and a `Sidebar.MenuSub` with `Sidebar.MenuSubItem` and `Sidebar.MenuSubButton` rows in one of the menus. Asserts every slot renders the right `dsx-sidebar__*` class.
+
+**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.
+
+**A11y story:**
+
+- The `Sidebar.test.tsx` suite runs `vitest-axe` against the default shell and against the groups + separators shell. The registry does not need a separate `vitest-axe` check.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `defaultExpanded` | boolean | `true` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-slot`: enables `asChild` on `Sidebar.Inset`, `Sidebar.MenuAction`, and `Sidebar.MenuButton` (and `Sidebar.MenuSubButton`).
+- `_internal/helpers/extractProps`: turns the prop defs 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.
+- `ScrollArea`: the scroll surface for `Sidebar.Content`.
+- `Sheet`: 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`.
+- `Separator`: the `dsx-separator` / `dsx-separator--decorative` classes merged into `Sidebar.Separator`.
+- `Button`: the `dsx-button` class merged into `Sidebar.GroupAction`, `Sidebar.MenuAction`, `Sidebar.MenuButton`, `Sidebar.MenuSubButton`, and `Sidebar.Trigger`.
+
+**Used by:**
+
+- The Cabinet Shell pattern: composing `Sidebar`, `Toolbar`, `DropdownMenu`, `Card`, `DataList`, `EmptyState`, layout, and typography. App owns the route map, auth, permissions, and nav data.
+
+**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 the consumer: the route map, the active-page detection, the disabled reasons, the auth and permissions policy, and the persistence target.
+
+**Boundary rules:**
+
+- App-owned data: the nav registry, the route map, the auth and permissions policy, the page titles, the icon set, the badge counts, and the persistence target.
+- DS-owned visuals: the `dsx-sidebar` / `dsx-sidebar-provider` root classes, the slot classes, the token bindings, the data-attribute contract, and the persistence helpers (localStorage / cookie / memory).

package/dist/docs/skeleton.md

@@ -0,0 +1,233 @@
+---
+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.
+
+## Purpose
+
+A loading placeholder surface that mirrors the layout of the eventual content. `Skeleton` renders a single block with a shimmer animation, three shape presets, and an `asChild` escape hatch for wrapping custom content. Match the size and shape of the eventual content closely enough to avoid layout shift, but keep the surface simple.
+
+## Anatomy & slots
+
+**Parent:** `Skeleton` (no compound; flat export).
+
+**Slots:**
+
+No public subcomponents. The component renders a single `<div>` host (or a slotted child when `asChild` is set) with the `dsx-skeleton` root class and a `dsx-skeleton--{shape}` modifier class. The body content is whatever the consumer passes as `children`.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the skeleton through `Slot` from `@radix-ui/react-slot`; consumer supplies the host element. | no |
+| `shape` | `'rectangle' \| 'circle' \| 'text-line'` | `'rectangle'` | no | Selects the modifier class. `circle` swaps to a fully rounded border radius. `text-line` adds a `min-height: 1em` floor for text-row mirrors. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-skeleton`. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style forwarded to the host. Consumers use this to set width and height that match the eventual content. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Optional slotted content when `asChild` is set. | no |
+
+Rules that apply to this row:
+
+- `Skeleton` extends `React.ComponentPropsWithoutRef<'div'>`, so any standard `<div>` attribute (`id`, `aria-*`, `title`, etc.) is forwarded.
+- The shimmer animation is the only motion. The animation duration is theme-aware through the motion tokens; the component does not expose a `duration` prop.
+- Width and height are not props. Consumers set them through `style` (or via a wrapping layout primitive) to mirror the eventual content.
+
+## CSS class contract
+
+**Root class:** `dsx-skeleton`
+
+**Modifier classes** (driven by the `shape` prop, applied through the prop def class name):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-shape` | `rectangle`, `circle`, `text-line` | `dsx-skeleton--rectangle`, `dsx-skeleton--circle`, `dsx-skeleton--text-line` | `skeleton.css` |
+
+**Slot classes:** none.
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. Skeleton has no `responsive: true` prop defs. Width and height come from the consumer's `style` or the surrounding layout.
+
+**Reduced motion:**
+
+- The shimmer animation does not have a dedicated reduced-motion block in `skeleton.css`. The component relies on the global `prefers-reduced-motion` stylesheet. Consumers that need to fully stop the shimmer should layer their own media-query override or replace `Skeleton` with a static placeholder for the affected user.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Background | `linear-gradient(90deg, --dsx-color-surface-raised, --dsx-color-surface, --dsx-color-surface-raised)` | Shimmer band. |
+| Background size | `200% 100%` | Wide band for the slide. |
+| Border radius (default) | `var(--dsx-rounded-md)` | Rectangle corner. |
+| Border radius (circle) | `var(--dsx-rounded-full)` | Circle corner. |
+| Min height (text-line) | `1em` (CSS hard-code) | Floor for text-line mirrors. |
+| Animation duration | `calc(var(--dsx-motion-duration-slow) * 4)` | Full sweep. |
+| Animation easing | `var(--dsx-motion-easing-in-out)` | Shimmer easing. |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in `skeleton.css`. The shimmer band uses two surface tokens for the gradient; both are theme-aware.
+- The `text-line` shape has a `1em` hard-code because the spec expects a single line of text. The hard-code is a typography convention, not a token.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Shimmer | `calc(var(--dsx-motion-duration-slow) * 4)` + `var(--dsx-motion-easing-in-out)` | `dsx-skeleton-shimmer` keyframes, infinite | Relies on the global `prefers-reduced-motion` stylesheet. Skeleton does not currently gate the animation in CSS. |
+
+Rules:
+
+- Skeleton does not import `MOTION_TRANSITIONS` from `src/_internal/motion.ts`. The motion is plain CSS, sourced from the duration and easing tokens.
+- A future promotion that needs framer-motion should pick a preset from `MOTION_TRANSITIONS`; do not introduce new motion durations.
+- The reduced-motion behavior is global; the CSS file does not carry its own reduced-motion block.
+
+## Accessibility
+
+**Roles:**
+
+- `<div>` element by default. The component has no implicit role. When `asChild` is set, the consumer owns the role.
+
+**Keyboard:**
+
+- Skeleton is not interactive. No keyboard contract beyond the page-level Tab order.
+
+**Focus:**
+
+- Skeleton has no interactive surface. The host is not focusable and does not show a focus ring.
+
+**Reduced motion:**
+
+- The shimmer animation is not gated in `skeleton.css`. The global reduced-motion stylesheet governs. Consumers that need to fully pause the animation for the affected users should layer a media-query override or replace `Skeleton` with a static placeholder.
+
+**Color and meaning:**
+
+- The component does not communicate state. The shimmer is a visual signal that content is loading, not a state to be read by assistive tech. Pair `Skeleton` with `aria-busy="true"` on the loading region and an `aria-label` or visible heading so screen readers can announce the loading state.
+
+**Naming:**
+
+- The component does not generate an accessible name. The recommended pattern is to wrap the skeleton (or group of skeletons) in a region with `role="status"` and an `aria-label`, or to mark the surrounding region with `aria-busy="true"` and a visible heading. Putting `aria-label` directly on a bare `<div>` skeleton is a WCAG violation; the wrapper provides the valid role.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Skeleton` with no extra props. Asserts the root class is `dsx-skeleton`, `data-shape="rectangle"`, and the host element is `DIV`.
+
+**Shape story** (one per shape):
+
+- Renders Skeleton with `shape="rectangle"`, `shape="circle"`, and `shape="text-line"`. Asserts the matching `dsx-skeleton--{shape}` modifier class and the matching `data-shape` value on the host.
+
+**Composition story** (for `asChild`):
+
+- Renders Skeleton with `asChild` wrapping a custom `<div>`. Asserts the host is the consumer's element and the `dsx-skeleton` class is preserved.
+
+**State story:**
+
+- Renders three Skeletons stacked with descending widths inside a `role="status"` region to mirror a typical content skeleton (heading, paragraph, paragraph). Asserts the widths and shapes match the eventual content to avoid layout shift.
+- Asserts the loader region is announced as a single status with the wrapper's `aria-label`, not the individual skeleton elements.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the shimmer band color is unchanged across accents; the gradient tracks the surface tokens, not the accent tokens.
+
+**A11y story:**
+
+- Uses `vitest-axe` against a default Skeleton wrapped in a `role="status"` region with an `aria-label`. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `shape` | select (`rectangle`, `circle`, `text-line`) | `rectangle` |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `@radix-ui/react-slot`: enables `asChild` for consumer-supplied host elements.
+- No DS component composition. Skeleton is a single-element primitive.
+
+**Used by:**
+
+- `DataTable` (composite advanced table): renders skeleton rows while the data is loading.
+- `Field` (composite form wrapper): renders skeleton placeholders for the form row while the initial data is hydrating.
+- App-level loading surfaces where the eventual content has a stable shape.
+
+**State boundaries:**
+
+- Owned by Skeleton: the root class, the shape modifier class, the shimmer gradient, and the border radius.
+- Owned by the consumer: width, height, the surrounding loading region, the `aria-busy` and `aria-label` attributes, and the host element when `asChild` is set.
+
+**Boundary rules:**
+
+- App-owned data: the loading region's role, the eventual content's dimensions, and the loading state message.
+- DS-owned visuals: token bindings for the shimmer gradient, the corner radius per shape, the `text-line` min-height floor, and the motion tokens that drive the animation.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. Keep this section when the component has a published Penpot asset, or when the spec needs to call out a visual decision the package does not encode. Skip the section when the component is utility or layout-primitive; the package code is the only authority.
+
+The package does not yet publish a Penpot asset for Skeleton. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Primitives / Skeleton`.
+- **Dimensions**: `200 × 16` (default demo width and height).
+- **Layout**: `Fixed`.
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'fix'`.
+
+### Layer tree
+
+```
+<Root Board: Skeleton / rectangle>
+  └── <Frame: shimmer band (background = linear-gradient)>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Shimmer band | fill (start) | `--dsx-color-surface-raised` | Color | `fills` (gradient) |
+| Shimmer band | fill (mid) | `--dsx-color-surface` | Color | `fills` (gradient) |
+| Shimmer band | fill (end) | `--dsx-color-surface-raised` | Color | `fills` (gradient) |
+| Shimmer band | radius | `--dsx-rounded-md` | Radius | `radius` |
+| Shimmer band (circle) | radius | `--dsx-rounded-full` | Radius | `radius` (state) |
+| Shimmer band (text-line) | min height | `1em` | Sizing | `size` (state) |
+
+### State transformations
+
+| State | Radius | Min height |
+|---|---|---|
+| `rectangle` | `--dsx-rounded-md` | (none) |
+| `circle` | `--dsx-rounded-full` | (none) |
+| `text-line` | `--dsx-rounded-md` | `1em` |
+
+### Variant model
+
+- `shape`: `rectangle`, `circle`, `text-line`. Default `rectangle`.
+- `asChild`: `true`, `false`. Default `false`.
+- Total members: 6.
+
+### Validation checklist
+
+- [ ] Token bindings resolve at the values `DESIGN.md` describes.
+- [ ] Component is promoted to Main Component under `Primitives`.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.
+- [ ] The shimmer animation is motion-token-driven; document the duration and easing in the board metadata.
+- [ ] The `text-line` shape has a `1em` hard-code for min height; document it as a typography convention, not a token.