@d4gger/design-system 2.7.0

package/dist/docs/file-upload.md

@@ -0,0 +1,260 @@
+---
+title: FileUpload
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/fileUpload/FileUpload.tsx
+css_path: packages/d4gger-design-system/src/styles/components/file-upload.css
+props_path: packages/d4gger-design-system/src/components/fileUpload/fileUpload.props.ts
+test_path: packages/d4gger-design-system/src/test/components/FileUpload.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:
+  - Card
+  - EmptyState
+  - Item
+  - Progress
+  - Button
+  - Icon
+---
+
+# FileUpload
+
+> 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 card-based file selection surface with a dropzone, a list of file rows, and a progress bar per row. The dropzone is built on `EmptyState` and exposes a `dragging` data attribute, the list wraps `Item` rows that compose a `Progress` bar and an actions block, and the root is a `Card` so the whole surface fits the standard card surface treatment.
+
+## Anatomy & slots
+
+**Parent:** `FileUpload` (alias of `FileUpload.Root`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `FileUpload.Root` | `Card.Root` | card host | The surface container. Writes `data-size`. |
+| `FileUpload.Dropzone` | `EmptyState` (rendered through a `<section>`) | dropzone target with title, description, illustration, and action | Exposes `data-dragging` for the active drop state. |
+| `FileUpload.List` | `<div>` | vertical list container | The list of `FileUpload.Item` rows. |
+| `FileUpload.Item` | `Item` | one file row with media, content, and actions | Composes `ItemMedia`, `ItemContent` (title, description, optional progress), and `ItemActions` (status, actions). |
+| `FileUpload.Progress` | `<div>` wrapping `Progress` | progress bar + optional label | When `showValueLabel` is `true` and no `label` is provided, the progress label is ``${Math.round(value)}%``. |
+
+## Props contract
+
+### `FileUpload.Root` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Card-level size token. Drives `data-size`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the card through `Slot` from `@radix-ui/react-slot`. | no |
+| Standard `Card` props | `CardProps` | n/a | no | The root extends `CardProps`, so variant, radius, and standard card attributes pass through. | no |
+| `children` | `React.ReactNode` | `undefined` | no | `FileUpload.Dropzone`, `FileUpload.List`, and `FileUpload.Item` children. | no |
+
+### `FileUpload.Dropzone` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `title` | `ReactNode` | — | yes | Dropzone headline. | no |
+| `description` | `ReactNode` | `undefined` | no | Dropzone body text. | no |
+| `illustration` | `ReactNode` | `undefined` | no | Custom illustration. Defaults to an `Icon name="upload" size="lg"`. | no |
+| `action` | `ReactNode` | `undefined` | no | Custom action element. Takes precedence over `actionLabel`. | no |
+| `actionLabel` | `ReactNode` | `undefined` | no | Default action label. When set without an explicit `action`, the dropzone renders a `Button` with `variant="outline"`. | no |
+| `onActionClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined` | no | Default action click handler. | no |
+| `dragging` | `boolean` | `false` | no | Active drop state. Drives `data-dragging="true"`. | no |
+| `asChild` | `boolean` | `false` | no | Renders the dropzone through `Slot` from `@radix-ui/react-slot`. | no |
+| Standard `EmptyState` props | `EmptyStateProps` (without `action`, `description`, `illustration`, `title`) | n/a | no | The dropzone omits the four props it owns and forwards the rest. | no |
+
+### `FileUpload.List` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the list through `Slot`. | no |
+| `children` | `React.ReactNode` | `undefined` | no | `FileUpload.Item` children. | no |
+| Standard `<div>` props | `ComponentPropsWithoutRef<'div'>` | n/a | no | Forwarded. | no |
+
+### `FileUpload.Item` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `fileName` | `ReactNode` | — | yes | File name. Rendered as the `ItemTitle`. | no |
+| `description` | `ReactNode` | `undefined` | no | Optional `ItemDescription` text. | no |
+| `icon` | `ReactNode` | `undefined` | no | Custom file icon. When `null`, the icon slot is hidden. Default is `Icon name="file" size="sm"`. | no |
+| `progress` | `number` | `undefined` | no | When a number, the item renders a `FileUpload.Progress` with this value. | no |
+| `progressLabel` | `ReactNode` | `undefined` | no | Custom progress label. Overrides the auto `${value}%` label. | no |
+| `status` | `ReactNode` | `undefined` | no | Status text rendered above the actions block. | no |
+| `actions` | `ReactNode` | `undefined` | no | Action affordances rendered in the `ItemActions` block. | no |
+| `asChild` | `boolean` | `false` | no | Renders the item through `Slot`. | no |
+| Standard `Item` props | `Omit<ItemProps, 'children'>` | n/a | no | Forwarded. The interface omits `children` because the item composes its own. | no |
+
+### `FileUpload.Progress` props
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `label` | `ReactNode` | `undefined` | no | Custom progress label. Overrides the auto `${Math.round(value)}%` label. | no |
+| `showValueLabel` | `boolean` | `false` | no | When `true` and no `label` is provided, the progress label is the rounded percentage. | no |
+| Standard `Progress` props | `ProgressProps` | n/a | no | Forwarded. | no |
+
+Rules:
+
+- The Dropzone is intentionally built on `EmptyState`. The `action`, `description`, `illustration`, and `title` props on the dropzone's source-level `EmptyStateProps` are omitted from the typed interface so the dropzone owns them.
+- The Dropzone's resolved action is the explicit `action` prop when set, otherwise a `Button` rendered with `variant="outline"` and the `onActionClick` handler. When neither is set, the action is `null`.
+- The Item's `icon` prop accepts a `ReactNode`. Passing `null` (not `undefined`) hides the icon entirely; passing `undefined` falls back to the default `file` icon.
+
+## CSS class contract
+
+**Root class:** `dsx-file-upload` (rendered by the card).
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | n/a (no size-specific root CSS today) | `file-upload.css` |
+| `data-dragging` | `true` | `.dsx-file-upload__dropzone[data-dragging='true']` border, background, and focus ring | `file-upload.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `FileUpload.Root` | `dsx-file-upload` (via `Card.Root`) | `file-upload.css` |
+| `FileUpload.Dropzone` | `dsx-file-upload__dropzone` | `file-upload.css` |
+| Dropzone icon | `dsx-file-upload__dropzone-icon` | `file-upload.css` |
+| `FileUpload.List` | `dsx-file-upload__list` | `file-upload.css` |
+| `FileUpload.Item` | `dsx-file-upload__item` | `file-upload.css` |
+| Item media | `dsx-file-upload__media` | `file-upload.css` |
+| Item icon | `dsx-file-upload__icon` | `file-upload.css` |
+| Item content | `dsx-file-upload__content` | `file-upload.css` |
+| Item title | `dsx-file-upload__title` | `file-upload.css` |
+| Item actions | `dsx-file-upload__actions` | `file-upload.css` |
+| Item status | `dsx-file-upload__status` | `file-upload.css` |
+| `FileUpload.Progress` | `dsx-file-upload__progress` | `file-upload.css` |
+| Progress track | `dsx-file-upload__progress-track` | `file-upload.css` |
+| Progress label | `dsx-file-upload__progress-label` | `file-upload.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size is single-value only.
+
+**Reduced motion:**
+
+- The dropzone transitions `background-color`, `border-color`, and `box-shadow` against `var(--dsx-motion-duration-fast, 150ms)` and `var(--dsx-motion-easing-standard, ease)`. The CSS does not include a `prefers-reduced-motion` guard today; the global stylesheet is the fallback path.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Root layout | `display: grid; gap: var(--dsx-space-md); width: 100%` | Surface layout. |
+| Dropzone width | `width: 100%` | Full width. |
+| Dropzone min-height | `calc(var(--dsx-size-4xl) * 2)` | Tall enough to invite a drop. |
+| Dropzone border | `var(--dsx-border-width-sm)` dashed `var(--dsx-color-outline-variant)` | Resting edge. |
+| Dropzone radius | `var(--dsx-rounded-lg)` | Round corners. |
+| Dropzone background | `var(--dsx-color-surface-sunken)` | Sunken surface. |
+| Dropzone transition | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Border, background, and box-shadow transitions. |
+| Dropzone dragging border | `var(--dsx-color-primary)` | Active edge. |
+| Dropzone dragging background | `var(--dsx-color-high-contrast-container)` | Active fill. |
+| Dropzone dragging shadow | `var(--dsx-shadow-focus-ring)` | Active focus ring. |
+| Dropzone icon color | `var(--dsx-color-primary)` | Active affordance color. |
+| Item icon size | `var(--dsx-size-lg)` square | Round icon slot. |
+| Item icon color | `var(--dsx-color-on-surface-variant)` | Quiet icon. |
+| Item content min-width | `min-width: 0` | Allows the title to ellipsis. |
+| Item title overflow | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` | Long file names truncate. |
+| Item media color | `var(--dsx-color-on-surface-variant)` | Quiet media. |
+| Item actions alignment | `margin-left: auto; flex-direction: column; align-items: flex-end; gap: var(--dsx-space-xs)` | Right-aligned, stacked. |
+| Progress width | `width: 100%` | Full row width. |
+| Progress label/status typography | `var(--dsx-typography-label-small-*)` | Small label ramp. |
+| Progress label/status color | `var(--dsx-color-on-surface-variant)` | Quiet label. |
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Dropzone border, background, box-shadow | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Transitions when `data-dragging` flips | The CSS does not currently include a reduced-motion guard; the global stylesheet is the fallback path. |
+
+## Accessibility
+
+**Roles:**
+
+- The root is a `Card.Root`, so it carries no implicit ARIA role. The dropzone is rendered through `EmptyState` and inherits the same `role` posture. The list is a plain `<div>`. The item is an `Item` and inherits its own role posture.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus into and out of the dropzone, then through the file rows, the progress bar, and the actions. |
+| `Enter`, `Space` | Activates the focused affordance (dropzone action button, item action button, etc.). |
+
+**Focus:**
+
+- The dropzone relies on the underlying `EmptyState` and `Button` focus rules. The `data-dragging='true'` state adds the focus ring to the dropzone as a visual cue.
+
+**Reduced motion:**
+
+- The dropzone transitions honor the global `prefers-reduced-motion` stylesheet.
+
+**Color and meaning:**
+
+- Drag state is communicated by the dashed border swap to `var(--dsx-color-primary)`, the background swap, and the focus ring. Color is paired with the dashed-to-solid border change, so the meaning is not color-only.
+
+**Naming:**
+
+- The dropzone should expose an accessible name via its `title` prop. The default action button labels itself through the `actionLabel` prop. Each `FileUpload.Item` is named by its `fileName` content.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `FileUpload` with one `FileUpload.Dropzone` carrying `title="Upload files"`. Asserts the root class is `dsx-file-upload`, `data-size="md"`, and the dropzone renders with `dsx-file-upload__dropzone`.
+
+**Size story:**
+
+- Renders the root with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute on the root.
+
+**Drag state story:**
+
+- Renders the dropzone with `dragging={true}`. Asserts `data-dragging="true"` and the dropzone border, background, and shadow rules resolve.
+
+**Composition story:**
+
+- Renders the full surface: dropzone, list, two items. The first item has a `progress={42}` and a `progressLabel="Uploading…"`. The second item has a `status="Complete"` and an `actions={<Button>Remove</Button>}`. Asserts each slot renders with the right class, the progress bar renders with the rounded percentage, and the actions block sits at the right edge.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default surface. Asserts the dropzone has an accessible name, every item has a `fileName`, and the action buttons have visible text.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `dragging` | boolean | `false` |
+| `showValueLabel` | boolean | `false` |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Card`: the root extends `CardProps` and renders through `Card.Root`.
+- `EmptyState`: the dropzone extends `EmptyStateProps` and renders through `EmptyState`.
+- `Item` and its subcomponents: the file row composes `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, and `ItemActions`.
+- `Progress`: the progress block composes the package `Progress` primitive.
+- `Button`: the default dropzone action renders through `Button` with `variant="outline"`.
+- `Icon` (lucide-react `upload`, `file`): the default illustrations.
+- `@radix-ui/react-slot`: enables `asChild` on the root, dropzone, list, and item hosts.
+
+**Used by:**
+
+- Form specs that need a managed file picker. Apps own the file selection pipeline, the upload progress source, the onAction click handler, and the actual upload transport.
+
+**State boundaries:**
+
+- Owned by FileUpload: the root card surface, the dropzone presentation, the file row layout, the progress block, and the auto `${value}%` label derivation.
+- Owned by the consumer: the file list, the upload progress source, the dropzone click handler, the drag state (`dragging` is a controlled boolean), the per-item `fileName` and `description`, and the surrounding form context.
+
+**Boundary rules:**
+
+- App-owned data: the files, the upload pipeline, the drag detection (the package does not implement drag-and-drop, only the visual `dragging` state), the validation, and the persisted references.
+- DS-owned visuals: the surface, the dropzone, the list, the item, the progress block, the icons, the labels, and the size token.

package/dist/docs/filter-bar.md

@@ -0,0 +1,77 @@
+---
+title: FilterBar
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/filterBar/FilterBar.tsx
+css_path: packages/d4gger-design-system/src/styles/components/filter-bar.css
+props_path: packages/d4gger-design-system/src/components/filterBar/filterBar.props.ts
+test_path: packages/d4gger-design-system/src/test/components/FilterBar.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:
+  - Toolbar
+  - Button
+---
+
+# FilterBar
+
+## 2.6 contract
+
+Root accepts optional `activeCount`. `FilterBar.Control` applies the same wrapper contract to search, select, date, and custom filters and writes `data-active`. `FilterBar.Count` reads the root count. `FilterBar.Clear` is disabled when an explicit active count is zero; omitting `activeCount` preserves the 2.5 uncontrolled compatibility behavior.
+
+## Purpose
+
+A product-agnostic, wrapping filter toolbar that organizes consumer-controlled filter controls, result summary, actions, and a clear callback.
+
+## Anatomy & slots
+
+**Parent:** `FilterBar` (alias of `FilterBar.Root`).
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `FilterBar.Root` | `div role="toolbar"` | `dsx-filter-bar` | Default accessible name is `Filters`. |
+| `FilterBar.Group` | `div role="group"` | `dsx-filter-bar__group` | Groups related controls. |
+| `FilterBar.Summary` | `div` | `dsx-filter-bar__summary` | Result/filter summary. |
+| `FilterBar.Actions` | `div` | `dsx-filter-bar__actions` | Action cluster. |
+| `FilterBar.Clear` | `Button` | `dsx-filter-bar__clear` | Styled callback only. |
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Toolbar density. | no |
+| `aria-label` | `string` | `'Filters'` | no | Accessible toolbar name. | no |
+| `className` | `string` | `undefined` | no | Appended root class. | no |
+
+`FilterBar.Clear` accepts Button props and an optional `onClear: () => void`; its default children are `Clear filters`. All wrapper slots accept standard div attributes.
+
+## CSS class contract
+
+Root `dsx-filter-bar` writes `data-size`. Slot classes are `dsx-filter-bar__group`, `__summary`, `__actions`, and `__clear`. The shell uses flex wrapping without embedded product breakpoints.
+
+## Token mapping
+
+| Property | Token | Role |
+|---|---|---|
+| Gap/padding | `var(--dsx-space-sm)` / `var(--dsx-space-md)` | Responsive wrapping rhythm |
+| Border | `var(--dsx-control-separator-color)` | Muted toolbar edge |
+| Background | `var(--dsx-color-surface-raised)` | Toolbar surface |
+| Radius | `var(--dsx-rounded-lg)` | Shell roundness |
+
+## Motion contract
+
+No motion.
+
+## Accessibility
+
+The root is a named toolbar. Tab order follows DOM order and controls retain their own semantics; FilterBar does not implement roving focus because it may contain form controls. Groups may provide their own accessible names. Clear is a native button and never mutates sibling controls automatically.
+
+## Playground demo spec
+
+Show default, all sizes, full slot composition, empty/active summary, light/dark, and alternate accents. The composition story demonstrates source, direction, and a paired DatePicker range using consumer state. Test Clear callback/keyboard behavior and `vitest-axe`.
+
+## Wiring notes
+
+Consumers own all filter values, reset logic, query execution, date-range policy, and domain fields. The DS owns only layout, slots, accessible naming, and Clear styling.

package/dist/docs/flex.md

@@ -0,0 +1,222 @@
+---
+title: Flex
+status: canonical
+category: Foundations
+archetype: layout-primitive
+package_path: packages/d4gger-design-system/src/components/flex/Flex.tsx
+css_path: packages/d4gger-design-system/src/styles/components/flex.css
+props_path: packages/d4gger-design-system/src/layout/layout.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Flex.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/layout.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Box
+---
+
+# Flex
+
+> 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
+
+A horizontal or vertical flex layout primitive that turns design-token style props (direction, align, justify, wrap, gap, plus the inherited `Box` style props) into a CSS flexbox host. `Flex` extends `Box` and is the canonical primitive for row/column composition in app shells and product surfaces.
+
+## Anatomy & slots
+
+**Parent:** `Flex` (alias of `Flex.Root`; flat export, no compound).
+
+**Slots:**
+
+No slots: flat export. `Flex` is a single forwardRef that renders a host element chosen by `as`, or `div` by default. The body is whatever the consumer passes as `children`.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `as` | `React.ElementType` | `'div'` | no | Host element. `asChild` takes precedence when set. | no |
+| `asChild` | `boolean` | `false` | no | Renders the host through `Slot`; consumer supplies the child. | no |
+| `direction` | `ResponsiveValue<'row' \| 'column' \| 'row-reverse' \| 'column-reverse'>` | `'row'` | no | CSS `flex-direction`. Writes `dsx-r-fd-{value}` and per-breakpoint prefixes. | yes (initial, sm, md, lg, xl, 2xl) |
+| `align` | `ResponsiveValue<'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'>` | `undefined` | no | CSS `align-items`. `start` resolves to `flex-start`, `end` to `flex-end`. Writes `dsx-r-ai-{value}` and per-breakpoint prefixes. Also serialized into the `data-align` attribute. | yes (initial, sm, md, lg, xl, 2xl) |
+| `justify` | `ResponsiveValue<'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'>` | `undefined` | no | CSS `justify-content`. `start`/`end` resolve to `flex-start`/`flex-end`; `between`/`around`/`evenly` resolve to `space-*`. Writes `dsx-r-jc-{value}` and per-breakpoint prefixes. Also serialized into `data-justify`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `wrap` | `ResponsiveValue<'nowrap' \| 'wrap' \| 'wrap-reverse'>` | `'nowrap'` | no | CSS `flex-wrap`. Writes `dsx-r-fw-{value}` and per-breakpoint prefixes. | yes (initial, sm, md, lg, xl, 2xl) |
+| `gap` | `ResponsiveValue<SpaceToken \| string>` | `undefined` | no | Gap between children. Resolves `--dsx-box-gap`. Serialized into `data-gap`. | yes (initial, sm, md, lg, xl, 2xl) |
+| (all `Box` style props) | (see [Box](./box.md)) | `undefined` | no | Inherited: `display`, `position`, `padding`, `paddingX`, `paddingY`, `px`, `py`, `pt`, `pr`, `pb`, `pl`, `p`, `margin`, `m`, `mx`, `my`, `mt`, `mr`, `mb`, `ml`, `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`, `inset`, `zIndex`, `hide`, `show`, `radius`, `surface`, `shadow`, `border`, `borderTone`, `alignSelf`, `justifySelf`, `flex`, `flexBasis`, `flexGrow`, `flexShrink`, `order`, `gridArea`, `gridColumn`, `gridRow`. | yes where Box marks them responsive |
+| `className` | `string` | `undefined` | no | Extra classes appended to the generated utility class string. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Extra inline style merged with the generated `--dsx-*` variables. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Flex body. | no |
+| `ref` | `React.Ref<HTMLElement>` | `undefined` | no | Forwarded to the host element. | no |
+
+Rules:
+
+- Every prop above is declared on `Flex` in `Flex.tsx` or in `BoxStyleProps` / `FlexStyleProps` from `layout.props.ts`. The runtime type is the source of truth.
+- `data-gap`, `data-align`, and `data-justify` are written as serialized breakpoint maps (`initial:md;sm:lg`). When only the `initial` value is set, the attribute is the bare value (`md`).
+- The `Responsive` column is `yes` for `direction`, `align`, `justify`, `wrap`, and `gap`. The Box-inherited props are `yes` where Box marks them responsive.
+- The `data-*` attributes are descriptive only; the visual flex rules come from the `dsx-r-*` utility classes plus `--dsx-box-gap`.
+
+## CSS class contract
+
+**Root class:** `dsx-flex`
+
+In addition, Flex writes `dsx-box` (the Box host class) so the Box padding/margin/sizing tokens apply.
+
+**Utility classes** (driven by prop values):
+
+| Class | CSS file | Resolved property |
+|---|---|---|
+| `dsx-r-fd-{row \| column \| row-reverse \| column-reverse}` | `flexDirection.css` | `flex-direction` |
+| `dsx-r-ai-{start \| center \| end \| stretch \| baseline}` | `alignItems.css` | `align-items` |
+| `dsx-r-jc-{start \| center \| end \| between \| around \| evenly}` | `justifyContent.css` | `justify-content` |
+| `dsx-r-fw-{nowrap \| wrap \| wrap-reverse}` | `flexWrap.css` | `flex-wrap` |
+| `sm:dsx-r-fd-*`, `md:dsx-r-fd-*`, `lg:dsx-r-fd-*`, `xl:dsx-r-fd-*`, `2xl:dsx-r-fd-*` | `flexDirection.css` | Breakpoint-prefixed variants |
+
+The runtime also produces the same set of classes for the `align`, `justify`, and `wrap` props via `getResponsiveUtilityClassNames`.
+
+**Modifier attributes:**
+
+| Attribute | Value | Notes |
+|---|---|---|
+| `data-gap` | serialized `ResponsiveValue` of `gap` | Visual value, e.g. `initial:md;sm:lg` or `md` |
+| `data-align` | serialized `ResponsiveValue` of `align` | Visual value |
+| `data-justify` | serialized `ResponsiveValue` of `justify` | Visual value |
+
+The `dsx-flex` selector sets `display: var(--dsx-box-display, flex)` so the default Flex container is `display: flex`.
+
+**Slot classes:** none. Flex is a flat export.
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules for direction, align, justify, or wrap. Responsive prefixes are generated as classes.
+- `flex.css` does write `@media (min-width: ...)` blocks for `sm`, `md`, `lg`, `xl`, `2xl` so the `--dsx-box-display` cascade works.
+
+**Reduced motion:**
+
+- Flex has no motion. No transitions or animations are declared in `flex.css`.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Display | `var(--dsx-box-display, flex)` | Default flex display |
+| Gap | `var(--dsx-box-gap, 0)` | Default gap (Box-defined) |
+| (all inherited Box tokens) | (see [Box](./box.md)) | Padding, margin, sizing, surface, radius, border, shadow |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in the CSS. Tokens only.
+- The token list is closed; new tokens are a `DESIGN.md` change first.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | `none` | `none` | `none` |
+
+Flex has no motion. The motion section is intentionally empty.
+
+## Accessibility
+
+**Roles:**
+
+- `Flex` has no implicit ARIA role. The host element defaults to `<div>`. Consumers should set `role` explicitly when the surface needs a semantic role.
+
+**Keyboard:**
+
+- Flex is not interactive. No keyboard contract beyond the page-level Tab order.
+
+**Focus:**
+
+- Flex has no interactive surface. Focus management is the consumer's responsibility.
+
+**Reduced motion:**
+
+- N/A. Flex has no motion.
+
+**Color and meaning:**
+
+- Flex does not paint a surface, border, or shadow on its own. Any visual state comes from inherited Box props and is paired with the consumer's content for meaning.
+
+**Naming:**
+
+- Flex is not interactive and does not require an accessible name on its own. When Flex wraps an interactive element, the interactive element's accessible name is the source.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Flex gap="2" align="center"` with three child squares. Asserts the root class is `dsx-flex`, the host element is a `div`, and the children render in row order.
+
+**Direction story:**
+
+- Renders `Flex direction="column" gap="2"` with three child squares. Asserts the `dsx-r-fd-column` class and the host's `data-gap="2"`.
+
+**Justify story:**
+
+- Renders `Flex justify="between" align="center"` with two children. Asserts the `dsx-r-jc-between` and `dsx-r-ai-center` classes and the matching `data-justify` and `data-align` attributes.
+
+**Wrap story:**
+
+- Renders `Flex wrap="wrap" gap="1"` with five child chips. Asserts the `dsx-r-fw-wrap` class.
+
+**Responsive story:**
+
+- Renders `Flex direction={{ initial: 'row', sm: 'column', md: 'row' }}` and asserts `dsx-r-fd-row`, `sm:dsx-r-fd-column`, `md:dsx-r-fd-row` are all present.
+
+**Composition story:**
+
+- Renders `Flex` with two `Box` children showing different surface tones. Asserts the children keep their own `dsx-box` class and inherit the Flex container's gap.
+
+**State story:**
+
+- No discrete state. The story renders a default Flex with three children.
+
+**Token story:**
+
+- Flex does not honor `data-accent-color`. Render inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. The story asserts the layout is unchanged and surfaces come from the theme.
+
+**A11y story:**
+
+- Use `vitest-axe` against the rendered Flex. The default render is a non-semantic `div` with text content; tests assert no violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `direction` | select | `row` |
+| `align` | select | `stretch` |
+| `justify` | select | `start` |
+| `wrap` | select | `nowrap` |
+| `gap` | select | `md` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Box`: the host class and inherited style props. Flex writes `dsx-flex` and `dsx-box` together.
+- `Slot` from `@radix-ui/react-slot`: enables `asChild`.
+- `_internal/props/propDef.ts` and the helpers in `_internal/helpers/`: the responsive class + custom-property pipeline.
+- `foundations/Shared.tsx`: `PolymorphicProps` and the `resolve*` helpers.
+- `layout/responsive.props.ts`: `BREAKPOINTS`, `ResponsiveValue`, `toResponsiveMap`, `assignResponsiveVars`.
+- `layout/layout.props.ts`: `BoxStyleProps`, `FlexStyleProps`, `BOX_PROP_DEFS`, `FLEX_PROP_DEFS`, `extractLayoutProps`.
+- `styles/components/flex.css`: the `.dsx-flex` host rule plus breakpoint cascade.
+- `styles/responsive/flexDirection.css`, `flexWrap.css`, `alignItems.css`, `justifyContent.css`: utility classes.
+
+**Used by:**
+
+- `Stack`, `Container`, `Sidebar`, `Item`, `Toolbar`, `DataList`, `Field`, `Form`, `Card`, `Alert`, and most other composites: build their flex containers on top of `Flex` (directly or through the inherited `dsx-flex` class).
+
+**State boundaries:**
+
+- Owned by `Flex`: the host element selection (`as` / `asChild`), the responsive prop resolution, the generated utility classes, the `dsx-flex` / `dsx-box` host classes, and the `data-gap` / `data-align` / `data-justify` attributes.
+- Owned by the consumer: the children, the host element tag, the user-supplied `className` and `style`, the ref target.
+
+**Boundary rules:**
+
+- App-owned data: the children content and any host element chosen via `as` or `asChild`.
+- DS-owned visuals: token bindings, the `dsx-flex` and `dsx-box` root classes, the responsive utility classes, and the `data-*` attribute contract.
+
+## Penpot build recipe
+
+Flex is a layout primitive. The package code is the only authority. There is no published Penpot build recipe for Flex. A future Penpot board would show a flex container with direction, gap, align, and justify controls, but the spec intentionally does not duplicate the runtime class contract in a visual recipe.