@d4gger/design-system 2.7.0

package/dist/docs/form.md

@@ -0,0 +1,333 @@
+---
+title: Form
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/form/Form.tsx
+css_path: packages/d4gger-design-system/src/styles/components/form.css
+props_path: packages/d4gger-design-system/src/components/form/form.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Form.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:
+  - react-hook-form (the `Form` composite wires its submission through `useForm`'s `handleSubmit`; the `FormField` slot is a thin wrapper around `Controller`)
+  - Field (per the roster's `Composed From` column; the runtime does not import `Field` directly — `Form` is an orchestration layer around the same primitives `Field` composes, see Anomalies)
+  - Label (the `Form.Label` slot renders through the `Label` primitive for accessible `<label htmlFor>` association)
+  - "@radix-ui/react-slot (asChild on every subcomponent)"
+---
+
+# Form
+
+> 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
+
+An orchestration layer for form-level submission and field validation. `Form` wires the surrounding `<form>` element to `react-hook-form`, generates stable IDs for each field, propagates the field's `error` and `description` IDs into the wrapped control, and renders the message slot as an `aria-live="polite"` region. `Form` does not replace `Field`; it composes the same primitives `Field` exposes (label, control, description, error) and adds the orchestration that the design repo's other form-row components assume.
+
+## Anatomy & slots
+
+**Parent:** `Form` (alias of `Form.Root` and of the `FormLayout` convenience object that re-exports `Form` with the rest of the slots attached).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Form` (Root) | `<form>` (or a slotted host) | `dsx-form`, plus `data-layout` and `data-slot="form"` | The `<form>` element. Wires `onSubmit` through `form.handleSubmit(onSubmit)` when both `form` and `onSubmit` are provided. |
+| `Form.Field` | `Controller` from `react-hook-form` (no DOM output on its own) | n/a (renders nothing; supplies context through `render` prop) | The orchestration primitive. Wraps the consumer's `render` callback with a `FormFieldContext.Provider`. |
+| `Form.Item` | `<div>` (or slotted host) | `dsx-form__item`, plus `data-slot="form-item"` | The row wrapper. Provides the auto-generated `id`, `errorId`, and `descriptionId` through `FormFieldContext`. |
+| `Form.Label` | `<label>` through the `Label` primitive | `dsx-form__label`, plus `data-slot="form-label"` | Accessible label. Reads `id` from `FormFieldContext` and applies it as `htmlFor` unless the consumer supplies an explicit `htmlFor`. |
+| `Form.Control` | `<div>` (or slotted host) | `dsx-form__control`, plus `data-slot="form-control"` | Wraps the actual form control. Clones the single child element to set `id`, `aria-describedby`, and `aria-invalid` from context. |
+| `Form.Message` | `<p>` (or a slotted host when `asChild` is set) | `dsx-form__message`, plus `data-slot="form-message"`. `role="alert"`, `aria-live="polite"`. | Error or status message. Renders nothing if there is no `error` and no `children`. |
+| `Form.Header` | `<div>` (or slotted host) | `dsx-form__header`, plus `data-slot="form-header"` | Optional heading region above the body. |
+| `Form.Title` | `<h3>` (or slotted host) | `dsx-form__title`, plus `data-slot="form-title"` | The form title. |
+| `Form.Description` | `<p>` (or slotted host) | `dsx-form__description`, plus `data-slot="form-description"` | The form description. Reads `id` from context and applies it as the description's `id`. |
+| `Form.Body` | `<div>` (or slotted host) | `dsx-form__body`, plus `data-slot="form-body"` | The field region. |
+| `Form.Actions` | `<div>` (or slotted host) | `dsx-form__actions`, plus `data-slot="form-actions"` | The action button row. |
+
+`FormFieldContext` and `useFormField` are also exported. `useFormField` throws `'useFormField must be used within FormItem'` when used outside a `Form.Item` provider; the error message is part of the public contract and is asserted by the unit test.
+
+## Props contract
+
+**Root props (`Form` / `Form.Root`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. | no |
+| `layout` | `'standard' \| 'compact'` | `'standard'` | no | Row-gap profile. Writes `data-layout` and the `dsx-form-layout` class. The CSS uses the attribute to swap between `var(--dsx-space-lg)` and `var(--dsx-space-md)`. | no |
+| `form` | `UseFormReturn<TFieldValues>` | `undefined` | no | The `react-hook-form` instance. When provided together with `onSubmit`, the root wires `onSubmit={form.handleSubmit(onSubmit)}`. | no |
+| `onSubmit` | `(values: TFieldValues) => void \| Promise<void>` | `undefined` | no | The submission handler. Only wired when `form` is also provided. | no |
+| (HTML form props) | n/a | n/a | no | All standard `<form>` attributes are forwarded. `onSubmit` is omitted from the forwarded bag because the root owns it. | no |
+
+`FormProps<TFieldValues>` is a generic over the form's field values. The default is `FieldValues`.
+
+**`Form.Field` props:** `FormFieldProps<TFieldValues, TName>` is the full `ControllerProps` type from `react-hook-form`. The runtime is a thin wrapper around `Controller` that supplies `FormFieldContext` based on the controller's `fieldState.error`.
+
+**`Form.Item` props:** standard `React.ComponentPropsWithoutRef<'div'>` plus `asChild`.
+
+**`Form.Label` props:** standard `React.ComponentPropsWithoutRef<typeof Label>` plus `asChild`. The runtime resolves `htmlFor` from the context-provided `id` unless the consumer passes an explicit `htmlFor`.
+
+**`Form.Control` props:** standard `React.ComponentPropsWithoutRef<'div'>` plus `asChild`. The runtime expects exactly one child element. It clones that element to inject `id`, `aria-describedby`, and `aria-invalid` from context. The cloned `aria-invalid` is computed as `children.props['aria-invalid'] ?? (ctx?.hasError ? true : undefined)`, so an explicit `aria-invalid` on the child wins over the context-derived value.
+
+**`Form.Message` props:**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `error` | `FieldError \| string` | `undefined` | no | The error to render. When a `FieldError` object is passed, `error.message` is the rendered text. When a string is passed, it is rendered as-is. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Override for the message content. Wins over the `error` prop. | no |
+| `asChild` | `boolean` | `false` | no | Renders the message through `Slot` when `asChild` is set and the content is a single valid element. Otherwise the message renders as a `<p>`. | no |
+| (HTML p props) | n/a | n/a | no | All standard `<p>` attributes are forwarded. | no |
+
+The message renders nothing when there is no `error` and no `children`.
+
+**`Form.Header`, `Form.Body`, `Form.Actions` props:** standard `React.ComponentPropsWithoutRef<'div'>` plus `asChild`.
+
+**`Form.Title` props:** standard `React.ComponentPropsWithoutRef<'h3'>` plus `asChild`.
+
+**`Form.Description` props:** standard `React.ComponentPropsWithoutRef<'p'>` plus `asChild`. The runtime resolves the description's `id` from the `FormFieldContext` so the control's `aria-describedby` points at it.
+
+Rules that apply to this row:
+
+- The root's `onSubmit` is computed as `form && onSubmit ? form.handleSubmit(onSubmit) : undefined`. The root never attaches its own `onSubmit` handler.
+- `Form.Item` is the only slot that supplies an `id`, `errorId`, and `descriptionId` to the context. `Form.Label`, `Form.Control`, `Form.Description`, and `Form.Message` all read from that context.
+- `FormFieldContext` and `useFormField` are exported alongside the components so consumers can build their own slots (e.g. a `Form.Hint` that consumes `errorId` and `descriptionId`).
+- `FormLayoutType` is exported as the union of `Form`'s `layout` values.
+
+## CSS class contract
+
+**Root class:** `dsx-form`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-layout` | `standard`, `compact` | `.dsx-form[data-layout='standard']` row-gap `var(--dsx-space-lg)`; `.dsx-form[data-layout='compact']` row-gap `var(--dsx-space-md)` | `form.css` |
+| `data-slot` | `form` | (attribute written for tooling) | `form.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Form` (Root) | `dsx-form` | `form.css` |
+| `Form.Item` | `dsx-form__item` | `form.css` |
+| `Form.Label` | `dsx-form__label` | `form.css` |
+| `Form.Control` | `dsx-form__control` | `form.css` |
+| `Form.Message` | `dsx-form__message` | `form.css` |
+| `Form.Header` | `dsx-form__header` | `form.css` |
+| `Form.Title` | `dsx-form__title` | `form.css` |
+| `Form.Description` | `dsx-form__description` | `form.css` |
+| `Form.Body` | `dsx-form__body` | `form.css` |
+| `Form.Actions` | `dsx-form__actions` | `form.css` |
+
+**Data slots** (used by QA and audit tooling, not visual):
+
+| Element | `data-slot` |
+|---|---|
+| `Form` (Root) | `form` |
+| `Form.Item` | `form-item` |
+| `Form.Label` | `form-label` |
+| `Form.Control` | `form-control` |
+| `Form.Message` | `form-message` |
+| `Form.Header` | `form-header` |
+| `Form.Title` | `form-title` |
+| `Form.Description` | `form-description` |
+| `Form.Body` | `form-body` |
+| `Form.Actions` | `form-actions` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of the prop defs are `responsive: true`. Layout is single-value only.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- The component does not animate. The CSS does not declare transitions for any `Form` class.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Row gap (standard) | `var(--dsx-space-lg)` | Default row gap. |
+| Row gap (compact) | `var(--dsx-space-md)` | Compact row gap. |
+| Header gap | `var(--dsx-space-xs)` | Header inner gap. |
+| Body gap | `var(--dsx-space-md)` | Body inner gap. |
+| Item gap | `var(--dsx-space-xs)` | Item inner gap. |
+| Control gap | `var(--dsx-space-xs)` | Control inner gap. |
+| Actions gap | `var(--dsx-space-md)` | Action button row gap. |
+| Title typography | `var(--dsx-typography-headline-medium-*)` | Form title ramp. |
+| Title color | `var(--dsx-color-on-surface)` | Form title fill. |
+| Description color | `var(--dsx-color-on-surface-variant)` | Form description fill. |
+| Description typography | `var(--dsx-typography-body-medium-*)` | Form description ramp. |
+| Message color | `var(--dsx-color-error)` | Error message fill. |
+| Message typography | `var(--dsx-typography-body-small-*)` | Error message ramp. |
+| Label color | `var(--dsx-color-on-surface)` | Form label fill. |
+
+Rules:
+
+- No raw color, spacing, radius, or motion values in the CSS file.
+- Tokens come from `DESIGN.md` via the generated `tokens.css`. New tokens land there first, not in the component CSS.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| All | `none` | n/a | n/a |
+
+Rules:
+
+- `Form` is a static layout component and does not declare motion.
+
+## Accessibility
+
+**Roles:**
+
+- The root renders a `<form>` element. The form's name is supplied by `aria-label`, `aria-labelledby`, or by the nearest `Form.Header > Form.Title` heading region.
+- `Form.Message` carries `role="alert"` and `aria-live="polite"` so screen readers announce the error when it appears.
+
+**Keyboard:**
+
+- `Form` does not own any focusable element. Tab order is determined by the consumer's choice of focusable children. Submit buttons inside `Form.Actions` are normal `<button type="submit">` elements.
+
+**Focus:**
+
+- The form does not paint its own focus ring. Focus rings belong to the wrapped controls (and to the submit button).
+
+**Reduced motion:**
+
+- Not applicable; `Form` does not animate.
+
+**Color and meaning:**
+
+- Error state is communicated by the message text and by `aria-invalid` on the wrapped control. Color is not the only signal.
+
+**Naming:**
+
+- The root is unnamed by default. Provide `aria-label` (e.g. `aria-label="Profile form"`) for screen-reader discoverability.
+- `Form.Label` renders through the `Label` primitive. When used inside a `Form.Item`, the runtime resolves the `htmlFor` from context.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Form` with no extra props. Asserts the root has `data-layout="standard"` and the `dsx-form` class.
+
+**Layout story:**
+
+- Renders `Form` with `layout="standard"` and `layout="compact"`. Asserts the matching `data-layout` attribute is set on the root.
+
+**State story:**
+
+- Renders `Form` with a `FormMessage` carrying a `string` error. Asserts the message renders, has `role="alert"`, and has `aria-live="polite"`.
+- Renders `Form` with a `FormMessage` carrying a `FieldError` object. Asserts `error.message` is rendered.
+
+**Composition story:**
+
+- Renders a full form with `Form.Header > Form.Title`, `Form.Body > Form.Item > Form.Label + Form.Control + Form.Description + Form.Message`, and `Form.Actions` with submit / cancel buttons. Asserts every slot has the right class and the right `data-slot` attribute.
+
+**A11y story:**
+
+- Uses `vitest-axe` against a labelled form layout. Asserts there are no axe violations.
+- Uses `vitest-axe` against a full form with field wiring through `react-hook-form`. Asserts there are no axe violations.
+- Uses `vitest-axe` against a form whose field has been validated and now shows an error. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `layout` | select | `standard` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `react-hook-form`: the source of the form state machine. `Form` accepts the `useForm` return value through the `form` prop and calls `form.handleSubmit(onSubmit)` only when both `form` and `onSubmit` are supplied.
+- `Controller` (from `react-hook-form`): the runtime of `Form.Field`. The DS `FormField` is a thin wrapper that injects `FormFieldContext.Provider` around the controller's `render` output.
+- `Label` (DS primitive): the `Form.Label` slot renders through the `Label` primitive. The runtime imports the primitive directly to pick up the `htmlFor` association.
+- `@radix-ui/react-slot`: enables `asChild` on every subcomponent.
+
+**Used by:**
+
+- `Field` does not import `Form`. `Form` is the orchestration surface; `Field` is the canonical row surface. Apps compose `Form` and `Field` at the row level: `Form.Field` for the controller wiring, then `Form.Item > Form.Label + <Field.Root><Field.Label /><Field.Content><Input /></Field.Content><Field.Description /><Field.Error /></Field.Root> + Form.Message` if a richer row is needed.
+- App-level auth, profile, and settings forms use `Form` directly.
+
+**State boundaries:**
+
+- Owned by `Form`: the form layout (`data-layout`), the row gap, the auto-generated `id` / `errorId` / `descriptionId` for each `Form.Item`, the `onSubmit` wiring through `react-hook-form`, and the `aria-live` announcement for `Form.Message`.
+- Owned by the consumer: the field values, the validation rules, the `react-hook-form` instance, the submit handler, the disabled reason, the layout of the action buttons, and the persistence target.
+
+**Boundary rules:**
+
+- App-owned data: the field schema, the validation predicate, the `useForm` configuration (`mode`, `defaultValues`, `resolver`), and the submission side effects.
+- DS-owned visuals: token bindings, the `dsx-form*` slot classes, the `data-slot` and `data-layout` attributes, the `role="alert"` and `aria-live="polite"` on `Form.Message`, and the `useFormField` error message.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. Keep this section when the component has a published Penpot asset, or when the spec needs to call out a visual decision the package does not encode. Skip the section when the component is utility or layout-primitive; the package code is the only authority.
+
+The package does not yet publish a Penpot asset for Form. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / Form`.
+- **Dimensions**: `480 × auto`.
+- **Layout**: `Flex` (column).
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board: Form>
+  ├── <Frame: header>
+  │     ├── <Text: title>
+  │     └── <Text: description>
+  ├── <Frame: body>
+  │     └── <Frame: item × N>
+  │           ├── <Text: label>
+  │           ├── <Frame: control>
+  │           │     └── <Child control: input | select | textarea | ...>
+  │           ├── <Text: description (optional)>
+  │           └── <Text: message (optional)>
+  └── <Frame: actions>
+        ├── <Button: cancel>
+        └── <Button: submit>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Root (standard) | row-gap | `--dsx-space-lg` | Spacing | `row-gap` |
+| Root (compact) | row-gap | `--dsx-space-md` | Spacing | `row-gap` |
+| Header | column-gap | `--dsx-space-xs` | Spacing | `column-gap` |
+| Body | column-gap | `--dsx-space-md` | Spacing | `column-gap` |
+| Item | column-gap | `--dsx-space-xs` | Spacing | `column-gap` |
+| Control | column-gap | `--dsx-space-xs` | Spacing | `column-gap` |
+| Actions | column-gap | `--dsx-space-md` | Spacing | `column-gap` |
+| Title | typography | `--dsx-typography-headline-medium-*` | Typography | `typography` |
+| Title | fill | `--dsx-color-on-surface` | Color | `fills` |
+| Description | typography | `--dsx-typography-body-medium-*` | Typography | `typography` |
+| Description | fill | `--dsx-color-on-surface-variant` | Color | `fills` |
+| Message | typography | `--dsx-typography-body-small-*` | Typography | `typography` |
+| Message | fill | `--dsx-color-error` | Color | `fills` |
+| Label | fill | `--dsx-color-on-surface` | Color | `fills` |
+
+### State transformations
+
+| State | Message visible | Message fill |
+|---|---|---|
+| `default` | hidden | n/a |
+| `invalid` (with error) | shown | `--dsx-color-error` |
+
+### Variant model
+
+- `layout`: `standard`, `compact`. Default `standard`.
+- Total members: 2.
+
+### 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.
+- [ ] The form's `data-slot` attributes are baked in for QA tooling.

package/dist/docs/grid.md

@@ -0,0 +1,255 @@
+---
+title: Grid
+status: canonical
+category: Foundations
+archetype: layout-primitive
+package_path: packages/d4gger-design-system/src/components/grid/Grid.tsx
+css_path: packages/d4gger-design-system/src/styles/components/grid.css
+props_path: packages/d4gger-design-system/src/layout/layout.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Grid.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
+---
+
+# Grid
+
+> 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 CSS grid layout primitive that turns design-token style props (columns, rows, areas, flow, gap, align/justify content, align/justify items, minItemWidth, plus the inherited `Box` style props) into a CSS grid host. `Grid` extends `Box` and is the canonical primitive for two-dimensional composition in product surfaces.
+
+## Anatomy & slots
+
+**Parent:** `Grid` (alias of `Grid.Root`; flat export, no compound).
+
+**Slots:**
+
+No slots: flat export. `Grid` 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 |
+| `columns` | `ResponsiveValue<number \| string>` | `undefined` | no | CSS `grid-template-columns`. Number values resolve to `repeat(n, minmax(0, 1fr))`. String values are written through (e.g. `7rem`, `200px 1fr`). When `minItemWidth` is set, the runtime uses `repeat(auto-fit, minmax(<minItemWidth>, 1fr))` instead. Resolves `--dsx-grid-columns`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `rows` | `ResponsiveValue<number \| string>` | `undefined` | no | CSS `grid-template-rows`. Number values resolve to `repeat(n, minmax(0, 1fr))`. String values are written through. Resolves `--dsx-grid-rows`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `areas` | `ResponsiveValue<string>` | `undefined` | no | CSS `grid-template-areas`. Resolves `--dsx-grid-areas`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `flow` | `ResponsiveValue<'row' \| 'column' \| 'dense' \| 'row dense' \| 'column dense'>` | `undefined` | no | CSS `grid-auto-flow`. Resolves `--dsx-grid-auto-flow`. | 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) |
+| `align` | `ResponsiveValue<'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'>` | `undefined` | no | CSS `align-items`. `start` resolves to `flex-start`, `end` to `flex-end`. Resolves `--dsx-grid-align`. Serialized into `data-align`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `justify` | `ResponsiveValue<'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'>` | `undefined` | no | CSS `justify-content` (Grid shorthand). `between`/`around`/`evenly` resolve to `space-*`. Resolves `--dsx-grid-justify`. Serialized into `data-justify`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `alignContent` | `ResponsiveValue<'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly' \| 'stretch'>` | `undefined` | no | CSS `align-content`. Resolves `--dsx-grid-align-content`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `justifyItems` | `ResponsiveValue<'start' \| 'center' \| 'end' \| 'stretch'>` | `undefined` | no | CSS `justify-items`. Resolves `--dsx-grid-justify-items`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `justifyContent` | `ResponsiveValue<'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly' \| 'stretch'>` | `undefined` | no | CSS `justify-content`. Resolves `--dsx-grid-justify-content`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `minItemWidth` | `ResponsiveValue<number \| string>` | `undefined` | no | Auto-fit min item width. When set, the runtime writes `repeat(auto-fit, minmax(<value>, 1fr))` for `grid-template-columns` instead of the value from `columns`. | yes (initial, sm, md, lg, xl, 2xl) |
+| `sm` | `Partial<{ align; alignContent; areas; columns; flow; gap; justify; justifyContent; justifyItems; minItemWidth; rows }>` | `undefined` | no | Breakpoint alias for the `sm` breakpoint. Merged into the responsive prop map. | no |
+| `md` | `Partial<{ align; alignContent; areas; columns; flow; gap; justify; justifyContent; justifyItems; minItemWidth; rows }>` | `undefined` | no | Breakpoint alias for the `md` breakpoint. Merged into the responsive prop map. | no |
+| `lg` | `Partial<{ align; alignContent; areas; columns; flow; gap; justify; justifyContent; justifyItems; minItemWidth; rows }>` | `undefined` | no | Breakpoint alias for the `lg` breakpoint. Merged into the responsive prop map. | no |
+| (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 | Grid body. | no |
+| `ref` | `React.Ref<HTMLElement>` | `undefined` | no | Forwarded to the host element. | no |
+
+Rules:
+
+- Every prop above is declared on `Grid` in `Grid.tsx` or in `BoxStyleProps` / `GridStyleProps` 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 `sm`, `md`, and `lg` breakpoint aliases are merged into the responsive prop map. The runtime picks the alias value at that breakpoint when set.
+- The `Responsive` column is `yes` for every grid-specific prop. The Box-inherited props are `yes` where Box marks them responsive.
+- The `data-*` attributes are descriptive only; the visual grid rules come from the `--dsx-grid-*` custom properties consumed by `grid.css`.
+
+## CSS class contract
+
+**Root class:** `dsx-grid`
+
+In addition, Grid writes `dsx-box` so the Box padding/margin/sizing tokens apply.
+
+**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 |
+
+**Slot classes:** none. Grid is a flat export.
+
+The `dsx-grid` selector wires the grid-template custom properties:
+
+```css
+.dsx-grid {
+  display: var(--dsx-box-display, grid);
+  grid-template-columns: var(--dsx-grid-columns, minmax(0, 1fr));
+  grid-template-rows: var(--dsx-grid-rows, none);
+  grid-template-areas: var(--dsx-grid-areas, none);
+  grid-auto-flow: var(--dsx-grid-auto-flow, row);
+  align-content: var(--dsx-grid-align-content, normal);
+  justify-items: var(--dsx-grid-justify-items, legacy);
+  justify-content: var(--dsx-grid-justify-content, normal);
+}
+```
+
+`grid.css` then re-declares the same rule inside `@media (min-width: ...)` blocks for `sm`, `md`, `lg`, `xl`, `2xl` so per-breakpoint variables resolve in cascade order.
+
+**Responsive behavior:**
+
+- The runtime writes `--dsx-grid-columns` (and other `--dsx-grid-*` variables) per breakpoint through `assignResponsiveVars` for the inline-style cascade.
+- The breakpoint alias props `sm`, `md`, `lg` are merged into the responsive prop map and resolve to the matching `--dsx-grid-*-<breakpoint>` custom property.
+
+**Reduced motion:**
+
+- Grid has no motion. No transitions or animations are declared in `grid.css`.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Display | `var(--dsx-box-display, grid)` | Default grid display |
+| Columns | `var(--dsx-grid-columns, minmax(0, 1fr))` | Default 1fr column |
+| Rows | `var(--dsx-grid-rows, none)` | Default `none` |
+| Areas | `var(--dsx-grid-areas, none)` | Default `none` |
+| Auto flow | `var(--dsx-grid-auto-flow, row)` | Default `row` |
+| Align content | `var(--dsx-grid-align-content, normal)` | Default `normal` |
+| Justify items | `var(--dsx-grid-justify-items, legacy)` | Default `legacy` |
+| Justify content | `var(--dsx-grid-justify-content, normal)` | Default `normal` |
+| Gap | `var(--dsx-box-gap, 0)` | Inherited from Box |
+| (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.
+- `align` and `justify` resolve to the same `flex-start` / `flex-end` / `space-*` CSS keywords used by Flex. `start` and `end` are not valid CSS values for `align-items` or `justify-content` and the runtime maps them through.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | `none` | `none` | `none` |
+
+Grid has no motion. The motion section is intentionally empty.
+
+## Accessibility
+
+**Roles:**
+
+- `Grid` has no implicit ARIA role. The host element defaults to `<div>`. Consumers should set `role` explicitly when the surface needs a semantic role (for example, `role="grid"`).
+
+**Keyboard:**
+
+- Grid is not interactive. No keyboard contract beyond the page-level Tab order.
+
+**Focus:**
+
+- Grid has no interactive surface. Focus management is the consumer's responsibility.
+
+**Reduced motion:**
+
+- N/A. Grid has no motion.
+
+**Color and meaning:**
+
+- Grid 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:**
+
+- Grid is not interactive and does not require an accessible name on its own. When Grid wraps an interactive element, the interactive element's accessible name is the source.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Grid columns="3" gap="sm"` with six child squares. Asserts the root class is `dsx-grid`, the host element is a `div`, and the children render.
+
+**Column story:**
+
+- Renders `Grid columns={2}` and `Grid columns={{ initial: 1, sm: 2, md: 3 }}`. Asserts the `dsx-grid` class and the per-breakpoint `--dsx-grid-columns` custom property.
+
+**Areas story:**
+
+- Renders `Grid areas='"head head" "side main"'` and asserts `--dsx-grid-areas` resolves to that value.
+
+**Flow story:**
+
+- Renders `Grid flow="column dense"` and asserts `--dsx-grid-auto-flow` resolves to `column dense`.
+
+**MinItemWidth story:**
+
+- Renders `Grid minItemWidth={200}` and asserts `--dsx-grid-columns` resolves to `repeat(auto-fit, minmax(200px, 1fr))`.
+
+**Breakpoint alias story:**
+
+- Renders `Grid columns={2} sm={{ columns: 3, gap: 'sm' }} md={{ columns: 4, gap: 'lg' }} lg={{ columns: 6, gap: 'xl' }}`. Asserts the merged values resolve in the per-breakpoint custom properties.
+
+**Responsive story:**
+
+- Renders `Grid gap={{ initial: 'md', lg: 'xl' }}` and asserts the `data-gap` attribute serializes as `initial:md;lg:xl` and the per-breakpoint `--dsx-box-gap-*` variables resolve.
+
+**Composition story:**
+
+- Renders `Grid` with mixed `Box` children. Asserts the children keep their own `dsx-box` class and inherit the Grid container's gap.
+
+**State story:**
+
+- No discrete state. The story renders a default Grid with six children.
+
+**Token story:**
+
+- Grid 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 any surfaces come from the theme.
+
+**A11y story:**
+
+- Use `vitest-axe` against the rendered Grid. The default render is a non-semantic `div` with text content; tests assert no violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `columns` | number | `3` |
+| `rows` | number | `undefined` |
+| `gap` | select | `md` |
+| `flow` | select | `row` |
+| `align` | select | `stretch` |
+| `justify` | select | `start` |
+| `alignContent` | select | `normal` |
+| `justifyItems` | select | `legacy` |
+| `minItemWidth` | number | `undefined` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Box`: the host class and inherited style props. Grid writes `dsx-grid` 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`.
+- `layout/layout.props.ts`: `BoxStyleProps`, `GridStyleProps`, `BOX_PROP_DEFS`, `GRID_PROP_DEFS`, `extractLayoutProps`.
+- `styles/components/grid.css`: the `.dsx-grid` host rule plus breakpoint cascade.
+- `styles/responsive/gridTemplateColumns.css`, `gridTemplateRows.css`, `gridTemplateAreas.css`, `gridAutoFlow.css`, `gridArea.css`, `alignContent.css`, `justifyItems.css`: utility classes for grid child placement.
+
+**Used by:**
+
+- `Sidebar`, `Item`, `Card`, `DataTable`, `DataList`, `Pills`, `Marquee`, `Toolbar`, `Tabs`, `Stepper`, `Timeline`, `StatCard`, and other composites: build their grid surfaces on top of `Grid` (directly or through the inherited `dsx-grid` class).
+
+**State boundaries:**
+
+- Owned by `Grid`: the host element selection (`as` / `asChild`), the responsive prop resolution, the generated utility classes, the `dsx-grid` / `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-grid` and `dsx-box` root classes, the responsive utility classes, and the `data-*` attribute contract.
+
+## Penpot build recipe
+
+Grid is a layout primitive. The package code is the only authority. There is no published Penpot build recipe for Grid. A future Penpot board would show a grid container with columns, rows, areas, and gap controls, but the spec intentionally does not duplicate the runtime class contract in a visual recipe.