@d4gger/design-system 2.7.0

package/dist/docs/data-table.md

@@ -0,0 +1,275 @@
+---
+title: DataTable
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/dataTable/DataTable.tsx
+css_path: packages/d4gger-design-system/src/components/dataTable/dataTable.css
+props_path: packages/d4gger-design-system/src/components/dataTable/dataTable.props.ts
+test_path: packages/d4gger-design-system/src/test/components/DataTable.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/data.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Table
+  - Pagination
+  - Toolbar
+  - SearchBar
+  - EmptyState
+  - Pills
+---
+
+# DataTable
+
+> 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
+
+Advanced table shell with toolbar, search, sort, filter chips, density toggle, pagination, and row actions. The design system owns the visual shell and controlled sort/filter/density UI. The app owns data fetching and the `PaginatedResponse` contract.
+
+## 2.6 contract
+
+This section supersedes narrower 2.5 notes below. Columns additionally accept fixed or `{ min, max }` fluid `width`, `align`, `numeric`, `sortable`, `truncate`, and canonical `hideBelow` breakpoints. At most one column may truncate. `sortBy`, `sortOrder`, and `onSortChange` provide controlled sorting while omission retains stable client sorting. `stickyHeader`, controlled/uncontrolled selected row IDs, `onSelectedRowIdsChange`, and `selectionMode="multiple" | "none"` are supported; multiple selection remains the compatibility default.
+
+`listState="loading" | "empty" | "no-results" | "error"` renders the canonical Result path, or `result` supplies custom content. Fixed columns retain width while the lone truncating fluid column absorbs overflow. Apps continue to own fetching and server query execution; the component emits state changes only.
+
+## Anatomy & slots
+
+**Parent:** `DataTable` (alias of `DataTable.Root` when the component is a compound).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `DataTable.Root` | `<div>` | Host element with class | Root container. Writes `data-size` and `data-empty` attributes. |
+| `DataTable.Toolbar` | `<div>` | `DataTableToolbar` with class | Toolbar container for search, column visibility, export, and row count controls. |
+| `DataTable.Toolbar.Search` | `<Input>` | Search input | Text search input with `type="search"`. Filters rows client-side. |
+| `DataTable.Toolbar.ColumnVisibility` | `<DropdownMenu>` | Column toggle dropdown | Dropdown with checkbox items for toggling column visibility. |
+| `DataTable.Toolbar.Export` | `<DropdownMenu>` | Export dropdown | Dropdown with CSV and JSON export options. |
+| `DataTable.Toolbar.RowCount` | `<div>` | Row count display | Displays total, filtered, and selected row counts. |
+| `DataTable.Pagination` | `<div>` | `DataTablePagination` with class | Pagination controls with page size selector and page navigation. |
+| `DataTable.FacetedFilter` | `<div>` | `DataTableFacetedFilter` with class | Faceted filter dropdown with checkbox list and search. |
+
+The root `DataTable` component is a flat export, not a compound. Subcomponents are attached as static properties: `DataTable.Toolbar`, `DataTable.Pagination`, `DataTable.FacetedFilter`.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `columns` | `Array<DataTableColumn<Row>>` | `undefined` | yes | Column definitions with `id`, `header`, `accessorKey`, and optional `cell` renderer. | no |
+| `data` | `Row[]` | `undefined` | yes | Row data array. | no |
+| `emptyState` | `ReactNode` | `'No results.'` | no | Content rendered when no rows match filters. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Table density. Maps to `data-size` attribute. | no |
+| `getRowId` | `(row: Row, rowIndex: number) => React.Key` | `undefined` | no | Custom row ID extractor. Defaults to `rowIndex`. | no |
+| `visibleColumnIds` | `Set<string>` | `undefined` | no | Controlled visible column IDs. Defaults to all columns. | no |
+| `onVisibleColumnIdsChange` | `(visibleColumnIds: Set<string>) => void` | `undefined` | no | Callback when visible columns change. | no |
+| `pagination` | `DataTablePaginationState` | `undefined` | no | Controlled pagination state `{ page, pageSize }`. | no |
+| `onPaginationChange` | `(pagination: DataTablePaginationState) => void` | `undefined` | no | Callback when pagination changes. | no |
+| `facetedFilters` | `Array<DataTableFacetedFilterState>` | `undefined` | no | Controlled faceted filter state array. | no |
+| `onFacetedFiltersChange` | `(facetedFilters: Array<DataTableFacetedFilterState>) => void` | `undefined` | no | Callback when faceted filters change. | no |
+| `toolbar` | `ReactNode` | `undefined` | no | Custom toolbar content. Replaces default search toolbar. | no |
+| `showToolbar` | `boolean` | `true` | no | Whether to show the default toolbar. | no |
+| `showPagination` | `boolean` | `false` | no | Whether to show pagination controls. | no |
+
+Rules:
+
+- Every prop in this table must exist in `<name>.props.ts` or be typed inline in the TSX file. 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 `no` for all props. DataTable does not support responsive props.
+- `columns` and `data` are required. All other props are optional.
+- The `Type` column uses TypeScript syntax. Generic types are parameterized by `Row`.
+
+## CSS class contract
+
+**Root class:** `dsx-data-table`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-data-table[data-size="sm"]`, `.dsx-data-table[data-size="md"]`, `.dsx-data-table[data-size="lg"]` | inline styles |
+| `data-empty` | `true` | `.dsx-data-table[data-empty="true"]` | inline styles |
+
+**Slot classes** (for compounds and composites):
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `DataTable.Toolbar` | `dsx-data-table-toolbar` | inline styles |
+| `DataTable.Pagination` | `dsx-data-table-pagination` | inline styles |
+| `DataTable.FacetedFilter` | `dsx-data-table-faceted-filter` | inline styles |
+| Empty cell | `dsx-data-table__empty` | inline styles |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. Responsive sizing is driven by the layout primitives' responsive classes when composed by the app.
+- The component's CSS is breakpoint-agnostic. DataTable uses inline styles for all visual properties.
+
+**Reduced motion:**
+
+- DataTable does not animate. No motion contract.
+
+## Token mapping
+
+DataTable uses inline styles with token references. Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Gap | `var(--dsx-space-sm)`, `var(--dsx-space-xs)` | Spacing between controls |
+| Padding | `var(--dsx-space-md)`, `var(--dsx-space-sm)` | Internal gutter |
+| Font size | `var(--dsx-font-size-xs)` | Small text |
+| Color | `var(--dsx-color-on-surface)`, `var(--dsx-color-on-surface-variant)` | Text colors |
+| Border | `var(--dsx-color-outline)` | Edge |
+| Radius | `var(--dsx-radius-sm)` | Standard roundness |
+| Background | `var(--dsx-color-surface)`, `var(--dsx-color-surface-raised)` | Surface colors |
+| Accent | `var(--dsx-color-accent-primary)`, `var(--dsx-color-on-accent-primary)` | Active page button |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in the component. All values reference tokens.
+- Tokens come from `DESIGN.md` and the generated `tokens.css`. The token list is closed; new tokens are a `DESIGN.md` change first.
+- Accent color comes through `var(--dsx-color-accent-primary)` and the `data-accent-color` attribute on the `Theme` wrapper. DataTable does not name brand colors directly.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| All regions | `none` | `none` | `none` |
+
+Rules:
+
+- DataTable does not animate. No motion presets are used.
+- All motion respects `prefers-reduced-motion`. The `Reduced` column is `none` for all regions.
+
+## Accessibility
+
+**Roles:**
+
+- `table`. The root `Table` component renders a semantic `<table>` element.
+- `columnheader`. Each `TableHead` renders a `<th>` with `aria-sort` when sortable.
+- `cell`. Each `TableCell` renders a `<td>`.
+- `row`. Each `TableRow` renders a `<tr>`.
+- `searchbox`. The search input renders with `type="search"`.
+- `button`. Sort buttons, pagination buttons, and toolbar buttons render with `type="button"`.
+- `checkbox`. Row selection checkboxes render with `role="checkbox"`.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to / from the next / previous focusable element. |
+| `Enter`, `Space` | Activates sort buttons, pagination buttons, and checkboxes. |
+| Arrow keys | Navigates the faceted filter option list when open. |
+
+**Focus:**
+
+- Visible focus ring via `var(--dsx-ring-focus)`. The ring must remain visible on dark and light surfaces.
+- Sort buttons, pagination buttons, and checkboxes receive focus in tab order.
+
+**Reduced motion:**
+
+- DataTable does not animate. No motion to reduce.
+
+**Color and meaning:**
+
+- Sort direction is communicated by icon (↑, ↓, ↕) and `aria-sort` attribute, not by color alone.
+- Selection state is communicated by checkbox checked state and `data-selected` attribute on the row.
+
+**Naming:**
+
+- Every interactive element has an accessible name. Sort buttons use the column header text. Pagination buttons use `aria-label="Previous page"`, `aria-label="Next page"`, and `aria-label="Page {n}"`.
+- Search input uses `aria-label="Search table rows"`.
+- Select-all checkbox uses `aria-label="Select all visible rows"` or `aria-label="Deselect all visible rows"`.
+- Row checkboxes use `aria-label="Select row {n}"`.
+
+## 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 `columns` and `data` props. No other props passed.
+- Asserts the root class is `dsx-data-table`.
+
+**Variant story** (one per variant):
+
+- Renders the component with `size="sm"`, `size="md"`, and `size="lg"`.
+- Asserts the matching `data-size` attribute is set.
+
+**Composition story** (for composites):
+
+- Renders the component with `showPagination={true}` and a custom `toolbar` prop.
+- Asserts pagination controls and toolbar render.
+
+**State story:**
+
+- Renders the component with empty `data` array.
+- Asserts the `emptyState` content renders and `data-empty="true"` is set.
+
+**Token story:**
+
+- DataTable does not honor `data-accent-color` directly. The pagination active page button uses `var(--dsx-color-accent-primary)`, which responds to the `Theme` wrapper's `accentColor` prop.
+- Renders the component inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`.
+
+**A11y story:**
+
+- Uses `vitest-axe` to assert the rendered component has no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | `select` | `md` |
+| `showPagination` | `boolean` | `false` |
+| `showToolbar` | `boolean` | `true` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Table`: Renders the semantic table structure (`<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`).
+- `Pagination`: Renders pagination controls when `showPagination={true}`. DataTable uses its own `DataTablePagination` subcomponent, not the standalone `Pagination` component.
+- `Toolbar`: Renders toolbar controls. DataTable uses its own `DataTableToolbar` subcomponent, not the standalone `Toolbar` component.
+- `SearchBar`: DataTable does not compose `SearchBar`. It uses a plain `Input` with `type="search"` for client-side filtering.
+- `EmptyState`: DataTable does not compose `EmptyState`. It renders the `emptyState` prop content in a table cell when no rows match.
+- `Pills`: DataTable does not compose `Pills`. Faceted filters use `DataTableFacetedFilter` subcomponents.
+- `Input`: Renders the search input in the default toolbar.
+- `Checkbox`: Renders row selection checkboxes and the select-all checkbox.
+- `Button`: Renders pagination buttons and toolbar buttons.
+- `Badge`: Renders active filter count badges in toolbar and faceted filter.
+- `DropdownMenu`: Renders column visibility, export, and faceted filter dropdowns.
+
+**Used by:**
+
+- `Shell (Cabinet)`: DataTable is a common content surface in cabinet shell layouts.
+
+**State boundaries:**
+
+- Owned by this component: sort state (internal `useState`), search query (internal `useState`), row selection (internal `useState`), pagination state (internal or controlled), faceted filter state (internal or controlled), visible column IDs (internal or controlled).
+- Owned by the consumer: row data, column definitions, custom toolbar content, custom empty state content. The consumer passes these in as props.
+
+**Boundary rules:**
+
+- App-owned data: row data, column definitions, data fetching, sorting logic (if server-side), filtering logic (if server-side), pagination logic (if server-side). The consumer owns the `PaginatedResponse` contract (`offset`, `limit`, `sortBy`, `sortOrder`, `totalCount`).
+- DS-owned visuals: token bindings, slot classes, table structure, pagination controls, toolbar layout, faceted filter UI, sort icons, selection checkboxes.
+
+**Backend pagination contract:**
+
+The app owns data fetching and the `PaginatedResponse` contract. The contract is:
+
+- `PaginationQuery`: `{ offset: number, limit: number, sortOrder: 'asc' | 'desc' }`. Sent by the app to the backend.
+- `PaginationParams`: `{ offset: number, limit: number, sortBy: string, sortOrder: 'asc' | 'desc' }`. Extended query with sort field.
+- `PaginatedResponse`: `{ totalCount: number, offset: number, limit: number, items: Row[] }`. Returned by the backend.
+
+DataTable does not implement this contract. The app maps the contract to DataTable's controlled props:
+
+- `pagination.page` maps to `Math.floor(offset / limit) + 1`.
+- `pagination.pageSize` maps to `limit`.
+- `onPaginationChange` maps to updating `offset` and `limit` in the query.
+- `data` maps to `items` from the response.
+- `totalCount` is not a DataTable prop. The app passes `items.length` as `data.length`.
+
+## 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.
+
+DataTable does not have a Penpot build recipe. The package code is the only authority.

package/dist/docs/date-picker.md

@@ -0,0 +1,300 @@
+---
+title: DatePicker
+status: canonical
+category: Components
+archetype: adapter-backed
+package_path: packages/d4gger-design-system/src/components/datePicker/DatePicker.tsx
+css_path: packages/d4gger-design-system/src/styles/components/datepicker.css
+props_path: packages/d4gger-design-system/src/components/datePicker/datePicker.props.ts
+test_path: packages/d4gger-design-system/src/test/components/DatePicker.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:
+  - Calendar
+  - Popover
+  - Icon
+  - react-day-picker
+  - "@radix-ui/react-slot"
+---
+
+# DatePicker
+
+> 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
+
+The canonical product-facing single-date selection surface. `DatePicker` is `Calendar + Popover` glued together by a tokenized button trigger. The package owns the trigger, the popover positioning, the popover theme inheritance, and the controlled single-date state machine. The adapter (`react-day-picker` via `Calendar`) owns the calendar grid and the date math. Apps own locale formatting, timezone semantics, range and persistence concerns, and any non-standard product copy.
+
+`DatePicker` is single-date only. Range selection, multi-date selection, and month or year pickers are out of scope and would land as separate components.
+
+## Anatomy & slots
+
+**Parent:** `DatePicker`.
+
+No slots: flat export. The component is a single `React.forwardRef<HTMLButtonElement, DatePickerProps>` that composes `Popover`, `Calendar`, and `Icon` internally.
+
+**Internal regions:**
+
+| Region | Element | Class | Notes |
+|---|---|---|---|
+| Trigger | `<button>` (or `Slot` when `asChild`) | `dsx-date-picker__trigger` | Opens or closes the popover. Carries `data-size`, `data-placeholder` (`'true'` when empty), and any `data-variant` modifier class from prop defs. |
+| Value container | `<span>` | `dsx-date-picker__value` | Holds the leading calendar icon and the label. |
+| Leading icon | `Icon` (`name="calendar"`, `size="sm"`) | `dsx-date-picker__leading-icon` | Calendar glyph. |
+| Label | `<span>` | `dsx-date-picker__label` | The formatted value or the placeholder string. |
+| Trailing icon | `Icon` (`name="chevron-down"`, `size="sm"`) | `dsx-date-picker__icon` | Chevron glyph at the right edge of the trigger. |
+| Popover content | `Popover.Content` | `dsx-date-picker__content` | Resets the inner Popover surface so the calendar owns the visual frame. |
+| Theme wrapper | `<div>` | inherits `data-dsx-*` | `<Theme appearance="inherit">` mirrors the active theme into the calendar. |
+| Calendar | `Calendar` (`mode="single"`) | `dsx-date-picker__calendar` | The react-day-picker host. Forced to `mode="single"`. |
+
+**Adapter host:**
+
+`Popover` is the host for the popover lifecycle. The trigger and content are wired into the same `Popover` instance. `Calendar` is rendered inside `Popover.Content`, wrapped in `<Theme appearance="inherit">` so the calendar picks up the active light or dark appearance even when the host is inside a portal. The popover content class `dsx-date-picker__content` resets the inner Popover surface so the calendar owns the visual frame.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the trigger through `Slot` from `@radix-ui/react-slot`. The trigger still receives the `dsx-date-picker__trigger` class and the `data-*` attributes. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Drives `data-size` on the trigger. `sm` and `lg` consume the matching `--dsx-density-control-*` and `--dsx-size-*` tokens. | no |
+| `variant` | `'default' \| 'ghost'` | `'default'` | no | Drives the `dsx-date-picker-variant-*` modifier class. `ghost` makes the trigger background transparent. | no |
+| `placeholder` | `string` | `'Pick a date'` | no | Trigger label when no value is selected. | no |
+| `value` | `Date \| undefined` | `undefined` | no | Controlled selected date. Pair with `onValueChange` to receive updates. | no |
+| `defaultValue` | `Date \| undefined` | `undefined` | no | Uncontrolled initial value. | no |
+| `onValueChange` | `(value: Date \| undefined) => void` | `undefined` | no | Selection callback. Fires when a calendar day is selected. The popover closes immediately after the call. | no |
+| `open` | `boolean` | `undefined` | no | Controlled popover open state. | no |
+| `defaultOpen` | `boolean` | `false` | no | Uncontrolled initial popover open state. | no |
+| `onOpenChange` | `(open: boolean) => void` | `undefined` | no | Popover open state callback. | no |
+| `formatDate` | `(value: Date) => string` | `value.toLocaleDateString(undefined, { dateStyle: 'medium' })` | no | Trigger label formatter. Apps that need a fixed locale, timezone, or product-specific wording supply their own. | no |
+| `calendarProps` | `Omit<CalendarProps, 'mode' \| 'selected' \| 'onSelect'>` | `undefined` | no | Escape hatch for lower-level calendar configuration (locale, `numberOfMonths`, `disabled`, modifiers, custom `classNames`, etc.). `mode`, `selected`, and `onSelect` are owned by `DatePicker` and not forwarded. | no |
+| `popoverContentProps` | `Omit<PopoverContentProps, 'children'>` | `undefined` | no | Escape hatch for popover positioning, side, alignment, and class merging. `children` is owned by `DatePicker`. `align` defaults to `'start'` and `sideOffset` defaults to `8`. | no |
+| `type` | `string` | `'button'` | no | Trigger button `type`. Suppressed when `asChild` is set so the child element owns the attribute. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-date-picker__trigger`. | no |
+
+The component extends `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'defaultValue' | 'onChange' | 'value'>` so `value`, `defaultValue`, and `onChange` are surfaced only as the controlled `Date` API above.
+
+## CSS class contract
+
+**Root class:** none. The public surface is a single `forwardRef` whose host element is the trigger.
+
+**Modifier classes** (driven by `data-*` attributes and prop def `className` values):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-date-picker-size-sm`, `.dsx-date-picker-size-md`, `.dsx-date-picker-size-lg` | `datepicker.css` |
+| `data-variant` | `default`, `ghost` | `.dsx-date-picker-variant-default`, `.dsx-date-picker-variant-ghost` | `datepicker.css` |
+| `data-placeholder` | `true` | `.dsx-date-picker__trigger[data-placeholder='true']` | `datepicker.css` |
+| `data-state` (Radix) | `open`, `closed` | `.dsx-date-picker__trigger[data-state='open']` | `datepicker.css` |
+
+The `data-size` and `data-variant` attributes drive both inline and modifier class forms. The modifier classes are applied via the prop def `className` and match the inline `[data-size='…']` selectors used by the trigger.
+
+**Slot classes:**
+
+| Region | Class | CSS file |
+|---|---|---|
+| Trigger | `dsx-date-picker__trigger` | `datepicker.css` |
+| Value container | `dsx-date-picker__value` | `datepicker.css` |
+| Leading icon | `dsx-date-picker__leading-icon` | `datepicker.css` |
+| Label | `dsx-date-picker__label` | `datepicker.css` |
+| Trailing icon | `dsx-date-picker__icon` | `datepicker.css` |
+| Popover content | `dsx-date-picker__content` | `datepicker.css` |
+| Calendar | `dsx-date-picker__calendar` | `datepicker.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- Trigger border, background, box-shadow, and color transitions use `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. The popover open transition is owned by `Popover`. The CSS file does not include a `prefers-reduced-motion` gate; the global stylesheet is expected to honor the media query.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Trigger min-height | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Default trigger height. |
+| Trigger min-height (sm) | `var(--dsx-density-control-height-sm, var(--dsx-size-lg))` | Small trigger height. |
+| Trigger min-height (lg) | `var(--dsx-density-control-height-lg, var(--dsx-size-2xl))` | Large trigger height. |
+| Trigger padding block | `var(--dsx-density-control-padding-block, var(--dsx-space-sm))` | Default trigger vertical padding. |
+| Trigger padding inline | `var(--dsx-density-control-padding-inline, var(--dsx-space-md))` | Default trigger horizontal padding. |
+| Trigger padding block (sm) | `var(--dsx-density-control-padding-block-sm, var(--dsx-space-xs))` | Small trigger vertical padding. |
+| Trigger padding inline (sm) | `var(--dsx-density-control-padding-inline-sm, var(--dsx-space-sm))` | Small trigger horizontal padding. |
+| Trigger padding block (lg) | `var(--dsx-density-control-padding-block-lg, var(--dsx-space-md))` | Large trigger vertical padding. |
+| Trigger padding inline (lg) | `var(--dsx-density-control-padding-inline-lg, var(--dsx-space-lg))` | Large trigger horizontal padding. |
+| Trigger gap | `var(--dsx-space-sm)` | Gap between value, leading icon, label, and trailing icon. |
+| Trigger border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Edge. |
+| Trigger radius | `var(--dsx-rounded-md)` | Corner roundness. |
+| Trigger background | `var(--dsx-color-surface)` | Resting surface. |
+| Trigger text | `var(--dsx-color-on-surface)` | Primary labels. |
+| Trigger typography | `var(--dsx-typography-body-medium-*)` | Trigger body text. |
+| Trigger hover border | `var(--dsx-color-outline-variant)` | Hover edge. |
+| Trigger hover background | `var(--dsx-color-surface-hover)` | Hover surface. |
+| Trigger focus border | `var(--dsx-color-primary)` | Focus edge. |
+| Trigger focus ring | `var(--dsx-shadow-focus-ring)` | Focus indicator. |
+| Trigger placeholder text | `var(--dsx-color-on-surface-variant)` | Placeholder label color. |
+| Trigger disabled opacity | `var(--dsx-opacity-disabled)` | Disabled state. |
+| Trigger disabled cursor | `var(--dsx-cursor-not-allowed, not-allowed)` | Disabled cursor. |
+| Value container gap | `var(--dsx-space-sm)` | Space between leading icon and label. |
+| Popover content width | `min(100%, var(--dsx-calendar-width))` | Cap content width. |
+| Popover content reset | none (transparent) | Resets inner popover surface so the calendar owns the visual frame. |
+| Calendar width | `var(--dsx-calendar-width)` | Calendar width inherited from `Calendar` slot. |
+| Transition | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Hover, focus, and popover open transitions. |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Trigger border, background, box-shadow, color | `var(--dsx-motion-duration-fast)` + `var(--dsx-motion-easing-standard)` | Trigger hover and focus transitions. | Relies on the global `prefers-reduced-motion` stylesheet. |
+| Popover open | `MOTION_TRANSITIONS.popover` | Inherited from `Popover`. | Inherited from `Popover`. |
+
+## Accessibility
+
+**Roles:**
+
+- The trigger is a native `<button>` (or a `Slot` host when `asChild` is set). The `asChild` host is responsible for its own role.
+- `Popover.Content` carries the `role="dialog"` semantics from Radix Popover.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to the trigger. Inside the popover, focus is managed by Radix Popover and `react-day-picker`. |
+| `Enter`, `Space` | Opens the popover when the trigger is focused. Inside the calendar, activates the focused day cell. |
+| `Escape` | Closes the popover. |
+| Arrow keys | Inside the calendar, navigate between day cells. |
+
+**Focus:**
+
+- Visible focus ring via `var(--dsx-shadow-focus-ring)` on the trigger.
+- Radix Popover manages focus inside the popover and returns focus to the trigger on close.
+
+**Reduced motion:**
+
+- Trigger transitions collapse under the global `prefers-reduced-motion` stylesheet. The popover transition is owned by `Popover` and respects the same media query.
+
+**Color and meaning:**
+
+- The selected state is communicated by the calendar's own `data-selected` and `aria-selected` attributes, plus the package's calendar palette. `data-placeholder="true"` distinguishes the empty state.
+
+**Naming:**
+
+- The trigger requires an accessible name via `aria-label` or `aria-labelledby`. `react-day-picker` auto-labels day cells with their full date string.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `DatePicker` with no extra props. Asserts the trigger has `dsx-date-picker__trigger`, `data-size="md"`, `data-placeholder="true"`, and the placeholder text "Pick a date".
+
+**Variant stories** (one per size and one per variant):
+
+- Renders with `size="sm"`, `size="md"`, and `size="lg"`. Asserts `data-size` matches on the trigger.
+- Renders with `variant="ghost"`. Asserts the `dsx-date-picker-variant-ghost` modifier class is applied.
+
+**Composition story:**
+
+- Renders with `asChild` and a custom `<button>` child. Asserts the custom child is the trigger host and still carries the `dsx-date-picker__trigger` class plus the `data-placeholder` attribute.
+
+**State story:**
+
+- Opens the popover, clicks a day cell, and asserts the trigger label switches from the placeholder to the formatted date and `data-placeholder` is removed.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper. Opens the popover and asserts the calendar is mounted inside an element that carries `data-dsx-theme` matching the wrapper. The popover content renders inside a `<Theme appearance="inherit">` so the active appearance is preserved.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select (`sm`, `md`, `lg`) | `md` |
+| `variant` | select (`default`, `ghost`) | `default` |
+| `placeholder` | text | `Pick a date` |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Calendar`: the lower-level date primitive. `DatePicker` renders `<Calendar mode="single" selected={value} onSelect={handleSelect} />` with the caller-supplied `calendarProps` merged on top.
+- `Popover`: hosts the popover lifecycle. `DatePicker` always renders `Popover.Trigger asChild` and `Popover.Content` so the theme is mirrored and the positioning is consistent with the rest of the overlay family.
+- `Icon`: renders the `calendar` leading glyph and the `chevron-down` trailing glyph.
+- `react-day-picker`: the adapter engine. `mode="single"`, `selected`, and `onSelect` are forced by `DatePicker` and not exposed through `calendarProps`.
+- `@radix-ui/react-slot`: enables `asChild` on the trigger.
+- `Theme`: wraps the calendar inside `Popover.Content` so the calendar inherits the active light or dark appearance.
+- `classnames`: used to merge the trigger and slot classes with the caller's `className`.
+
+**Used by:**
+
+- No DS component currently wraps `DatePicker`. The pattern is the intended app-side composition. Apps that need a form row wrap the picker in `Field`.
+
+**State boundaries:**
+
+- Owned by this component: the controlled and uncontrolled open state, the controlled and uncontrolled selected date, the popover close-on-select behavior, the trigger label formatting default, the `data-placeholder` attribute, the size and variant attributes, and the `dsx-date-picker__*` class wiring.
+- Owned by the adapter: the calendar grid, day-cell rendering, locale-aware month navigation, and selection state propagation through `onSelect`.
+- Owned by the consumer: the selected date value, the locale, the timezone, range and persistence semantics, the disabled date set, the trigger `aria-label`, and any custom `formatDate` function.
+
+**Boundary rules:**
+
+- App-owned data: the `value` and `defaultValue` `Date` values, the `formatDate` function, the `calendarProps` (locale, `numberOfMonths`, `disabled`, modifiers, custom `classNames`), and the `popoverContentProps` (side, alignment, side offset).
+- DS-owned visuals: token bindings, the `dsx-date-picker__*` selector hierarchy, the `data-size`, `data-variant`, and `data-placeholder` attributes, the popover content reset, and the theme inheritance inside the popover.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. The package source is the only authority.
+
+### Root board
+
+- **Name**: `Components / DatePicker`.
+- **Dimensions**: `320 × 360` (trigger plus open calendar).
+- **Layout**: `Flex` with `horizontalSizing = 'fix'`.
+
+### Layer tree
+
+```
+<Root Board: DatePicker>
+  ├── <Trigger>
+  │     ├── Leading icon (calendar)
+  │     ├── Label
+  │     └── Trailing icon (chevron-down)
+  └── <Popover content: Calendar>
+        ├── Month caption
+        ├── Nav group
+        ├── Weekday row
+        └── Day grid
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Trigger | fill | `var(--dsx-color-surface)` | Color | `fills` |
+| Trigger | stroke | `var(--dsx-color-outline)` | Color | `strokes` |
+| Trigger placeholder | text fill | `var(--dsx-color-on-surface-variant)` | Color | `fills` |
+| Trigger focused | stroke | `var(--dsx-color-primary)` | Color | `strokes` |
+| Calendar | fill | `var(--dsx-color-surface-raised)` | Color | `fills` |
+| Calendar selected day | fill | `var(--dsx-semantic-primary)` | Color | `fills` |
+
+### State transformations
+
+| State | Trigger fill | Trigger stroke | Label fill | Calendar |
+|---|---|---|---|---|
+| `default` | `var(--dsx-color-surface)` | `var(--dsx-color-outline)` | `var(--dsx-color-on-surface-variant)` | closed |
+| `hover` | `var(--dsx-color-surface-hover)` | `var(--dsx-color-outline-variant)` | `var(--dsx-color-on-surface)` | closed |
+| `open` | `var(--dsx-color-surface)` | `var(--dsx-color-primary)` | `var(--dsx-color-on-surface)` | open |
+| `disabled` | `var(--dsx-color-surface)` (opacity `--dsx-opacity-disabled`) | `var(--dsx-color-outline)` | `var(--dsx-color-on-surface-variant)` | closed |
+
+### Variant model
+
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `variant`: `default`, `ghost`. Default `default`.
+- Total members: 6 (3 sizes × 2 variants).
+
+### 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.