@d4gger/design-system 2.7.0 → 3.0.0

package/dist/docs/index.md

@@ -1,149 +0,0 @@
-# D4gger Design System API
-
-Offline, package-shipped copies of the canonical component specifications and consumer guides.
-The repository documents remain the source of truth.
-
-## Guides
-
-- [Consumer guide](./consumer-guide.md)
-- [Sidebar guide](./sidebar-guide.md)
-- [Theme guide](./theme-guide.md)
-
-## Component specifications
-
-- [HIERARCHY](./HIERARCHY.md)
-- [accessible-icon](./accessible-icon.md)
-- [accordion](./accordion.md)
-- [alert-dialog](./alert-dialog.md)
-- [alert](./alert.md)
-- [article-nodes](./article-nodes.md)
-- [aspect-ratio](./aspect-ratio.md)
-- [avatar](./avatar.md)
-- [badge](./badge.md)
-- [blockquote](./blockquote.md)
-- [box](./box.md)
-- [breadcrumb](./breadcrumb.md)
-- [button-group](./button-group.md)
-- [button](./button.md)
-- [calendar](./calendar.md)
-- [callout](./callout.md)
-- [card](./card.md)
-- [carousel](./carousel.md)
-- [chart](./chart.md)
-- [checkbox-cards](./checkbox-cards.md)
-- [checkbox-group](./checkbox-group.md)
-- [checkbox](./checkbox.md)
-- [code-input](./code-input.md)
-- [code](./code.md)
-- [collapsible](./collapsible.md)
-- [color-picker](./color-picker.md)
-- [color-swatch](./color-swatch.md)
-- [combobox](./combobox.md)
-- [command](./command.md)
-- [comment-thread](./comment-thread.md)
-- [component-roster](./component-roster.md)
-- [component-spec-template](./component-spec-template.md)
-- [config-drawer](./config-drawer.md)
-- [container](./container.md)
-- [context-menu](./context-menu.md)
-- [copy-button](./copy-button.md)
-- [copy-field](./copy-field.md)
-- [data-list](./data-list.md)
-- [data-table](./data-table.md)
-- [date-picker](./date-picker.md)
-- [dialog](./dialog.md)
-- [direction-provider](./direction-provider.md)
-- [drawer](./drawer.md)
-- [dropdown-menu](./dropdown-menu.md)
-- [editable](./editable.md)
-- [em](./em.md)
-- [empty-state](./empty-state.md)
-- [field](./field.md)
-- [file-upload](./file-upload.md)
-- [filter-bar](./filter-bar.md)
-- [flex](./flex.md)
-- [floating-panel](./floating-panel.md)
-- [font-provider](./font-provider.md)
-- [form](./form.md)
-- [grid](./grid.md)
-- [heading](./heading.md)
-- [hover-card](./hover-card.md)
-- [icon-button](./icon-button.md)
-- [icon](./icon.md)
-- [input-group](./input-group.md)
-- [input-otp](./input-otp.md)
-- [input](./input.md)
-- [inset](./inset.md)
-- [item](./item.md)
-- [kbd](./kbd.md)
-- [label](./label.md)
-- [layout-props](./layout-props.md)
-- [link](./link.md)
-- [marquee](./marquee.md)
-- [menu](./menu.md)
-- [menubar](./menubar.md)
-- [metric](./metric.md)
-- [native-select](./native-select.md)
-- [navigation-menu](./navigation-menu.md)
-- [notification-center](./notification-center.md)
-- [number-input](./number-input.md)
-- [page-content](./page-content.md)
-- [page-header](./page-header.md)
-- [pagination](./pagination.md)
-- [password-input](./password-input.md)
-- [pills](./pills.md)
-- [popover](./popover.md)
-- [progress](./progress.md)
-- [prose](./prose.md)
-- [qr-code](./qr-code.md)
-- [quote](./quote.md)
-- [radio-cards](./radio-cards.md)
-- [radio-group](./radio-group.md)
-- [rating](./rating.md)
-- [resizable](./resizable.md)
-- [result](./result.md)
-- [rich-text-editor](./rich-text-editor.md)
-- [scroll-area](./scroll-area.md)
-- [search-bar](./search-bar.md)
-- [section](./section.md)
-- [segmented-control](./segmented-control.md)
-- [segmented-meter](./segmented-meter.md)
-- [select](./select.md)
-- [separator](./separator.md)
-- [shared](./shared.md)
-- [sheet](./sheet.md)
-- [sidebar](./sidebar.md)
-- [skeleton](./skeleton.md)
-- [slider](./slider.md)
-- [slot](./slot.md)
-- [sonner](./sonner.md)
-- [sortable-list](./sortable-list.md)
-- [spinner](./spinner.md)
-- [stack](./stack.md)
-- [stat-card](./stat-card.md)
-- [status](./status.md)
-- [stepper](./stepper.md)
-- [strong](./strong.md)
-- [switch](./switch.md)
-- [tab-nav](./tab-nav.md)
-- [table-of-contents](./table-of-contents.md)
-- [table](./table.md)
-- [tabs](./tabs.md)
-- [tags-input](./tags-input.md)
-- [text-area](./text-area.md)
-- [text-field](./text-field.md)
-- [text](./text.md)
-- [theme-panel](./theme-panel.md)
-- [theme-provider](./theme-provider.md)
-- [theme](./theme.md)
-- [time-picker](./time-picker.md)
-- [timeline](./timeline.md)
-- [toast](./toast.md)
-- [toggle-group](./toggle-group.md)
-- [toggle-tip](./toggle-tip.md)
-- [toggle](./toggle.md)
-- [toolbar](./toolbar.md)
-- [tooltip](./tooltip.md)
-- [tree-view](./tree-view.md)
-- [typography](./typography.md)
-- [visually-hidden](./visually-hidden.md)

package/dist/docs/segmented-control.md

@@ -1,211 +0,0 @@
----
-title: SegmentedControl
-status: canonical
-category: Components
-archetype: composite
-package_path: packages/d4gger-design-system/src/components/segmentedControl/SegmentedControl.tsx
-css_path: packages/d4gger-design-system/src/styles/components/segmented-control.css
-props_path: packages/d4gger-design-system/src/components/segmentedControl/segmentedControl.props.ts
-test_path: packages/d4gger-design-system/src/test/components/SegmentedControl.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/forms.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
-depends_on:
-  - ToggleGroup
----
-
-# SegmentedControl
-
-> 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 single-select sliding-indicator control that renders a row of mutually exclusive options inside a raised or outlined container, backed by `ToggleGroup` from Radix. Used for switching between views, filters, or modes in forms and toolbars.
-
-## Anatomy & slots
-
-**Parent:** `SegmentedControl` (alias of `SegmentedControl.Root`).
-
-**Slots:**
-
-| Slot | Element | Renders | Notes |
-|---|---|---|---|
-| `SegmentedControl.Root` | `ToggleGroupPrimitive.Root` | Radix ToggleGroup root + class | Single-select container. Writes `data-size`, `data-variant`, `data-disabled`. |
-| `SegmentedControl.Item` | `ToggleGroupPrimitive.Item` | Radix ToggleGroup item + class | Individual option. Writes `data-state` (`on`/`off`), `data-disabled`. |
-
-## Props contract
-
-| Prop | Type | Default | Required | Description | Responsive |
-|---|---|---|---|---|---|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height and item padding; writes `data-size` and `dsx-segmented-control--{size}` class. | no |
-| `variant` | `'default' \| 'outline'` | `'default'` | no | Container surface treatment; writes `data-variant` and `dsx-segmented-control--{variant}` class. | no |
-| `disabled` | `boolean` | `false` | no | Disables the entire control; writes `data-disabled`. | no |
-| `value` | `string` | `undefined` | no | Controlled selected value. | no |
-| `defaultValue` | `string` | `undefined` | no | Uncontrolled initial selected value. | no |
-| `onValueChange` | `(value: string) => void` | `undefined` | no | Callback when the selected value changes. | no |
-| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-segmented-control`. | no |
-| `children` | `React.ReactNode` | `undefined` | no | `SegmentedControl.Item` children. | no |
-
-**SegmentedControl.Item props:**
-
-| Prop | Type | Default | Required | Description | Responsive |
-|---|---|---|---|---|---|
-| `value` | `string` | — | yes | Unique value for this item. | no |
-| `disabled` | `boolean` | `undefined` | no | Disables this item. | no |
-| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-segmented-control__item`. | no |
-| `children` | `React.ReactNode` | `undefined` | no | Item label content. | no |
-
-Rules:
-
-- `size`, `variant`, and `disabled` are wired through `extractProps` and the prop def bag on the Root.
-- `value`, `defaultValue`, and `onValueChange` are passed through to the Radix ToggleGroup root directly.
-- The Root forces `type="single"` and filters empty string values from `onValueChange` to prevent deselection.
-
-## CSS class contract
-
-**Root class:** `dsx-segmented-control`
-
-**Modifier classes** (driven by `data-*` attributes and class names written by the component):
-
-| Attribute / Class | Allowed values | CSS selector | CSS file |
-|---|---|---|---|
-| `data-size` | `sm`, `md`, `lg` | `.dsx-segmented-control--sm`, `.dsx-segmented-control--md`, `.dsx-segmented-control--lg` | `segmented-control.css` |
-| `data-variant` | `default`, `outline` | `.dsx-segmented-control--default`, `.dsx-segmented-control--outline` | `segmented-control.css` |
-| `data-disabled` | (present/absent) | `.dsx-segmented-control[data-disabled]` | `segmented-control.css` |
-
-**Slot classes:**
-
-| Slot | Class | CSS file |
-|---|---|---|
-| `SegmentedControl.Root` | `dsx-segmented-control` | `segmented-control.css` |
-| `SegmentedControl.Item` | `dsx-segmented-control__item` | `segmented-control.css` |
-
-**Responsive behavior:**
-
-- The component does not write `@media` rules. Size and variant are single-value only.
-
-**Reduced motion:**
-
-- Item transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)` for background-color, color, and box-shadow. No explicit `prefers-reduced-motion` gate is present in the CSS; the token values should be set to `0` by the global reduced-motion override.
-
-## Token mapping
-
-Every CSS value the component paints is a `var(--dsx-*)` token.
-
-| Property | Token | Role |
-|---|---|---|
-| Container background | `var(--dsx-color-surface-raised)` | Default container surface |
-| Container border | `var(--dsx-border-width-sm)` solid `var(--dsx-color-outline)` | Container edge |
-| Container radius | `var(--dsx-grouped-radius, var(--dsx-rounded-md))` | Container roundness |
-| Container shadow | `var(--dsx-effect-shadow-1)` | Container elevation |
-| Item text color | `var(--dsx-color-on-surface-variant)` | Unselected item label |
-| Item selected background | `linear-gradient(var(--dsx-effect-pressed-layer), var(--dsx-effect-pressed-layer)), var(--dsx-control-active-background)` | Selected item surface |
-| Item selected text | `var(--dsx-control-active-foreground)` | Selected item label |
-| Item selected shadow | `var(--dsx-shadow-active-inset-outline)` | Selected item inset outline |
-| Item hover | `var(--dsx-effect-hover-ghost)` | Hover background |
-| Focus ring | `var(--dsx-shadow-focus-ring)` | Focus indicator |
-| Disabled opacity | `var(--dsx-opacity-disabled)` | Disabled fade |
-| Item padding (sm) | `var(--dsx-space-sm)` | Small item horizontal padding |
-| Item padding (md) | `var(--dsx-space-md)` | Default item horizontal padding |
-| Item padding (lg) | `var(--dsx-space-lg)` | Large item horizontal padding |
-| Height (sm) | `var(--dsx-density-control-height-sm, var(--dsx-size-lg))` | Small control height |
-| Height (md) | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Default control height |
-| Height (lg) | `var(--dsx-density-control-height-lg, var(--dsx-size-2xl))` | Large control height |
-| Typography | `var(--dsx-typography-label-large-*)`, `var(--dsx-typography-label-small-*)` | Item label type ramp |
-| Transition duration | `var(--dsx-motion-duration-fast, 150ms)` | Item transition speed |
-| Transition easing | `var(--dsx-motion-easing-standard, ease)` | Item transition curve |
-
-## Motion contract
-
-| Region | Token | Default | Reduced |
-|---|---|---|---|
-| Item background/color/shadow transition | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | `150ms` ease | Global `prefers-reduced-motion` override via token layer |
-
-## Accessibility
-
-**Roles:**
-
-- `group` (Radix ToggleGroup root). Each item is a `radio` role within the group.
-
-**Keyboard:**
-
-| Key | Action |
-|---|---|
-| `Tab` | Moves focus to / from the control. |
-| `Arrow Left`, `Arrow Right` | Moves focus between items. |
-| `Space`, `Enter` | Selects the focused item. |
-
-**Focus:**
-
-- Visible focus ring via `var(--dsx-shadow-focus-ring)` on `:focus-visible`. The ring uses `z-index: var(--dsx-z-index-elevated-strong)` to clear adjacent items.
-
-**Reduced motion:**
-
-- Item transitions collapse when the global reduced-motion token override sets durations to `0`.
-
-**Color and meaning:**
-
-- Selected state is communicated by background fill, text color, and inset shadow — not by color alone.
-
-**Naming:**
-
-- The Root requires an `aria-label` or `aria-labelledby` to name the group.
-
-## Playground demo spec
-
-**Default story:**
-
-- Renders `SegmentedControl` with three items and `defaultValue="day"`. Asserts the root class is `dsx-segmented-control`, `data-size="md"`, and `data-variant="default"`.
-
-**Size story:**
-
-- Renders with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute and `dsx-segmented-control--{size}` class.
-
-**Variant story:**
-
-- Renders with `variant="default"` and `variant="outline"`. Asserts the matching `data-variant` attribute and `dsx-segmented-control--{variant}` class.
-
-**State story:**
-
-- Renders with `disabled={true}`. Asserts `data-disabled` is present and items are not interactive.
-
-**Composition story:**
-
-- Renders with each `SegmentedControl.Item` populated. Asserts each item renders with `dsx-segmented-control__item` class and the selected item has `data-state="on"`.
-
-**Token story:**
-
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. SegmentedControl does not track `data-accent-color`; the story documents that the control surface is visually unchanged across accents.
-
-**A11y story:**
-
-- Uses `vitest-axe` against the rendered default control. Asserts there are no axe violations.
-
-**Props exposed in the playground controls:**
-
-| Prop | Control | Default |
-|---|---|---|
-| `size` | select | `md` |
-| `variant` | select | `default` |
-| `disabled` | boolean | `false` |
-
-## Wiring notes
-
-**Composes from:**
-
-- `@radix-ui/react-toggle-group`: provides the single-select toggle group semantics and keyboard navigation.
-
-**Used by:**
-
-- `ThemePanel`: theme configuration panel uses SegmentedControl for density and mode switching.
-- `ConfigDrawer`: app-config drawer uses SegmentedControl for setting groups.
-
-**State boundaries:**
-
-- Owned by SegmentedControl: the selected value, the `data-size`, `data-variant`, `data-disabled` attributes, and the CSS classes.
-- Owned by the consumer: the item values, the item labels, the controlled/uncontrolled value, and the `onValueChange` callback.
-
-**Boundary rules:**
-
-- App-owned data: the item values and labels, the selection state semantics.
-- DS-owned visuals: token bindings, slot classes, motion presets, and the container/item layout.

package/dist/docs/sheet.md

@@ -1,326 +0,0 @@
----
-title: Sheet
-status: canonical
-category: Components
-archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/sheet/Sheet.tsx
-css_path: packages/d4gger-design-system/src/styles/components/sheet.css
-props_path: packages/d4gger-design-system/src/components/sheet/sheet.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Sheet.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/overlay.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
-depends_on:
-  - Dialog
----
-
-# Sheet
-
-> Source of truth: the package source at `package_path`. The spec mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
-
-## Purpose
-
-An edge-attached complementary panel that slides in from the top, right, bottom, or left edge of the viewport. Use `Sheet` for side panels, filter rails, and complementary content that should not block the page. For a mobile-first modal that slides in from a drag handle, use `Drawer` instead.
-
-## Anatomy & slots
-
-**Parent:** `Sheet` (alias of `Sheet.Root`).
-
-**Slots:**
-
-| Slot | Element | Renders | Notes |
-|---|---|---|---|
-| `Sheet.Root` | Radix `Dialog.Root` | DS wrapper | Owns open state, presence context, and `PortalThemeBoundary`. |
-| `Sheet.Trigger` | `BaseDialogTrigger` | DS primitive | Wires the element that opens the sheet. |
-| `Sheet.Portal` | Radix `Dialog.Portal` | DS primitive | Wraps the overlay and content in a Radix portal. |
-| `Sheet.Overlay` | Radix `Dialog.Overlay` | DS primitive + class `dsx-sheet__overlay` | Click-to-dismiss surface behind the sheet. |
-| `Sheet.Content` | Radix `Dialog.Content` wrapped in `motion.div` | DS wrapper + class `dsx-sheet__content` | Hosts header, title, description, body, footer, and the close button. `data-side` and `data-size` drive positioning. |
-| `Sheet.Title` | Radix `Dialog.Title` | DS primitive + class `dsx-sheet__title` | Required for the sheet's accessible name. |
-| `Sheet.Description` | Radix `Dialog.Description` | DS primitive + class `dsx-sheet__description` | Optional body copy. |
-| `Sheet.Header` | `<div>` composed through `Flex` | DS composite + class `dsx-sheet__header` | Optional header layout, right-aligned, with bottom border. |
-| `Sheet.Footer` | `<div>` composed through `Flex` | DS composite + class `dsx-sheet__footer` | Optional footer with right-aligned, top border. |
-| `Sheet.Close` | `BaseDialogClose` | DS primitive | Programmatic close. The content renders a default close button (`dsx-sheet__close`) with `aria-label="Close sheet"` when `showClose` is true. |
-
-## Props contract
-
-**Root props (`Sheet`):**
-
-| Prop | Type | Default | Required | Description | Responsive |
-|---|---|---|---|---|---|
-| `defaultOpen` | `boolean` | `undefined` | no | Initial open state when uncontrolled. | no |
-| `open` | `boolean` | `undefined` | no | Controlled open state. | no |
-| `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Fires on every open transition. | no |
-| `children` | `React.ReactNode` | `undefined` | no | Slot content. | no |
-
-**Content props (`Sheet.Content`):**
-
-| Prop | Type | Default | Required | Description | Responsive |
-|---|---|---|---|---|---|
-| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | no | Edge from which the sheet slides. Writes `data-side`. | no |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Size band. Writes `data-size`. | no |
-| `showClose` | `boolean` | `true` | no | Whether the default close button is rendered. | no |
-| `width` | `WidthToken` (from `widthPropDef`) | `undefined` | no | Width of the sheet for `left` and `right` sides. Forwards to `--dsx-sheet-width` via the standard `widthPropDef` resolution. | yes |
-| `height` | `HeightToken` (from `heightPropDef`) | `undefined` | no | Height of the sheet for `top` and `bottom` sides. Forwards to `--dsx-sheet-height` via the standard `heightPropDef` resolution. | yes |
-| `onOpenAutoFocus` | `(event: Event) => void` | `undefined` | no | Radix `onOpenAutoFocus` event. | no |
-| `onCloseAutoFocus` | `(event: Event) => void` | `undefined` | no | Radix `onCloseAutoFocus` event. | no |
-| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | `undefined` | no | Radix escape handler. | no |
-| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | `undefined` | no | Radix pointer handler. | no |
-| `children` | `React.ReactNode` | `undefined` | no | Header, body, footer, action trigger. | no |
-
-**Header and Footer props (`Sheet.Header` and `Sheet.Footer`):**
-
-| Prop | Type | Default | Required | Description | Responsive |
-|---|---|---|---|---|---|
-| `asChild` | `boolean` | `false` | no | Renders through `Slot`; consumer supplies the element. | no |
-| `children` | `React.ReactNode` | `undefined` | no | Header or footer content. | no |
-
-**Title, Description, Close props:**
-
-Each slot accepts the standard Radix `Dialog` props. None expose DS-only props.
-
-Rules:
-
-- `side`, `showClose`, `width`, `height`, and `size` are wired through `extractProps` and the `sheetContentPropDefs` bag. Mismatches between this table and `sheet.props.ts` fail `qa:contracts`.
-- `width` and `height` come from the shared `widthPropDef` and `heightPropDef` and are responsive by definition.
-
-## CSS class contract
-
-**Root class:** `dsx-sheet` (implicit; the visible root is the `Content` wrapper).
-
-**Modifier classes** (driven by `data-*` attributes written by the component):
-
-| Attribute | Allowed values | Class | CSS file |
-|---|---|---|---|
-| `data-side` | `top`, `right`, `bottom`, `left` | `.dsx-sheet__content[data-side='top']`, `[data-side='right']`, `[data-side='bottom']`, `[data-side='left']` | `sheet.css` |
-| `data-size` | `sm`, `md`, `lg` | `.dsx-sheet__content[data-size='sm']`, `[data-size='md']`, `[data-size='lg']` | `sheet.css` |
-| `data-slot` | `sheet-header`, `sheet-footer`, `sheet-overlay`, `sheet-content`, `sheet-close`, `sheet-title`, `sheet-description` | (CSS does not style `data-slot`; the attributes serve as stable hooks for app code and tests) | n/a |
-
-**Slot classes:**
-
-| Slot | Class | CSS file |
-|---|---|---|
-| `Sheet.Content` | `dsx-sheet__content` | `sheet.css` |
-| `Sheet.Overlay` | `dsx-sheet__overlay` | `sheet.css` |
-| `Sheet.Header` | `dsx-sheet__header` | `sheet.css` |
-| `Sheet.Footer` | `dsx-sheet__footer` | `sheet.css` |
-| `Sheet.Title` | `dsx-sheet__title` | `sheet.css` |
-| `Sheet.Description` | `dsx-sheet__description` | `sheet.css` |
-| `Sheet.Close` | `dsx-sheet__close` | `sheet.css` |
-
-`Sheet.Trigger` and `Sheet.Portal` have no DS class; the Radix primitives are used directly.
-
-**Responsive behavior:**
-
-- The component does not write `@media` rules. `width` and `height` are `responsive: true` through the shared `widthPropDef` and `heightPropDef`; the `extractProps` runtime emits breakpoint-prefixed CSS custom properties.
-- `side` and `size` are single values, not responsive.
-
-**Reduced motion:**
-
-- The `motion.div` in `SheetContent` collapses to opacity-only transitions on `MOTION_TRANSITIONS.reduced` when `useReducedMotion` from `framer-motion` matches. The default preset is `MOTION_TRANSITIONS.sheet`, with a side-specific translation (`x` for `left` / `right`, `y` for `top` / `bottom`).
-
-## Token mapping
-
-| Property | Token | Role |
-|---|---|---|
-| Overlay z-index | `var(--dsx-z-index-overlay)` | Stacking. |
-| Content z-index | `var(--dsx-z-index-modal)` | Stacking. |
-| Content padding | `var(--dsx-space-lg)` | Internal gutter. |
-| Content width (default) | `min(var(--dsx-sheet-width), 100vw)` | Default right or left width. |
-| Structural widths | `var(--dsx-sheet-width-sm)`, `var(--dsx-sheet-width-lg)` | Canonical small and large side-panel widths. |
-| Content min height (top or bottom) | `min(var(--dsx-size-popover-max-width), var(--dsx-sheet-min-height))` | Default top or bottom height. |
-| Edge border (right) | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Right edge divider. |
-| Edge border (left) | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Left edge divider. |
-| Edge border (top) | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Bottom edge divider. |
-| Edge border (bottom) | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Top edge divider. |
-| Header padding | `var(--dsx-space-sm) 0` and `var(--dsx-space-md)` bottom | Header rhythm. |
-| Header right padding | `calc(var(--dsx-space-lg) + 2rem)` | Space for the close button. |
-| Header bottom border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Header divider. |
-| Footer padding | `var(--dsx-space-md) 0 var(--dsx-space-sm)` | Footer rhythm. |
-| Footer top border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Footer divider. |
-| Title typography | `var(--dsx-typography-headline-medium-*)` | Title. |
-| Title color | `var(--dsx-color-on-surface)` | Title text. |
-| Description typography | `var(--dsx-typography-body-medium-*)` | Description. |
-| Description color | `var(--dsx-color-on-surface-variant)` | Body copy. |
-| Close button position | `var(--dsx-space-lg)` from the corner | Distance from the corner. |
-| Close button padding | `var(--dsx-space-xs)` | Tap padding. |
-| Close button radius | `var(--dsx-rounded-sm)` | Round corner. |
-| Close button z-index | `var(--dsx-z-index-elevated)` | Stacking. |
-| Motion duration | `var(--dsx-motion-duration-*)` | Mount and exit. |
-| Motion easing | `var(--dsx-motion-easing-*)` | Mount and exit. |
-
-Rules:
-
-- The content background and surface tokens come from `baseDialog.css` (the shared overlay surface).
-- No raw color, spacing, radius, or motion values in `sheet.css`.
-
-## Motion contract
-
-| Region | Token | Default | Reduced |
-|---|---|---|---|
-| Overlay mount and exit | `MOTION_TRANSITIONS.sheet` | opacity 0 to 1 | opacity only on `MOTION_TRANSITIONS.reduced` |
-| Content mount and exit | `MOTION_TRANSITIONS.sheet` with side-specific translation | side-specific x or y translation, opacity 0 to 1 | opacity only on `MOTION_TRANSITIONS.reduced` |
-
-Side translation matrix:
-
-| `side` | Initial | Animate | Exit |
-|---|---|---|---|
-| `left` | `x: '-100%'`, `opacity: 0` | `x: 0`, `opacity: 1` | `x: '-100%'`, `opacity: 0` |
-| `right` (default) | `x: '100%'`, `opacity: 0` | `x: 0`, `opacity: 1` | `x: '100%'`, `opacity: 0` |
-| `top` | `y: '-100%'`, `opacity: 0` | `y: 0`, `opacity: 1` | `y: '-100%'`, `opacity: 0` |
-| `bottom` | `y: '100%'`, `opacity: 0` | `y: 0`, `opacity: 1` | `y: '100%'`, `opacity: 0` |
-
-## Accessibility
-
-**Roles:**
-
-- `Sheet.Content` renders a Radix `Dialog.Content` that exposes `role="dialog"` and `aria-modal="true"`. The `aria-labelledby` reference is wired from `Sheet.Title` and `aria-describedby` from `Sheet.Description`.
-
-**Keyboard:**
-
-| Key | Action |
-|---|---|
-| `Tab` | Moves focus to the next focusable element inside the sheet. Focus is trapped while the sheet is open. |
-| `Shift` + `Tab` | Moves focus to the previous focusable element. |
-| `Enter`, `Space` | Activates the focused control. |
-| `Escape` | Closes the sheet (Radix default; configurable via `onEscapeKeyDown`). |
-
-**Focus:**
-
-- Visible focus ring via `var(--dsx-shadow-focus-ring)` on interactive elements.
-- Focus is trapped inside the sheet while open. Focus returns to the trigger on close.
-- `onOpenAutoFocus` and `onCloseAutoFocus` are forwarded for apps that need to override focus management.
-
-**Reduced motion:**
-
-- Mount and exit motion collapses to `MOTION_TRANSITIONS.reduced` when `prefers-reduced-motion: reduce` matches.
-
-**Color and meaning:**
-
-- The sheet does not communicate state by color alone. Destructive copy is the consumer's responsibility; pair the destructive action with a clear label.
-
-**Naming:**
-
-- `Sheet.Title` is required for the accessible name.
-- `Sheet.Description` provides the longer description; the sheet is still valid without it.
-- The default close button has `aria-label="Close sheet"`. Custom close buttons must set their own `aria-label`.
-
-## Playground demo spec
-
-**Default story:**
-
-- Renders `Sheet` with a `Trigger` and `Content` containing `Header` and `Title`. Asserts the content has `dsx-sheet__content`, `data-side="right"`, and `data-size="md"`.
-
-**Side story** (one per side value):
-
-- Renders `Sheet.Content` with `side="top"`, `side="right"`, `side="bottom"`, and `side="left"`. Asserts `data-side`.
-
-**Size story** (one per size value):
-
-- Renders `Sheet.Content` with `size="sm"`, `size="md"`, and `size="lg"`. Asserts `data-size`.
-
-**Header and Footer story:**
-
-- Renders `Sheet.Content` with `Header`, `Body`, and `Footer` populated. Asserts each slot has the matching class.
-
-**Close story:**
-
-- Opens the sheet with `userEvent.click`. Asserts the body appears, then dismisses with the `Escape` key. Asserts focus returns to the trigger.
-
-**Composition story:**
-
-- Renders every slot: `Root`, `Trigger`, `Content`, `Header`, `Footer`, `Title`, `Description`. Asserts each slot renders the right class.
-
-**A11y story:**
-
-- Uses `vitest-axe` against an open sheet. Asserts there are no axe violations.
-
-**Props exposed in the playground controls:**
-
-| Prop | Control | Default |
-|---|---|---|
-| `side` | select | `right` |
-| `size` | select | `md` |
-| `showClose` | boolean | `true` |
-| `width` | text | (empty) |
-| `height` | text | (empty) |
-
-## Wiring notes
-
-**Composes from:**
-
-- `@radix-ui/react-dialog`: provides the dialog state, focus trap, portal, overlay, and the `Title` / `Description` / `Close` primitives. The sheet is a `Dialog` derivative.
-- `@radix-ui/react-slot`: enables `asChild` on `Sheet.Header` and `Sheet.Footer`.
-- `framer-motion`: provides the `motion.div` for mount and exit. The reduced motion preset is read from `useReducedMotion`.
-- `Flex` (from `../flex/Flex`): `Sheet.Header` composes `Flex` with `direction="row"`, `align="start"`, `justify="between"`, `gap="md"`. `Sheet.Footer` composes `Flex` with `justify="end"`, `gap="md"`.
-- `Icon` (from `../icon/Icon`): the default close button renders `<Icon name="x" size="md" />`.
-- `BaseDialog` (`_internal/BaseDialog`): `Sheet.Trigger` and `Sheet.Close` use `BaseDialogTrigger` and `BaseDialogClose` for consistent button semantics.
-
-**Used by:**
-
-- Filter rails, settings panels, complementary content.
-- Side panels for product detail views, navigation drawers (the complementary case, not the modal case).
-
-**State boundaries:**
-
-- Owned by `Sheet`: open state when uncontrolled, presence context, portal theme mirroring, side-specific motion, action-trigger loading state.
-- Owned by the consumer: title copy, description copy, the body content, the action handlers, the close behavior.
-
-**Boundary rules:**
-
-- App-owned data: the panel content, the side choice for the product area, the action handlers.
-- DS-owned visuals: overlay, content frame, header / footer rhythm, close button, side-specific motion.
-
-## Penpot build recipe
-
-### Root board
-
-- **Name**: `Components / Sheet`.
-- **Dimensions**: `420 × 600` (default `side="right"`, `size="md"`).
-- **Layout**: `Flex`, vertical.
-- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = '100%'`.
-
-### Layer tree
-
-```
-<Root Board>
-  ├── <Overlay rect>
-  └── <Content frame (anchored to right edge)>
-        ├── <Close icon button>
-        ├── <Header>
-        │     └── <Title text>
-        ├── <Body>
-        │     └── <Description text>
-        └── <Footer>
-              └── <Action button>
-```
-
-### Token bindings (Penpot properties)
-
-| Shape | Property | Token | Token type | Penpot property name |
-|---|---|---|---|---|
-| `<Content frame>` | fill | `var(--dsx-color-surface-overlay)` | Color | `fills` |
-| `<Content frame>` (right) | stroke (left) | `var(--dsx-color-outline)` | Color | `strokes` |
-| `<Content frame>` | spacing | `var(--dsx-space-lg)` | Spacing | `padding` |
-| `<Title text>` | typography | `var(--dsx-typography-headline-medium-*)` | Typography | `typography` |
-| `<Description text>` | typography | `var(--dsx-typography-body-medium-*)` | Typography | `typography` |
-| `<Close icon button>` | size | `var(--dsx-size-lg)` | Size | `width` / `height` |
-
-### State transformations
-
-| State | Content fill | Content shadow |
-|---|---|---|
-| `default` | `var(--dsx-color-surface-overlay)` | `var(--dsx-shadow-elevation-3)` |
-| `open` | `var(--dsx-color-surface-overlay)` | `var(--dsx-shadow-elevation-4)` |
-
-### Variant model
-
-- `side`: `top`, `right`, `bottom`, `left`. Default `right`.
-- `size`: `sm`, `md`, `lg`. Default `md`.
-- `showClose`: `true`, `false`. Default `true`.
-- Total members: `4 * 3 * 2 = 24`.
-
-### Validation checklist
-
-- [ ] Token bindings resolve at the values `DESIGN.md` describes.
-- [ ] Component is promoted to Main Component under `Components`.
-- [ ] `penpotUtils.shapeStructure(board, 3)` matches the expected hierarchy.