@d4gger/design-system 2.7.0

package/dist/docs/component-roster.md

@@ -0,0 +1,224 @@
+# Component Roster
+
+The single source of truth for every component the `@d4gger/design-system` package should contain. This file is decision-oriented: it lists what exists, where it lives in the taxonomy, how it is built, and which batch will harden it. Deep anatomy, variants, states, accessibility, and Penpot contracts live in the per-component spec files under `docs/design-system/`. The roster points at those specs; it does not duplicate them.
+
+## How to read this file
+
+- **Category** is the canonical taxonomy bucket from `docs/design-system/HIERARCHY.md`: Foundations, Primitives, Components, Patterns, Utilities.
+- **Archetype** describes *how* the component is built, not what it is for: `radix-wrapper`, `radix-compound`, `layout-primitive`, `composite`, `adapter-backed`, `pattern`, `utility`.
+- **Status** is the package-vs-canon maturity flag: `canonical` (first-class spec exists and matches the package), `package-stage` (package ships the surface, canon treats it as incomplete), `implemented-missing-spec` (package TSX + CSS + tests exist, no canonical spec yet), `spec-only-proposed` (spec proposed, not yet in the package).
+- **Parent / Slots** lists the compound sub-components in `Component.Slot` form. A `-` means the component is a single, flat export.
+- **Composed From** names the package components (or external adapters) the row should be built on top of, so wiring decisions are visible at a glance.
+- **Batch** is the rollout bucket 0 to 6 used to delegate work to subagents. See [Batches](#batches) below.
+
+## Master Roster
+
+| Component | Category | Archetype | Status | Purpose | Parent / Slots | Composed From | Batch | Notes |
+|---|---|---|---|---|---|---|---|---|
+| Box | Foundations | layout-primitive | canonical | Polymorphic layout primitive that maps design-token style props to a host element. | - | - | 2 | Foundational. `foundations` entrypoint is canonical; component-subpath wrapper is compatibility-only. |
+| Container | Foundations | layout-primitive | canonical | Centers content and applies a max-width rhythm from the spacing scale. | - | Box | 2 | Foundation-level wrapper. |
+| Flex | Foundations | layout-primitive | canonical | Horizontal or vertical flex layout with gap and alignment tokens. | - | Box | 2 | Foundational. |
+| Grid | Foundations | layout-primitive | canonical | CSS grid layout primitive with responsive columns and gap tokens. | - | Box | 2 | Foundational. |
+| Section | Foundations | layout-primitive | canonical | Page-level vertical-rhythm wrapper with padding and background tokens. | - | Box | 2 | Foundational. |
+| Stack | Foundations | layout-primitive | canonical | Stacks children with a single gap token; lives exclusively in `foundations/`. | - | Box | 2 | Only layout primitive that does not have a `components/` directory. |
+| Inset | Foundations | layout-primitive | canonical | Edge-padding utility for composed surfaces; not an app-shell primitive. | - | Box | 2 | Component-level convenience; does not replace Container or Section. |
+| Layout (props) | Foundations | utility | canonical | Shared polymorphic style-prop types (`BoxStyleProps`, `FlexStyleProps`, `GridStyleProps`, etc.) for DS-local extension. | - | - | 2 | Infra, not a public component. Exposed as types only. |
+| Theme | Foundations | utility | canonical | Theme provider/context that writes the full `data-dsx-*` attribute contract to the DOM. | - | - | 2 | `applyToDocument` enables global application. `DESIGN.md` is source of truth for theme values. |
+| ThemeProvider | Foundations | utility | canonical | Persisted theme preference (light/dark/system) with full attribute mirroring. | - | Theme, `useTheme` | 2 | Requires `storageKey`. `useTheme` must run inside this provider. |
+| DirectionProvider | Foundations | utility | canonical | RTL/LTR direction context for downstream app composition. | - | - | 2 | Locale plumbing, not visual UI. |
+| FontProvider | Foundations | utility | canonical | Loads Fraunces and Manrope font subsets and sets CSS font variables. | - | - | 2 | Required for token-aligned typography. |
+| Typography | Foundations | primitive | canonical | Foundation-level `Text` and `Heading` components with token-aligned type ramps. | - | - | 2 | Exposed as `FoundationText` and `FoundationHeading` to avoid clashing with the app-level `Text` and `Heading`. |
+| Shared | Foundations | utility | canonical | Polymorphic utility types for DS-local extension (`as`, `asChild`, ref forwarding). | - | - | 2 | Type-only infrastructure. |
+| ThemePanel | Foundations | composite | canonical | Theme configuration panel for color, gray, radius, density, and scaling. | - | Sheet, SegmentedControl, Field, ColorSwatch | 5 | Primarily used in product shell for theme switcher. |
+| ConfigDrawer | Foundations | composite | canonical | App-config drawer pattern that exposes theme and density controls. | - | Sheet, SegmentedControl, Field, ColorSwatch | 5 | Composed from shell primitives; app owns the actual config keys. |
+| AccessibleIcon | Primitives | radix-wrapper | canonical | Icon wrapper that exposes an accessible label to assistive tech. | - | Icon | 1 | Radix wrapper. |
+| AspectRatio | Primitives | radix-wrapper | canonical | Maintains a fixed width-to-height ratio for media surfaces. | - | - | 1 | Radix wrapper. |
+| Avatar | Primitives | composite | canonical | User or entity identity surface with image and initials fallback. | `Avatar.Root`, `Avatar.Image` | - | 1 | Use initials fallback by default; group overflow via `+N`. |
+| Badge | Primitives | primitive | canonical | Compact status, metadata, or filter token. | - | - | 1 | Carries `label-medium` uppercase utility by convention. |
+| Button | Primitives | primitive | canonical | Primary interactive surface; CTAs, secondary actions, and toggles. | - | - | 1 | Sparingly use `primary` for CTAs. Shares `baseButton.props` infra. |
+| Checkbox | Primitives | radix-compound | canonical | Independent boolean or tri-state selection control. | `Checkbox.Root`, `Checkbox.Indicator` | - | 1 | Use for yes/no; use `Switch` for settings. |
+| ColorSwatch | Primitives | primitive | canonical | Visual swatch of a color value; intentionally excluded from `data-accent-color` theming. | - | - | 1 | Canon says it must not theme with the rest; canonical spec verified against package source. |
+| CopyButton | Primitives | composite | canonical | One-click clipboard copy with inline confirmation state. | - | Button, Icon | 1 | Uses `navigator.clipboard`; provide `aria-label`. |
+| Icon | Primitives | primitive | canonical | Named icon surface backed by `lucide-react`. | - | - | 1 | Approved set, sizes, and stroke in `docs/design-system/foundations/iconography.md`. |
+| IconButton | Primitives | primitive | canonical | Compact icon-only button with required accessible name. | - | Button, Icon | 1 | Always needs `aria-label`. |
+| Input | Primitives | primitive | canonical | Standard single-line text entry. | - | - | 1 | Raw text; use `Field` for form rows. |
+| Label | Primitives | primitive | canonical | Accessible label association for a single control. | - | - | 1 | Use direct `Label` only for simple pairings; use `Field.Label` for full rows. |
+| Progress | Primitives | composite | canonical | Determinate progress indicator for known-duration work. | `Progress.Root`, `Progress.Indicator` | - | 1 | Use determinate; indeterminate is `Spinner`. |
+| SegmentedMeter | Primitives | primitive | canonical | Discrete n-of-m capacity meter (e.g. "3 of 5 device slots used"). | - | - | 1 | Distinct from the proposed continuous `Meter` (scalar-in-range) and from `Progress` (continuous, single-value). Sized like `Progress`: reuses `--dsx-progress-height` at each `size`. |
+| Separator | Primitives | radix-wrapper | canonical | Visual divider; horizontal or vertical. | - | - | 1 | Use only when spacing alone is insufficient. |
+| Skeleton | Primitives | primitive | canonical | Loading placeholder that mirrors eventual layout. | - | - | 1 | Match layout closely enough to avoid CLS, avoid over-detailed fake UI. |
+| Slider | Primitives | radix-compound | canonical | Bounded numeric range with draggable thumb. | `Slider.Root`, `Slider.Track`, `Slider.Range`, `Slider.Thumb` | - | 1 | For ranges; use `NumberInput` for exact entry. |
+| Slot | Primitives | radix-wrapper | canonical | Radix `Slot` helper for `asChild` composition. | - | - | 1 | Type/utility surface, not visual. |
+| Spinner | Primitives | primitive | canonical | Indeterminate loading indicator for short, local async work. | - | - | 1 | Inline in Buttons, Badges, InputGroup, EmptyState. |
+| Switch | Primitives | radix-compound | canonical | Immediate on/off setting. | `Switch.Root`, `Switch.Thumb` | - | 1 | For settings; use `Checkbox` for choices. |
+| TextArea | Primitives | primitive | canonical | Multiline freeform text entry. | - | - | 1 | Raw text; use `Field` for form rows. |
+| Toggle | Primitives | primitive | canonical | Independent pressed/unpressed button-scale control. | - | Button | 1 | For formatting/view modes; use `ToggleGroup` for coordinated state. |
+| Tooltip | Primitives | radix-compound | canonical | Brief, non-essential explanatory text on hover or focus. | `Tooltip.Root`, `Tooltip.Trigger`, `Tooltip.Content`, `TooltipProvider` | - | 1 | Brief, non-essential; for essential info use `Field.Description` or visible text. |
+| VisuallyHidden | Primitives | radix-wrapper | canonical | Visually hides content while keeping it available to assistive tech. | - | - | 1 | Radix wrapper. |
+| Text | Primitives | primitive | canonical | App-level body text primitive with token-aligned typography. | - | - | 2 | App-facing Text; `FoundationText` lives in `foundations/`. |
+| Heading | Primitives | primitive | canonical | App-level heading primitive with token-aligned typography. | - | - | 2 | App-facing Heading; `FoundationHeading` lives in `foundations/`. |
+| Blockquote | Primitives | primitive | canonical | Styled block quotation surface. | - | - | 2 | Canonical spec verified against package source. |
+| Code | Primitives | primitive | canonical | Inline code token surface. | - | - | 2 | For multi-line, use a `pre > Code` composition. |
+| Em | Primitives | primitive | canonical | Inline emphasis span. | - | - | 2 | Canonical spec verified against package source. |
+| Kbd | Primitives | primitive | canonical | Keyboard shortcut token surface for command and toolbar hints. | - | - | 2 | Canonical spec verified against package source. |
+| Link | Primitives | primitive | canonical | Anchor element with token-aligned typography and color. | - | - | 2 | External vs internal handled via prop. |
+| Quote | Primitives | primitive | canonical | Inline quotation span. | - | - | 2 | Companion to `Blockquote`. Canonical spec verified. |
+| Strong | Primitives | primitive | canonical | Inline strong span. | - | - | 2 | Canonical spec verified against package source. |
+| Combobox | Components | radix-compound | canonical | Search-first option picker for large option sets. | `Combobox.Root`, `Combobox.Trigger`, `Combobox.Content`, `Combobox.Input`, `Combobox.List`, `Combobox.Empty`, `Combobox.Item`, `Combobox.Group` | Popover, Command | 3 | Multi-mode can cover the MultiSelect gap. |
+| Editable | Components | composite | canonical | Inline-editable text cell. | `Editable.Root`, `Editable.Preview`, `Editable.Input` | Text | 3 | Type-checking failure noted in Phase 6 audit; needs fix. |
+| Field | Components | composite | canonical | Default form-control wrapper combining label, control, description, and error. | `Field.Root`, `Field.Label`, `Field.Title`, `Field.Content`, `Field.Description`, `Field.Error`, `Field.Set`, `Field.Legend`, `Field.Group` | Label, Text | 3 | Preferred wrapper for form specs in the design repo. |
+| Form | Components | composite | canonical | Orchestration layer around `Field` for form-level validation and submission. | `Form.Root`, `Form.Item`, `Form.Label`, `Form.Control`, `Form.Message`, `Form.Header`, `Form.Title`, `Form.Description`, `Form.Body`, `Form.Actions` | Field | 3 | Treated as orchestration; not a visual replacement for Field. |
+| InputOtp | Components | composite | canonical | Verification-code and short-PIN entry. | `InputOtp.Root`, `InputOtp.Group`, `InputOtp.Slot`, `InputOtp.Separator` | Input, Separator | 3 | Verification only; not a generic multi-field input. |
+| NativeSelect | Components | composite | canonical | Native browser `<select>` wrapper for mobile-first option pickers. | `NativeSelect.Root`, `NativeSelect.Option`, `NativeSelect.OptionGroup` | - | 3 | Marked `[FUTURE]` in `design-system-index.md`; revisit when mobile-native patterns become standard. |
+| NumberInput | Components | primitive | canonical | Spinbutton with increment/decrement for bounded numeric entry. | - | Input, IconButton | 3 | Implemented; spec missing. Compose over `Input` with `IconButton` steppers. |
+| PasswordInput | Components | primitive | canonical | Password entry with visibility toggle. | - | - | 3 | Visibility toggle via `IconButton`; spec missing. |
+| SearchBar | Components | composite | canonical | Search field with command-palette-style results menu. | `SearchBar.Root`, `SearchBar.Trigger`, `SearchBar.Menu` | Command, Input | 3 | Composes Command; ideal for search-first flows. |
+| Select | Components | radix-compound | canonical | Controlled option picker for known, medium-sized lists. | `Select.Root`, `Select.Trigger`, `Select.Content`, `Select.Group`, `Select.Value`, `Select.Label`, `Select.Item`, `Select.Separator`, `Select.ItemText` | Popover | 3 | Use for known lists; use Combobox for large or search-first sets. |
+| TagsInput | Components | primitive | canonical | Tag entry with chip-style value display. | - | Input, Badge, IconButton | 3 | Canonical spec verified against package source. |
+| TextField | Components | composite | canonical | Composite label-plus-input-plus-error field for fast form rows. | `TextField.Root`, `TextField.Input`, `TextField.Slot` | Label, Text, Input | 3 | Convenience composition; prefer explicit `Field` for new specs. |
+| ButtonGroup | Components | composite | canonical | Adjacent button cluster without pressed state. | - | Button | 3 | For related actions, not state selection. |
+| CheckboxGroup | Components | composite | canonical | Multi-select checkbox cluster with shared label. | `CheckboxGroup.Root`, `CheckboxGroup.Item`, `CheckboxGroup.Label` | Checkbox, Field | 3 | For grouped yes/no choices. |
+| InputGroup | Components | composite | canonical | Input wrapper with leading/trailing addons, inline buttons, or text. | `InputGroup.Root`, `InputGroup.Addon`, `InputGroup.Text`, `InputGroup.Button`, `InputGroup.Input`, `InputGroup.Textarea` | Input, Button | 3 | Ideal for search fields, URLs, copy/share flows. |
+| RadioGroup | Components | composite | canonical | Mutually exclusive choice cluster. | `RadioGroup.Root`, `RadioGroup.Item` | - | 3 | For 2+ mutually exclusive options. |
+| SegmentedControl | Components | composite | canonical | Single-select sliding-indicator control, ToggleGroup-backed. | `SegmentedControl.Root`, `SegmentedControl.Item` | ToggleGroup | 3 | Keep distinct: SegmentedControl = single-select visual switch in forms/toolbars; Tabs = peer views with linked panels; ToggleGroup = multi-select/view-mode cluster. |
+| ToggleGroup | Components | radix-compound | canonical | Coordinated segmented state cluster with multi-select option. | `ToggleGroup.Root`, `ToggleGroup.Item` | Toggle | 3 | Use for view selectors, formatting clusters. |
+| FileUpload | Components | composite | canonical | File selection with preview and metadata. | - | Button, Input, Icon | 3 | Drop-zone variant is proposed; see Proposed Additions. |
+| CheckboxCards | Components | composite | canonical | Card-style multi-select cluster with internal indicator. | `CheckboxCards.Root`, `CheckboxCards.Item`, `CheckboxCards.Indicator` | Checkbox, Card | 4 | Canonical spec verified against package source. |
+| RadioCards | Components | composite | canonical | Card-style mutually exclusive cluster. | `RadioCards.Root`, `RadioCards.Item`, `RadioCards.Indicator` | RadioGroup, Card | 4 | Canonical spec verified against package source. |
+| AlertDialog | Components | radix-compound | canonical | High-stakes destructive confirmation modal. | `AlertDialog.Root`, `AlertDialog.Trigger`, `AlertDialog.Overlay`, `AlertDialog.Content`, `AlertDialog.Title`, `AlertDialog.Description`, `AlertDialog.Action`, `AlertDialog.Cancel` | Dialog | 4 | Reserve for destructive or irreversible actions. |
+| Dialog | Components | radix-compound | canonical | Modal dialog for focused task interruption. | `Dialog.Root`, `Dialog.Trigger`, `Dialog.Overlay`, `Dialog.Content`, `Dialog.Title`, `Dialog.Description`, `Dialog.Close` | - | 4 | Modal; for non-modal see Popover, Sheet, Drawer. |
+| Drawer | Components | radix-compound | canonical | Mobile or edge-attached modal overlay. | `Drawer.Root`, `Drawer.Trigger`, `Drawer.Content`, `Drawer.Title`, `Drawer.Description`, `Drawer.Close` | Dialog | 4 | Keep distinct from Sheet. Drawer is a mobile/edge modal overlay; Sheet is a non-modal side/complementary panel. Both share the Dialog base. |
+| HoverCard | Components | radix-compound | canonical | Sighted-only preview surface for secondary context. | `HoverCard.Root`, `HoverCard.Trigger`, `HoverCard.Content` | Popover | 4 | For sighted users only; do not hide essential info here. |
+| Popover | Components | radix-compound | canonical | Interactive contextual floating surface. | `Popover.Root`, `Popover.Trigger`, `Popover.Content`, `Popover.Close` | - | 4 | More interactive than Tooltip, less blocking than Dialog. |
+| Sheet | Components | radix-compound | canonical | Edge-attached complementary panel. | `Sheet.Root`, `Sheet.Trigger`, `Sheet.Overlay`, `Sheet.Content`, `Sheet.Title`, `Sheet.Description`, `Sheet.Close` | Dialog | 4 | For side panels, filters, complementary context. Keep distinct from Drawer. |
+| ToggleTip | Components | composite | canonical | Click-to-toggle tooltip variant for touch and keyboard parity. | - | Popover | 4 | Canonical spec verified against package source. |
+| FloatingPanel | Components | composite | canonical | Generic floating content surface with drag, resize, and persistent placement. | `FloatingPanel.Root`, `FloatingPanel.Header`, `FloatingPanel.Content`, `FloatingPanel.Handle` | - | 4 | Heavy surface; spec missing. |
+| Breadcrumb | Components | composite | canonical | Location-hierarchy navigation trail. | `Breadcrumb.Root`, `Breadcrumb.List`, `Breadcrumb.Item`, `Breadcrumb.Link`, `Breadcrumb.Page`, `Breadcrumb.Separator`, `Breadcrumb.Ellipsis` | Link, Separator | 4 | For hierarchy, not action history. |
+| Command | Components | composite | canonical | Search-and-act command palette, cmdk-backed. | `Command.Root`, `Command.Input`, `Command.List`, `Command.Group`, `Command.Separator`, `Command.Item`, `Command.Empty` | Input, Dialog | 4 | Package owns palette anatomy; app owns command registry, permissions, and action execution. |
+| Menu | Components | utility | canonical | Internal abstraction shared by DropdownMenu, ContextMenu, and Menubar. | `Menu.Root`, `Menu.Trigger`, `Menu.Content`, `Menu.Item`, `Menu.Separator` | - | 4 | Keep internal. Public surfaces are DropdownMenu, ContextMenu, Menubar. Promote only if a fourth public menu surface needs the shared primitive. |
+| Menubar | Components | radix-compound | canonical | App-style horizontal command menu bar. | `Menubar.Root`, `Menubar.Trigger`, `Menubar.Content`, `Menubar.Label`, `Menubar.Separator`, `Menubar.Item`, `Menubar.Group` | Menu | 4 | For app-like command menus, not site navigation. |
+| NavigationMenu | Components | radix-compound | canonical | Site navigation with panels, previews, and grouped destinations. | `NavigationMenu.Root`, `NavigationMenu.List`, `NavigationMenu.Item`, `NavigationMenu.Trigger`, `NavigationMenu.Content`, `NavigationMenu.Link`, `NavigationMenu.Indicator`, `NavigationMenu.Viewport` | - | 4 | For site navigation with rich panels. |
+| Pagination | Components | composite | canonical | Page-based dataset navigation. | `Pagination.Root`, `Pagination.List`, `Pagination.Item`, `Pagination.Link`, `Pagination.Previous`, `Pagination.Next`, `Pagination.Ellipsis`, `Pagination.Info`, `Pagination.PageSize` | Button | 4 | For page-based datasets, not infinite scroll. |
+| Sidebar | Components | composite | canonical | Panel/cabinet shell navigation surface. | `Sidebar.Provider`, `Sidebar.Root`, `Sidebar.Header`, `Sidebar.Content`, `Sidebar.Footer`, `Sidebar.Group`, `Sidebar.GroupLabel`, `Sidebar.GroupAction`, `Sidebar.GroupContent`, `Sidebar.Menu`, `Sidebar.MenuItem`, `Sidebar.MenuBadge`, `Sidebar.MenuAction`, `Sidebar.MenuButton`, `Sidebar.MenuSkeleton`, `Sidebar.MenuSub`, `Sidebar.MenuSubItem`, `Sidebar.MenuSubButton`, `Sidebar.Separator`, `Sidebar.Trigger`, `Sidebar.Rail`, `Sidebar.Inset` | Button, Input, Tooltip, Card | 4 | App owns routing, auth, nav data, permissions, and page orchestration. |
+| PageHeader | Components | composite | canonical | Fixed-height content-area header bar: title + trailing actions. | `PageHeader.Root`, `PageHeader.Title`, `PageHeader.Actions` | - | 4 | Designed to sit as the first child inside `.dsx-sidebar__inset`. Closes the gap where every cabinet screen invented its own header height/padding. |
+| PageContent | Components | primitive | canonical | Content-region wrapper with a canonical padding scale (`sm`/`md`/`lg`). | - | - | 4 | Sibling of `PageHeader`; sits below it inside `.dsx-sidebar__inset`. Not compound: a single padded region, not a layout primitive with responsive style props. |
+| TabNav | Components | primitive | canonical | Simpler horizontal tab bar alternative to `Tabs`. | `TabNav`, `TabNav.List`, `TabNav.Link` | - | 4 | Canonical spec verified against package source. |
+| Tabs | Components | radix-compound | canonical | Peer views of equal hierarchy with linked panels. | `Tabs.Root`, `Tabs.List`, `Tabs.Trigger`, `Tabs.Content` | - | 4 | For peer views; for one-of-many use SegmentedControl or ToggleGroup. |
+| ContextMenu | Components | radix-compound | canonical | Object-scoped right-click action menu. | `ContextMenu.Root`, `ContextMenu.Trigger`, `ContextMenu.Content`, `ContextMenu.Label`, `ContextMenu.Separator`, `ContextMenu.Item`, `ContextMenu.Group` | Menu | 4 | For actions on a target object. |
+| DropdownMenu | Components | radix-compound | canonical | Button-triggered secondary action menu. | `DropdownMenu.Root`, `DropdownMenu.Trigger`, `DropdownMenu.Content`, `DropdownMenu.Label`, `DropdownMenu.Separator`, `DropdownMenu.Item`, `DropdownMenu.Group` | Menu | 4 | For compact secondary actions from a button trigger. |
+| Accordion | Components | composite | canonical | Vertically stacked, mutually exclusive or multi-open disclosure list. | `Accordion.Root`, `Accordion.Item`, `Accordion.Header`, `Accordion.Trigger`, `Accordion.Content` | Collapsible | 5 | Trigger owns its default/custom/hidden indicator. `ItemBody` and `ItemIndicator` remain compatibility exports outside canonical anatomy. |
+| Alert | Components | composite | canonical | Inline status, warning, or info banner. | `Alert.Root`, `Alert.Title`, `Alert.Description`, `Alert.Action` | Icon, Button | 5 | For in-page flow; for transient notifications use Toast or Sonner. |
+| Callout | Components | composite | canonical | Authored or inline notice with semantic tone, title, message, and optional actions. | `Callout.Root`, `Callout.Icon`, `Callout.Title`, `Callout.Text`, `Callout.Actions` | - | 5 | Stable authored HTML uses `data-dsx-*`; app owns dismissal. |
+| Card | Components | composite | canonical | Grouped content block with header, body, and footer hierarchy. | `Card.Root`, `Card.Header`, `Card.Title`, `Card.Description`, `Card.Content`, `Card.Footer` | Box | 5 | Canonical variants are `default` and `glass`; `outline` is compatibility-only. |
+| Collapsible | Components | radix-compound | canonical | Lightweight show/hide region inside cards or panels. | `Collapsible.Root`, `Collapsible.Trigger`, `Collapsible.Content` | - | 5 | Use Accordion for stacked disclosures. |
+| DataList | Components | composite | canonical | Structured list surface for metadata, attributes, or settings rows. | `DataList.Root`, `DataList.Item`, `DataList.Media`, `DataList.Content`, `DataList.Text`, `DataList.Metadata`, `DataList.Badge`, `DataList.Actions` | Item | 5 | Canonical spec verified against package source. |
+| DataTable | Components | composite | canonical | Advanced controlled/uncontrolled data table with responsive columns, sort, selection, pagination, and list states. | `DataTable.Root`, `DataTable.Toolbar`, `DataTable.Pagination`, `DataTable.FacetedFilter` | Table, Pagination, Result | 5 | DS emits query/selection changes; apps own fetching and server execution. |
+| Result | Components | composite | canonical | Unified success, failure, expired, loading, empty, no-results, and error result surface. | `Result.Root`, `Result.Icon`, `Result.Title`, `Result.Description`, `Result.Metadata`, `Result.Steps`, `Result.Actions` | - | 5 | State semantics and tone are independent. |
+| EmptyState | Components | composite | canonical | Deprecated compatibility wrapper for the canonical empty Result state. | - | Result | 5 | Preserves 2.5 imports and variants. |
+| Prose | Components | composite | canonical | Tokenized read-side article typography constrained for comfortable reading. | - | Callout, article renderers | 6 | HTML must be consumer-sanitized. |
+| TableOfContents | Components | composite | canonical | Stable-anchor article navigation with scroll-spy and responsive sticky behavior. | - | Prose | 6 | Consumes authored heading IDs. |
+| SortableList | Components | adapter-backed | canonical | Accessible vertical reorder surface for pointer, touch, and keyboard input. | `SortableList.Root`, `SortableList.Item`, `SortableList.Handle`, `SortableList.Overlay` | `@dnd-kit/*` | 6 | Emits the complete reordered ID array; data persistence is app-owned. |
+| CommentThread | Components | composite | canonical | Controlled one-level discussion thread with composer, moderation affordances, and tombstones. | `CommentThread.Root`, `CommentThread.Comment`, `CommentThread.Replies`, `CommentThread.Tombstone`, `CommentThread.Composer`, `CommentThread.Locked` | - | 6 | Data, permissions, localization, and persistence are app-owned. |
+| Item | Components | composite | canonical | Generic list-row surface for settings, notifications, or selectable summaries. | - | Box, Text, Badge | 5 | Strong fit for settings rows, notifications, list entries. |
+| Marquee | Components | primitive | canonical | Horizontally scrolling content strip with pause-on-hover. | - | - | 5 | Canonical spec verified against package source. |
+| Pills | Components | composite | canonical | Compact cluster of selectable or status pills. | - | Badge, Button | 5 | Use for filters, tags, segmented status. |
+| Rating | Components | primitive | canonical | Star-based rating control. | - | Icon, Button | 5 | Canonical spec verified against package source. |
+| Metric | Components | composite | canonical | Surface-neutral metric anatomy with a label, tabular value, and semantic delta. | `Metric.Root`, `Metric.Label`, `Metric.Value`, `Metric.Delta` | Text, Icon | 5 | Canonical replacement for the proposed `Statistic`; consumers choose the surrounding surface. |
+| StatCard | Components | composite | canonical | Headline metric card with value, label, and trend. | - | Card, Text, Badge, Icon | 5 | For dashboards and KPI summaries. |
+| FilterBar | Components | composite | canonical | Responsive, wrapping filter toolbar with grouped controls, summary, actions, and clear affordance. | `FilterBar.Root`, `FilterBar.Group`, `FilterBar.Summary`, `FilterBar.Actions`, `FilterBar.Clear` | Toolbar, Button | 5 | Filter values and query execution remain consumer-controlled. |
+| CopyField | Components | composite | canonical | Read-only field that exposes a value and delegates clipboard feedback to CopyButton. | - | Field, InputGroup, Input, CopyButton | 5 | Clipboard state and timing stay owned by CopyButton. |
+| CodeInput | Components | composite | canonical | Controlled code-entry field with checking, accepted, and rejected status presentation. | - | Field, InputGroup, Input, Spinner, Icon | 5 | Consumer owns debounce, server calls, validation policy, and status transitions. |
+| Status | Components | primitive | canonical | Compact status indicator with semantic color and label. | - | - | 5 | Canonical spec verified against package source. |
+| Table | Components | composite | canonical | Read-heavy structured data table. | `Table.Root`, `Table.Caption`, `Table.Header`, `Table.Body`, `Table.Footer`, `Table.Row`, `Table.Head`, `Table.Cell`, `Table.ColumnHeaderCell`, `Table.RowHeaderCell` | - | 5 | Use plain `Table` for read-heavy data; advanced features go to `DataTable`. |
+| Timeline | Components | composite | canonical | Vertical or horizontal event timeline. | `Timeline.Root`, `Timeline.Item`, `Timeline.Marker`, `Timeline.Connector`, `Timeline.Content` | Text, Badge, Icon | 5 | For activity feeds, audit logs. |
+| Toolbar | Components | composite | canonical | Dense editor or action strip with arrow-key movement. | `Toolbar.Root`, `Toolbar.Button`, `Toolbar.ToggleButton`, `Toolbar.ToggleGroup`, `Toolbar.Link`, `Toolbar.Separator` | Button, Toggle, ToggleGroup, Separator | 5 | For dense editor and rich-text surfaces. |
+| NotificationCenter | Components | composite | canonical | Inbox-style notification surface with grouped entries. | - | Sonner, Toast, Card, DataList | 5 | Pattern-level; groups notifications into a panel. |
+| Stepper | Components | composite | canonical | Multi-step wizard or progress indicator. | `Stepper.Root`, `Stepper.Item`, `Stepper.Indicator`, `Stepper.Label`, `Stepper.Description`, `Stepper.Separator`, `Stepper.Content` | Progress, Separator, Text, Button | 5 | HIERARCHY called this a pattern because of Penpot delivery; in code it is a multi-slot composite component. MUST compose primitive Indicator + Separator + Label parts. |
+| Shell (Cabinet) | Components | pattern | spec-only-proposed | Customizable application shell for cabinet, admin, and authenticated product areas. | `Shell.Root`, `Shell.Header`, `Shell.Sidebar`, `Shell.Content`, `Shell.Footer` | Sidebar, Toolbar, Card, DataList, EmptyState, layout, typography | 5 | Not yet implemented in the package. Cabinet shell is the primary use case; app owns routing, auth, permissions, and nav data. |
+| Calendar | Components | adapter-backed | canonical | Lower-level date-selection primitive. | - | react-day-picker | 6 | Canonical spec verified against package source. Stays lower-level underneath `DatePicker`. |
+| Carousel | Components | adapter-backed | canonical | Horizontal content carousel with autoplay and gesture support. | `Carousel.Root`, `Carousel.Viewport`, `Carousel.Item`, `Carousel.Previous`, `Carousel.Next`, `Carousel.Indicators` | Embla | 6 | Canonical spec verified against package source. |
+| Chart | Components | adapter-backed | canonical | Token-aligned chart shell with line, bar, and pie primitives. | `Chart.Container`, `Chart.Line`, `Chart.Bar`, `Chart.Pie`, `Chart.Empty`, `Chart.Legend`, `Chart.LegendItem` | Recharts | 6 | Package owns shell and tokens; app owns analytics semantics. |
+| ColorPicker | Components | adapter-backed | canonical | Color value picker with swatch and inputs. | - | Popover, ColorSwatch | 6 | Canonical spec verified against package source. Uses Popover internally. |
+| DatePicker | Components | adapter-backed | canonical | Product-facing single-date selection with popover calendar. | - | Calendar, Popover, Button, Input | 6 | MUST compose `Calendar + Popover`; stays single-date only. |
+| QRCode | Components | adapter-backed | canonical | QR code generator. | - | qrcode.react | 6 | Canonical spec verified against package source. |
+| Resizable | Components | adapter-backed | canonical | Resizable panel group with draggable handles. | `Resizable.PanelGroup`, `Resizable.Panel`, `Resizable.Handle` | react-resizable-panels | 6 | Adapter-backed. |
+| RichTextEditor | Components | adapter-backed | canonical | Productized Tiptap editor shell. | `RichTextEditor.Root`, `RichTextEditor.Shell`, `RichTextEditor.Toolbar`, `RichTextEditor.ToolbarButton`, `RichTextEditor.Content` | Tiptap, Toolbar | 6 | Canonical spec verified against package source. Package owns shell; app owns schema, serialization, and extensions. |
+| ArticleNodes | Components | adapter-backed | canonical | Stable authoring extensions and matching read-side renderers for article media and custom blocks. | `ArticleImage`, `ArticleEmbed`, `BeforeAfterComparison`, `ArticlePoll` | Tiptap, Lowlight, Callout | 6 | HTML attributes are the interoperability contract; network and persistence remain app-owned. |
+| ScrollArea | Components | radix-compound | canonical | Custom-styled scroll viewport. | `ScrollArea.Root`, `ScrollArea.Viewport` | - | 6 | Good for bounded menus, panels, long option lists. |
+| Sonner | Components | adapter-backed | canonical | Modern toast surface. | - | sonner | 6 | Prefer over Toast for new spec; keep Toast knowledge for low-level control. |
+| TimePicker | Components | adapter-backed | canonical | Dropdown-based time selection. | - | Popover, NativeSelect, Input | 6 | Canonical spec verified against package source. Uses Popover internally. |
+| Toast | Components | radix-compound | canonical | Low-level toast surface, Radix-backed. | `Toast.Viewport`, `Toast.Root`, `Toast.Title`, `Toast.Description`, `Toast.Action`, `Toast.Close` | - | 6 | Prefer Sonner for new spec; keep Toast for low-level control. |
+| TreeView | Components | composite | canonical | Hierarchical tree with expand/collapse. | `TreeView.Root`, `TreeView.Item` | - | 6 | Canonical spec verified against package source. |
+
+## Batches
+
+| Batch | Theme | Components | Goal |
+|---|---|---|---|
+| 0 | Roster and taxonomy | (this file) | Lock the inventory, taxonomy, archetype, status, and slot mapping before any work. |
+| 1 | Core primitives | AccessibleIcon, AspectRatio, Avatar, Badge, Button, Checkbox, ColorSwatch, CopyButton, Icon, IconButton, Input, Label, Progress, Separator, Skeleton, Slider, Slot, Spinner, Switch, TextArea, Toggle, Tooltip, VisuallyHidden | Lock primitives first. All other work depends on these tokens, variants, and slot conventions. |
+| 2 | Layout and typography | Box, Container, Flex, Grid, Inset, Layout (props), Section, Stack, Theme, ThemeProvider, DirectionProvider, FontProvider, Typography, Shared, Text, Heading, Blockquote, Code, Em, Kbd, Link, Quote, Strong | Foundation infrastructure and typography. Hosts the spec targets for batch 0 conventions. |
+| 3 | Form components | Combobox, Editable, Field, Form, InputOtp, NativeSelect, NumberInput, PasswordInput, SearchBar, Select, TagsInput, TextField, ButtonGroup, CheckboxGroup, InputGroup, RadioGroup, SegmentedControl, ToggleGroup, FileUpload | Wire all form components to the batch 1 primitives and the Field/Form pattern. Add the missing specs for implemented surfaces. |
+| 4 | Overlays and navigation | CheckboxCards, RadioCards, AlertDialog, Dialog, Drawer, HoverCard, Popover, Sheet, ToggleTip, FloatingPanel, Breadcrumb, Command, Menu, Menubar, NavigationMenu, Pagination, Sidebar, TabNav, Tabs, ContextMenu, DropdownMenu | Lock overlay and navigation behavior. Resolve Drawer vs Sheet. Wire `Menu` abstraction explicitly. |
+| 5 | Data display and patterns | ThemePanel, ConfigDrawer, Accordion, Alert, Card, Collapsible, DataList, DataTable, EmptyState, Item, Marquee, Pills, Rating, StatCard, Status, Table, Timeline, Toolbar, NotificationCenter, Stepper, Cabinet Shell | Lock Card, Table, DataList, DataTable, and Stepper composition. Hard-canonize the Cabinet Shell pattern. |
+| 6 | Adapter-backed heavy components | Calendar, Carousel, Chart, ColorPicker, DatePicker, QRCode, Resizable, RichTextEditor, ScrollArea, Sonner, TimePicker, Toast, TreeView | Resolve adapter boundaries. Confirm `DatePicker = Calendar + Popover`, `DataTable = Table + Pagination + Toolbar + SearchBar + EmptyState`, and the heavy-component ownership contract. |
+
+## Proposed Additions
+
+Components common across major design systems (Radix, shadcn/ui, Chakra v3, Mantine v7, Ant Design v6, React Aria) but not currently in the package. Each is a candidate, not a commitment: spec work begins only when a real product need appears or a `package-stage` row above is promoted first.
+
+| Component | Category | Archetype | Suggested Batch | Justification | Reference systems |
+|---|---|---|---|---|---|
+| List / ListItem | Primitives | primitive | 2 or 5 | Generic ordered/unordered list primitive. DataList is opinionated and Table is heavy; a minimal List fills the gap. | Chakra, Mantine, Ant |
+| Tag / Chip | Primitives | primitive | 1 or 5 | Dismissible label and filter chip. Pills covers the cluster pattern; a single Tag primitive would simplify forms and Pills' internals. | Chakra, Mantine, Ant, React Aria |
+| Description List | Components | composite | 5 | Key-value description list for entity detail pages. Strong fit alongside Card and DataList. | Ant, Mantine (via Table/Style) |
+| ProgressCircle / RingProgress | Primitives | primitive | 1 | Circular progress variant. `Progress` is linear only today. | Chakra, Mantine, Ant |
+| LoadingOverlay | Components | composite | 5 or 6 | Full-region spinner with scrim. Needed for inline region loading states that Spinner alone cannot express. | Mantine, Ant |
+| Meter | Primitives | primitive | 1 | Scalar measurement within a known range. Adds semantic clarity vs. Progress for non-progress values. | React Aria |
+| Tour | Components | pattern | 5 or 6 | Step-by-step onboarding overlay. Useful for first-run product flows. | Ant |
+| Watermark | Components | composite | 5 | Repeating text or image overlay for screenshots and shared content. | Ant |
+| DropZone | Components | composite | 3 | Drag-and-drop file target. Composes on top of FileUpload. | React Aria |
+| GridList | Components | composite | 5 | Accessible grid-of-cards with arrow-key navigation. Composes on Item and Card. | React Aria |
+| AppShell / Layout | Foundations | pattern | 5 | Higher-level app-shell composition that wraps Sidebar, Topbar, and content. Cabinet Shell is one variant; a generic AppShell generalizes the pattern. | shadcn (Sidebar), Mantine, Ant |
+| DateTimePicker | Components | adapter-backed | 6 | Combined date and time selection. Composes on DatePicker and TimePicker. | Mantine, Ant |
+| MonthPicker / YearPicker | Components | adapter-backed | 6 | Lower-density date pickers for credit-card and DOB flows. Composes on Calendar. | Mantine, Ant |
+| DateRangePicker | Components | adapter-backed | 6 | Date range selection. Pairs with DatePicker and Calendar; range semantics not owned by DatePicker. | Mantine, Ant, React Aria |
+| Cascader | Components | composite | 3 | Hierarchical multi-step option picker. | Ant |
+| Mentions | Components | composite | 3 | At-mention autocomplete in text inputs. | Ant, shadcn (community) |
+| Affix / BackTop | Components | composite | 5 | Sticky element with scroll-to-top behavior. | Mantine, Ant |
+| Highlight | Primitives | primitive | 2 | Inline search-result highlighting. Common in search-first surfaces. | Chakra, Mantine |
+| Mark | Primitives | primitive | 2 | Inline `<mark>` element with token-aligned styling. | Mantine |
+| SkipNav | Utilities | utility | 4 | Skip-to-content link for keyboard users. Accessibility hygiene. | Chakra |
+| Popconfirm | Components | composite | 4 | Confirmation popover on action click. Lightweight alternative to AlertDialog. | Ant |
+| Masonry | Components | composite | 5 | Pinterest-style staggered grid. Niche but expected in content surfaces. | Ant |
+| Transfer | Components | composite | 5 | Two-panel list transfer control. Niche but expected in admin surfaces. | Ant |
+| Spotlight | Components | pattern | 4 | Spotlight-style command launcher with keyboard chord. Composes on Command. | Mantine |
+| MultiSelect | Components | composite | 3 | Native multi-select wrapper. Could be satisfied by Combobox multi mode; promote to a first-class surface only if the gap is real. | Mantine, Ant, React Aria |
+
+## Wiring notes
+
+These are the explicit composition calls the user surfaced during planning. Each row here is a wiring contract; the package should fail loudly if any of these break.
+
+- `DatePicker` MUST compose `Calendar + Popover`. Selection state and single-date mode stay owned by `DatePicker`; `Calendar` is a lower-level builder underneath.
+- `DataTable` MUST compose `Table + Pagination + Toolbar + SearchBar + EmptyState + Pills`. Filter chips use `Pills`; the package should not ship a second sort/filter/pagination implementation.
+- `Stepper` MUST compose primitive `Indicator + Separator + Label + Text + Button` parts. Visual rhythm is shared with `Progress` and `Breadcrumb.Separator`.
+- `ColorPicker` MUST compose `Popover + ColorSwatch`. It intentionally does not theme with `data-accent-color`.
+- `RichTextEditor.Shell` MUST compose `Toolbar` rather than ship a parallel toolbar. `RichTextEditor.Root` is the convenience default; `Shell` is the canon-aligned surface.
+- `Sidebar` is a cabinet shell, not a route registry. Routing, auth, nav data, and permissions are app-owned.
+- `Card` has canonical variants `default` and `glass`; `outline` is compatibility-only for older frontend usage.
+- `Sonner` is preferred for new toast spec; `Toast` remains for low-level control. Both ship until `Sonner` is fully canonized.
+- `Menu` is an internal abstraction. Public menu surfaces are `DropdownMenu`, `ContextMenu`, and `Menubar`. Apps should not import `Menu` directly.
+- `Theme` writes the full `data-dsx-*` attribute contract. `ThemeProvider` persists the user choice and re-applies it on mount.
+
+## Resolved decisions
+
+- **Drawer vs Sheet.** Keep both. Drawer is a mobile/edge-attached **modal** overlay; Sheet is a non-modal side/complementary panel. They share the Dialog base but have distinct roles.
+- **`Stepper` archetype.** It is a **composite component**, not a pattern. The HIERARCHY `pattern` label was a Penpot delivery artifact; the code has multi-slot anatomy.
+- **`SegmentedControl` boundary.** Keep all three. `SegmentedControl` = single-select visual switch for forms/toolbars; `Tabs` = peer views with linked panels; `ToggleGroup` = multi-select/view-mode cluster.
+- **`DataTable` ownership.** DS owns the visual shell and controlled sort/filter/density UI. App owns data fetching and the `PaginatedResponse` contract (`offset`, `limit`, `sortBy`, `sortOrder`, `totalCount`).
+- **`Menu` exposure.** Keep `Menu` internal. Public surfaces remain `DropdownMenu`, `ContextMenu`, `Menubar`. Promote only if a fourth public menu surface appears.
+- **`Cabinet Shell`.** Proposed as a customizable package component named `Shell`, with `Shell.Root`, `Shell.Header`, `Shell.Sidebar`, `Shell.Content`, `Shell.Footer`. It remains spec-only and does not ship yet. Cabinet shell is the primary use case; app owns routing/auth/nav data.
+
+## Open questions
+
+- **Internal `_internal/` files.** 44 infra files (BaseButton, BaseDialog, BaseSelect, css, props, helpers) are intentionally excluded from the roster. They are not user-facing.
+- **HIERARCHY.md archive.** The old `docs/feature/inventory/design-system/HIERARCHY.md` Penpot taxonomy should be archived once the roster is approved, since the roster is now the canonical taxonomy.

package/dist/docs/component-spec-template.md

@@ -0,0 +1,256 @@
+---
+title: <ComponentName>
+status: <canonical | package-stage | implemented-missing-spec | spec-only-proposed>
+category: <Foundations | Primitives | Components | Patterns | Utilities>
+archetype: <primitive | radix-wrapper | radix-compound | layout-primitive | composite | adapter-backed | pattern | utility>
+package_path: packages/d4gger-design-system/src/components/<kebab-name>/<Name>.tsx
+css_path: packages/d4gger-design-system/src/components/<kebab-name>/<name>.css
+props_path: packages/d4gger-design-system/src/components/<kebab-name>/<name>.props.ts
+test_path: packages/d4gger-design-system/src/components/<kebab-name>/<Name>.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/<category>.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - <other DS component names this composes from>
+---
+
+# <ComponentName>
+
+> 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
+
+<One sentence. What this component is, in the user's mental model. No marketing copy.>
+
+## Anatomy & slots
+
+**Parent:** `<ComponentName>` (alias of `Component.Root` when the component is a compound).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Component.Root` | `<element>` | DS primitive + class | <responsibility, default behavior> |
+| `Component.<Slot>` | `<element>` | DS primitive + class | <responsibility, default behavior> |
+
+For a non-compound component, list a single `Root` row and note "no slots: flat export".
+
+For an adapter-backed component, the slot table also names the adapter host: `Component.Line` → `recharts` `LineChart` wrapped in `ResponsiveContainer`.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `<prop>` | `<TS type>` | `<default or undefined>` | no | <one-line description> | `no` or `yes (initial, xs, sm, md, lg, xl, 2xl)` |
+
+Rules:
+
+- Every prop in this table must exist in `<name>.props.ts`. The runtime prop def is the source.
+- Every prop in `<name>.props.ts` must be in this table. Mismatches fail `qa:contracts`.
+- The `Responsive` column is `yes` only for props that mark `responsive: true` in the prop def.
+- `as` and `asChild` are polymorphic infra. They are listed in the table when the component is polymorphic.
+- Optional props default to `undefined` unless the prop def has a `default`.
+- The `Type` column uses TypeScript syntax. For enum props, list the enum values inline: `'primary' | 'secondary' | 'outline' | 'ghost'`.
+
+## CSS class contract
+
+**Root class:** `dsx-<name>`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `dsx-<name>--sm`, `dsx-<name>--md`, `dsx-<name>--lg` | `<name>.css` |
+| `data-variant` | `default`, `glass` | `dsx-<name>--default`, `dsx-<name>--glass` | `<name>.css` |
+| `data-state` | `open`, `closed`, `on`, `off` | `.dsx-<name>[data-state="open"]` | `<name>.css` |
+| `data-accent-color` | `amber`, `silver`, `bronze` | `.dsx-<name>[data-accent-color="amber"]` | `<name>.css` |
+| `data-high-contrast` | `true` | `.dsx-<name>[data-high-contrast="true"]` | `<name>.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | `.dsx-<name>[data-radius="..."]` | `<name>.css` |
+
+**Slot classes** (for compounds and composites):
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `<Name>.Root` | `dsx-<name>` | `<name>.css` |
+| `<Name>.Header` | `dsx-<name>__header` | `<name>.css` |
+| `<Name>.Content` | `dsx-<name>__content` | `<name>.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. Responsive sizing is driven by `responsive: true` prop defs and the layout primitives' responsive classes.
+- The component's CSS file is breakpoint-agnostic. Breakpoint-prefixed classes (`sm:`, `md:`, etc.) come from `src/styles/responsive/*.css`, not from this file.
+
+**Reduced motion:**
+
+- All motion respects `prefers-reduced-motion`. Gate framer-motion or CSS transitions behind `usePrefersReducedMotion` from `src/_internal/usePrefersReducedMotion.ts`.
+- When reduced motion is active, transitions collapse to `MOTION_TRANSITIONS.reduced` (duration `0`).
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token. List the token roles, not the values:
+
+| Property | Token | Role |
+|---|---|---|
+| Background | `var(--dsx-color-surface-raised)` | Default card surface |
+| Text | `var(--dsx-color-on-surface)` | Primary labels |
+| Border | `var(--dsx-color-outline)` | Edge |
+| Padding | `var(--dsx-space-md)` | Internal gutter |
+| Radius | `var(--dsx-radius-md)` | Standard roundness |
+| Shadow | `var(--dsx-shadow-card-sm)` | Default elevation |
+| Accent | `var(--dsx-color-primary)` | Active state |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in this table or in the CSS file.
+- Tokens come from `DESIGN.md` and the generated `tokens.css`. The token list is closed; new tokens are a `DESIGN.md` change first.
+- Alpha is only allowed in effect tokens. Shadow, focus ring, scrim, and hover overlays own transparency. Component color tokens stay solid.
+- Accent color comes through `var(--dsx-color-primary)` and the `data-accent-color` attribute. Components do not name brand colors directly.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| `<region>` | `MOTION_TRANSITIONS.<preset>` | `duration.normal`, `ease.emphasized` | `MOTION_TRANSITIONS.reduced` |
+| `<region>` | `none` | `none` | `none` |
+
+Rules:
+
+- Pick a `MOTION_TRANSITIONS` preset by name from `src/_internal/motion.ts`: `dialog`, `sheet`, `drawer`, `popover`, `combobox`, `menu`. Do not invent new presets.
+- For static regions, write `none` and skip the motion row.
+- All motion respects `prefers-reduced-motion`. The `Reduced` column is mandatory; do not leave it blank.
+- Token-driven motion: `var(--dsx-motion-duration-*)` and `var(--dsx-motion-easing-*)` are the tokenized values. The `MOTION_TRANSITIONS` presets are the JS-side bindings to framer-motion.
+
+## Accessibility
+
+**Roles:**
+
+- `<role>`. Match the WAI-ARIA pattern for the component.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to / from the next / previous focusable element. |
+| `Enter`, `Space` | Activates the control. |
+| `Escape` | Closes the overlay (for overlay components). |
+| Arrow keys | Navigates the slot list (for list-style components). |
+
+**Focus:**
+
+- Visible focus ring via `var(--dsx-ring-focus)`. The ring must remain visible on dark and light surfaces.
+- Focus management for overlay components: focus is trapped inside the overlay; focus returns to the trigger on close.
+
+**Reduced motion:**
+
+- Animations and transitions are disabled or reduced to opacity-only fades when `prefers-reduced-motion: reduce` matches. `MOTION_TRANSITIONS.reduced` is the fallback.
+
+**Color and meaning:**
+
+- State is not communicated by color alone. The icon, label, or text communicates the same state.
+
+**Naming:**
+
+- Every interactive element has an accessible name. Icon-only controls require `aria-label`.
+
+## Playground demo spec
+
+The Playground docs surface has two parts: the registry entry in `playground_registry_path` that imports the component and its prop defs and defines the render fixture, and the generic doc route at `demo_path` that renders every registered component. The demo spec describes what the registry render function must expose:
+
+**Default story:**
+
+- Renders the component with all defaults. No props passed.
+- Asserts the root class is `dsx-<name>`.
+
+**Variant story** (one per variant):
+
+- Renders the component with `<prop>=<value>` for each variant value.
+- Asserts the matching `data-*` attribute is set.
+
+**Composition story** (for composites):
+
+- Renders the component with each slot populated.
+- Asserts each slot renders the right element with the right class.
+
+**State story:**
+
+- Renders the component in each documented state (`default`, `hover`, `focus`, `disabled`, `loading`).
+
+**Token story:**
+
+- Renders the component inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`. Asserts the `data-accent-color` attribute is `silver` and `bronze` respectively.
+
+**A11y story:**
+
+- Uses `vitest-axe` to assert the rendered component has no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `<prop>` | `<select | text | boolean | number>` | `<default>` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `<DS component 1>`: `<role in this component>`.
+- `<DS component 2>`: `<role in this component>`.
+
+**Used by:**
+
+- `<DS component that uses this one>`: `<why>`.
+
+**State boundaries:**
+
+- Owned by this component: `<state 1>`, `<state 2>`.
+- Owned by the consumer: `<state 3>`, `<state 4>`. The consumer passes these in as props.
+
+**Boundary rules:**
+
+- App-owned data: `<list>`. Examples: route data, notification payloads, command registry, analytics semantics.
+- DS-owned visuals: `<list>`. Examples: token bindings, slot classes, motion presets.
+
+## 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.
+
+### Root board
+
+- **Name**: `<Category> / <Name>`.
+- **Dimensions**: `<width> × <height>`.
+- **Layout**: `<Flex | Fixed>`.
+- **Sizing**: `horizontalSizing = '<fix | auto | 100%>'`, `verticalSizing = '<fix | auto>'`.
+
+### Layer tree
+
+```
+<Root Board>
+  ├── <Child shape 1>
+  ├── <Child shape 2>
+  └── <Child shape 3>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| `<shape>` | `<fill | stroke | typography | spacing | radius | shadow>` | `<token name>` | `<Color | Spacing | ...>` | `<fills | strokes | ...>` |
+
+### State transformations
+
+| State | Root fill | Stroke | Text fill | Shadow |
+|---|---|---|---|---|
+| `default` | `<token>` | `<token>` | `<token>` | `<token>` |
+| `<state>` | `<token>` | `<token>` | `<token>` | `<token>` |
+
+### Variant model
+
+- `<prop>`: `<value 1>`, `<value 2>`. Default `<value 1>`.
+- `<prop>`: `<value 1>`, `<value 2>`. Default `<value 1>`.
+- Total members: `<count>`.
+
+### Validation checklist
+
+- [ ] Token bindings resolve at the values `DESIGN.md` describes.
+- [ ] Component is promoted to Main Component under `<Category>`.
+- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.