@d4gger/design-system 2.7.0

package/dist/docs/empty-state.md

@@ -0,0 +1,221 @@
+---
+title: EmptyState
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/emptyState/EmptyState.tsx
+css_path: packages/d4gger-design-system/src/styles/components/empty-state.css
+props_path: packages/d4gger-design-system/src/components/emptyState/emptyState.props.ts
+test_path: packages/d4gger-design-system/src/test/components/EmptyState.test.tsx
+demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
+playground_registry_path: apps/playground/lib/registry/display.tsx
+playground_manifest_path: apps/playground/lib/component-manifest.ts
+depends_on:
+  - Icon
+  - Text
+  - Button
+---
+
+# EmptyState
+
+## 2.6 compatibility status
+
+`EmptyState` is deprecated but not removed. Its normal host delegates to `Result state="empty"` while preserving the `dsx-empty-state` class, size/variant attributes, unavailable/staleness behavior, and public import. New list-state work should use Result and distinguish `empty` from `no-results`.
+
+> 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 empty-region template that pairs an optional illustration with a headline, a description, and an optional recovery action. Use EmptyState whenever a list, table, page, or section has no content to show; the recovery action is required for the canonical pattern, and the component still renders when the action is omitted. The contract goal is to give every empty region a path forward for the user.
+
+The `variant="unavailable"` + `staleness` pair covers a semantically different case: the feature works, but its data source is currently down (a timeout, an outage) — not "you have no devices". Using the default (`"default"`) variant for a degraded-source state would mislead the user into thinking the underlying resource doesn't exist. `staleness` is the freshness stamp for showing cached-but-stale values alongside that message (e.g. "Updated 5 minutes ago").
+
+## Anatomy & slots
+
+**Parent:** `EmptyState` (no compound; flat export).
+
+**Slots:**
+
+No slots: flat export. The component renders a `<section>` (or `Slot` host) with three internal regions:
+
+| Region | Element | Renders | Notes |
+|---|---|---|---|
+| `EmptyState` (root) | `<section>` (or `Slot` host) | Root + class | Renders as a `<section>` by default. Writes `dsx-empty-state` and `data-size`. |
+| Illustration (internal) | `<div class="dsx-empty-state__illustration">` | Internal layout | Wraps the consumer-supplied `illustration` node. Omitted when `illustration` is not provided. |
+| Header (internal) | `<div class="dsx-empty-state__header">` | Internal layout | Wraps the title (`<h2>`) and the optional description (`<p>`). |
+| Action (internal) | `<div class="dsx-empty-state__action">` | Internal layout | Wraps the consumer-supplied `action` node. Omitted when `action` is not provided. |
+
+`title` is a required prop and always renders. `illustration`, `description`, and `action` are optional props. The default host is `<section>`; the component supports `asChild` so the consumer can swap in a `<div>` or other element.
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `title` | `ReactNode` | — | yes | Headline text. Renders as `<h2>` inside the header region. | no |
+| `description` | `ReactNode` | `undefined` | no | Supporting text. Renders as `<p>` inside the header region, below the title. | no |
+| `illustration` | `ReactNode` | `undefined` | no | Visual content rendered above the title. Typically an `Icon` or a custom illustration. | no |
+| `action` | `ReactNode` | `undefined` | no | Recovery action. Typically a `Button` or a group of `Button`s. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Padding scale; writes `data-size`. | no |
+| `variant` | `'default' \| 'unavailable'` | `'default'` | no | `'unavailable'` tints the illustration and title to distinguish "source is degraded" from "genuinely empty"; writes `data-variant`. | no |
+| `staleness` | `ReactNode` | `undefined` | no | Freshness stamp rendered below the description (e.g. "Updated 5 minutes ago"). Renders as a `<p class="dsx-empty-state__staleness">` when provided; omitted otherwise. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot`; consumer supplies the host element. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to `dsx-empty-state`. | no |
+| `children` | `ReactNode` | `undefined` | no | When `asChild` is `true`, the consumer's children are slotted through `Slottable` and rendered after the illustration / header / action regions. |
+
+Rules:
+
+- `title` is destructured in the component and rendered as an `<h2>`; the `title` HTML attribute is not forwarded (the props type omits it).
+- The component now emits `data-size` and `data-variant`. It still does not emit `data-radius`, `data-accent-color`, or `data-high-contrast`.
+- The component does not own the `asChild` host via `Slot` semantics for the default `<section>` path; the `asChild` path swaps the host for the consumer's element and renders the children through `Slottable`.
+
+## CSS class contract
+
+**Root class:** `dsx-empty-state`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-empty-state[data-size='sm'|'lg']` (padding scale) | `empty-state.css` |
+| `data-variant` | `default`, `unavailable` | `.dsx-empty-state[data-variant='unavailable']` (tints illustration + title) | `empty-state.css` |
+
+**Internal element classes:**
+
+| Element | Class | CSS file |
+|---|---|---|
+| `EmptyState` (root) | `dsx-empty-state` | `empty-state.css` |
+| Illustration wrapper | `dsx-empty-state__illustration` | `empty-state.css` |
+| Header wrapper | `dsx-empty-state__header` | `empty-state.css` |
+| Title (`<h2>`) | `dsx-empty-state__title` | `empty-state.css` |
+| Description (`<p>`) | `dsx-empty-state__description` | `empty-state.css` |
+| Staleness stamp (`<p>`) | `dsx-empty-state__staleness` | `empty-state.css` |
+| Action wrapper | `dsx-empty-state__action` | `empty-state.css` |
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. `size` is single-value only.
+
+**Reduced motion:**
+
+- The component is static. No motion is applied.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token (or a `var(--dsx-*)` token whose value is theme-defined).
+
+| Property | Token | Role |
+|---|---|---|
+| Root display | `flex` (column, center) | Layout for the three internal regions |
+| Root gap | `var(--dsx-space-lg)` | Space between illustration, header, and action |
+| Root width | `min(100%, var(--dsx-empty-state-max-width))` | Constrain width while remaining responsive |
+| Root min-height | `var(--dsx-empty-state-min-height)` | Minimum surface height |
+| Root padding | `var(--dsx-space-xl)` | Internal gutter |
+| Root text-align | `center` | Centered text alignment |
+| Illustration dimensions | `var(--dsx-size-4xl)` | Illustration container size |
+| Illustration color | `var(--dsx-color-outline-variant)` | Illustration icon color |
+| Header display | `flex` (column) | Title + description layout |
+| Header gap | `var(--dsx-space-sm)` | Space between title and description |
+| Title type ramp | `var(--dsx-typography-headline-large-*)` | Headline text scale |
+| Title color | `var(--dsx-color-on-surface)` | Headline text color |
+| Description type ramp | `var(--dsx-typography-body-medium-*)` | Description text scale |
+| Description color | `var(--dsx-color-on-surface-variant)` | Description text color |
+| Staleness type ramp | `var(--dsx-typography-label-medium-*)` | Freshness stamp text scale, smaller/quieter than the description |
+| Staleness color | `var(--dsx-color-on-surface-variant)` | Same muted tone as the description |
+| Illustration color (`unavailable`) | `var(--dsx-color-tertiary)` | Caution tone — same token `Status.degraded` uses — instead of the neutral `outline-variant` the default treatment uses |
+| Title color (`unavailable`) | `var(--dsx-color-tertiary)` | Signals "source is degraded", not "genuinely empty" |
+| Action display | `inline-flex` | Action container layout |
+
+The `empty-state.css` file imports `../../_internal/baseCard.css` so EmptyState inherits the card surface (background, border, shadow) by default. The `var(--dsx-color-surface-raised)`, `var(--dsx-shadow-1)`, and `var(--dsx-color-outline)` tokens are resolved through that import.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| (none) | none | none | n/a |
+
+The component is static.
+
+## Accessibility
+
+**Roles:**
+
+- The root renders as a `<section>` by default. The `<h2>` title provides the heading for the region. The component does not add a `role` or `aria-label`; consumers that need a labelled region should add `aria-labelledby` pointing to the title or `aria-label`.
+
+**Keyboard:**
+
+- The root is not interactive. Actionable content inside the `action` prop handles its own keyboard interactions.
+
+**Focus:**
+
+- Focus handling is owned by the consumer's action controls.
+
+**Reduced motion:**
+
+- No motion is applied.
+
+**Color and meaning:**
+
+- The illustration is decorative (`color: var(--dsx-color-outline-variant)`). The title and description carry the meaning. Consumers should not rely on the illustration alone to communicate the empty state.
+
+**Naming:**
+
+- `title` is the accessible name of the section. The description provides supplementary context. The action's accessible name is the consumer's responsibility.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders an `EmptyState` with a title, description, and action. Asserts the root class is `dsx-empty-state`, the host is a `<section>`, the title is an `<h2>`, and the action is rendered.
+
+**Composition story:**
+
+- Renders an `EmptyState` with an `illustration` slot populated. Asserts the `dsx-empty-state__illustration` wrapper is present.
+- Renders an `EmptyState` with no `description`. Asserts the description wrapper is omitted.
+- Renders an `EmptyState` with no `action`. Asserts the action wrapper is omitted.
+
+**Size story:**
+
+- Renders three `EmptyState` instances with `size="sm"`, `size="md"`, and `size="lg"`. Asserts the matching `data-size` attribute.
+
+**State story:**
+
+- Renders an `EmptyState` with `asChild` and a `<div>` host. Asserts the host element is the consumer's element and the `dsx-empty-state` class is applied.
+- Renders an `EmptyState` with `variant="unavailable"` and a `staleness` stamp (e.g. "Updated 5 minutes ago"). Asserts `data-variant="unavailable"` and the stamp text renders.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. EmptyState does not track `data-accent-color`; the story asserts the surface is unchanged.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default story. Asserts no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `size` | select | `md` |
+| `variant` | select | `default` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Icon`, `Text`, `Button`: the typical content of the illustration, description, and action slots. EmptyState does not import any of these; the consumer supplies the nodes.
+- `@radix-ui/react-slot`: enables `asChild` on the root.
+- `Card` is not composed; the base card surface is inherited through the CSS import (`@import '../../_internal/baseCard.css'`) so the EmptyState background, border, and shadow resolve through the same tokens as `Card`.
+
+**Used by:**
+
+- `DataTable`: passes an `emptyState` prop to render the empty state inside the table region.
+- App-level empty-region templates (inbox, search results, dashboards, settings).
+
+**State boundaries:**
+
+- Owned by EmptyState: the `data-size` attribute, the internal layout, the `<h2>` and `<p>` host elements, and the `dsx-empty-state__*` classes.
+- Owned by the consumer: the title, description, illustration, action, and the surrounding region.
+
+**Boundary rules:**
+
+- App-owned data: the empty-state message, the recovery action, the analytics events, and the decision of when a source is genuinely empty vs. degraded/unavailable (i.e. which `variant` to pass), plus the actual staleness timestamp/text.
+- DS-owned visuals: token bindings, internal layout, typography ramps, the inherited card surface, and the `unavailable` variant's caution-tone treatment.

package/dist/docs/field.md

@@ -0,0 +1,301 @@
+---
+title: Field
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/field/Field.tsx
+css_path: packages/d4gger-design-system/src/styles/components/field.css
+props_path: packages/d4gger-design-system/src/components/field/field.props.ts
+test_path: packages/d4gger-design-system/src/test/components/Field.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:
+  - Label (the `Field.Label` slot renders through the `Label` primitive for accessible `<label htmlFor>` association)
+  - Text (the `Field.Description`, `Field.Error`, and `Field.Title` slots render through the `Text` primitive at the `body-medium` ramp; the runtime does not import `Text` as a value, it composes through it for the typography ramp only — see Anomalies)
+  - "@radix-ui/react-slot (asChild on every subcomponent)"
+---
+
+# Field
+
+> 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 default form-control wrapper for the design repo. Pairs a label, a control region, an optional description, and an optional error message into a single root with consistent state-aware styling. Use `Field` whenever a form row needs label association, description, or error wiring; reach for `TextField` only for the convenience "label + input + helper + error" bundle.
+
+## Anatomy & slots
+
+**Parent:** `Field` (alias of `Field.Root`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `Field.Root` | `<div>` (or a slotted host) | `dsx-field`, plus `data-size`, `data-state`, `data-orientation`, `data-invalid`, `data-disabled` | Owns the row layout. Provides `FieldContext` so children can read disabled / invalid / state. |
+| `Field.Label` | `<label>` through the `Label` primitive | `dsx-field__label`, plus `data-state`, `data-invalid`, `data-disabled` | Accessible label for the wrapped control. Honors `htmlFor` from the consumer. |
+| `Field.Title` | `<div>` (or slotted host) | `dsx-field__title`, plus `data-state` | Optional heading region inside the row. |
+| `Field.Content` | `<div>` (or slotted host) | `dsx-field__content`, plus `data-state` | The control region. Consumers typically place the input, select, or other control here. |
+| `Field.Description` | `<p>` (or slotted host) | `dsx-field__description`, plus `data-state` | Helper text below the control. |
+| `Field.Error` | `<p>` (or slotted host) | `dsx-field__error`, plus `data-state` and `role="alert"` | Error message. The CSS swaps the label and the error color to `var(--dsx-color-error)` when `data-state="invalid"`. |
+| `Field.Set` | `<fieldset>` (or slotted host) | `dsx-fieldset`, plus `data-state` | A semantic fieldset wrapper for grouped controls. |
+| `Field.Legend` | `<legend>` (or slotted host) | `dsx-fieldset__legend`, plus `data-state` | The legend for a `Field.Set`. |
+| `Field.Group` | `<div>` (or slotted host) | `dsx-field-group`, plus `data-state`. Defaults to `role="group"`; the consumer can override with an explicit `role` prop. | A `role="group"` region for related controls (e.g. radio group, checkbox group). |
+
+## Props contract
+
+**Root props (`Field` / `Field.Root`):**
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. | no |
+| `invalid` | `boolean` | `false` | no | Marks the row as invalid. Writes `data-invalid="true"`, derives `data-state="invalid"`, and adds the `dsx-field-invalid` class. | no |
+| `disabled` | `boolean` | `false` | no | Marks the row as disabled. Writes `data-disabled="true"`, derives `data-state="disabled"`, and adds the `dsx-field-disabled` class. | no |
+| `orientation` | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | no | Row layout. Writes `data-orientation` and the `dsx-field-orientation` class. The CSS uses the attribute to swap to a 2-column grid for `horizontal` and a responsive auto-fit grid for `responsive`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Size of the row. Writes `data-size`. The CSS does not currently declare per-size rules; the attribute is the contract hook. | no |
+| (HTML div props) | n/a | n/a | no | All standard `<div>` attributes are forwarded. | no |
+
+**Slot-level props (`Field.Label`, `Field.Title`, `Field.Content`, `Field.Description`, `Field.Error`, `Field.Set`, `Field.Legend`, `Field.Group`):**
+
+- `asChild` is the only prop in the slot-level prop def. The rest comes from the host element (`<label>`, `<div>`, `<p>`, `<fieldset>`, `<legend>`).
+- `Field.Label` accepts the standard `Label` primitive props (including `htmlFor`).
+- `Field.Group` accepts a `role` prop; the default is `role="group"`.
+
+`FieldState` is exported as `'default' | 'invalid' | 'disabled'`. `FieldOrientation` is exported as `'vertical' | 'horizontal' | 'responsive'`. `getFieldState` derives the resolved state from `invalid` and `disabled`: `disabled` wins over `invalid`.
+
+Rules:
+
+- `invalid`, `disabled`, `orientation`, and `size` are wired through `extractProps`; the rest of the host props are forwarded as-is.
+- The `FieldContext` provider exposes `disabled`, `invalid`, and the derived `state` to every descendant. Subcomponents merge that state into their own `data-state` attribute.
+- `Field.Error` is the only slot that hard-codes a non-empty `role`. The role is `role="alert"`, so screen readers announce the error when it appears.
+
+## CSS class contract
+
+**Root class:** `dsx-field` (and `dsx-fieldset` for `Field.Set`).
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | (attribute written on root; no per-size CSS rule today) | `field.css` |
+| `data-orientation` | `vertical`, `horizontal`, `responsive` | `.dsx-field[data-orientation='horizontal']` 2-column grid; `.dsx-field[data-orientation='responsive']` auto-fit grid | `field.css` |
+| `data-state` | `default`, `invalid`, `disabled` | `.dsx-field[data-state='disabled']` opacity; `.dsx-fieldset[data-state='invalid']` error border | `field.css` |
+| `data-invalid` | `true` | `.dsx-field-invalid .dsx-field__label` error color | `field.css` |
+| `data-disabled` | `true` | `.dsx-field-disabled` opacity | `field.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `Field.Label` | `dsx-field__label` | `field.css` |
+| `Field.Title` | `dsx-field__title` | `field.css` |
+| `Field.Content` | `dsx-field__content` | `field.css` |
+| `Field.Description` | `dsx-field__description` | `field.css` |
+| `Field.Error` | `dsx-field__error` | `field.css` |
+| `Field.Set` | `dsx-fieldset` | `field.css` |
+| `Field.Legend` | `dsx-fieldset__legend` | `field.css` |
+| `Field.Group` | `dsx-field-group` | `field.css` |
+
+**Responsive behavior:**
+
+- The `responsive` orientation uses `grid-template-columns: repeat(auto-fit, minmax(var(--dsx-size-popover-min-width), 1fr))`. The CSS does not write `@media` rules directly. None of the prop defs are `responsive: true`.
+
+**Reduced motion:**
+
+- The component does not animate. The CSS does not declare transitions for `Field` regions; any motion comes from child controls (e.g. `Input`).
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Row gap | `var(--dsx-space-xs)` | Default row gap. |
+| Row min-width | `0` | Allows the grid to shrink. |
+| Horizontal label column | `minmax(var(--dsx-size-field-label-min), var(--dsx-size-field-label-max))` | Label column size for `horizontal` orientation. |
+| Horizontal row column gap | `var(--dsx-space-md)` | Row gap for `horizontal` orientation. |
+| Responsive column min | `var(--dsx-size-popover-min-width)` | Min column width for `responsive` orientation. |
+| Label color | `var(--dsx-color-on-surface)` | Default label. |
+| Label color (invalid) | `var(--dsx-color-error)` | Label color when the row is invalid. |
+| Description color | `var(--dsx-color-on-surface-variant)` | Helper text. |
+| Error color | `var(--dsx-color-error)` | Error message. |
+| Error typography | `var(--dsx-typography-body-medium-*)` | Error message ramp. |
+| Title typography | `var(--dsx-typography-headline-medium-*)` | Optional title ramp. |
+| Disabled opacity | `var(--dsx-opacity-disabled)` | Disabled rows. |
+| Fieldset border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline-variant)` | Fieldset edge. |
+| Fieldset radius | `var(--dsx-rounded-lg)` | Fieldset corner roundness. |
+| Fieldset padding | `var(--dsx-space-md)` | Fieldset inner gutter. |
+| Fieldset border (invalid) | `var(--dsx-color-error)` | Fieldset edge when invalid. |
+| Legend padding | `0 var(--dsx-space-xs)` | Legend inline gutter. |
+| Group gap | `var(--dsx-space-xs)` | Group inner gap. |
+
+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:
+
+- `Field` is a static layout component and does not declare motion. The CSS file does not define transitions on any `Field` class.
+
+## Accessibility
+
+**Roles:**
+
+- The default root is a plain `<div>` with no implicit role. Consumers that need a region role can wrap the root or pass `asChild` to a `<section>`.
+- `Field.Set` is a `<fieldset>`. `Field.Legend` is a `<legend>`. `Field.Group` defaults to `role="group"`.
+- `Field.Error` carries `role="alert"`.
+
+**Keyboard:**
+
+- `Field` does not own any focusable element. Tab order is determined by the consumer's choice of focusable children. The label's `<label htmlFor>` association handles focus routing when the consumer provides an `id` on the control.
+
+**Focus:**
+
+- `Field` does not paint a focus ring. Focus rings belong to the wrapped control (`Input`, `Select`, `TextArea`, etc.).
+
+**Reduced motion:**
+
+- Not applicable; `Field` does not animate.
+
+**Color and meaning:**
+
+- Invalid state is communicated by the `data-state="invalid"` attribute, the `data-invalid="true"` attribute, the `dsx-field-invalid` class, and the `Field.Error` slot. The label color also shifts to the error color, so the row does not rely on color alone.
+
+**Naming:**
+
+- `Field.Label` renders through the `Label` primitive with the standard `<label htmlFor>` association. Provide the matching `id` on the wrapped control so screen readers read both the label and the control together.
+
+## Playground demo spec
+
+**Default story:**
+
+- Renders `Field` with a label, an input, and a description. Asserts the root class is `dsx-field`, the label is bound to the input via `htmlFor`, and the description text is rendered.
+
+**Orientation story:**
+
+- Renders `Field` with `orientation="vertical"`, `orientation="horizontal"`, and `orientation="responsive"`. Asserts the matching `data-orientation` attribute is set on the root.
+
+**State story:**
+
+- Renders `Field` with `invalid` and an `Field.Error`. Asserts the root has `data-invalid="true"`, `data-state="invalid"`, and the error slot has `role="alert"`.
+- Renders `Field` with `disabled`. Asserts the root has `data-disabled="true"`, `data-state="disabled"`, and the `dsx-field-disabled` class.
+
+**Composition story:**
+
+- Renders a `Field.Set` with a `Field.Legend` and two `Field.Root` rows. Asserts each slot renders the right class and the legend is associated with the fieldset.
+- Renders a `Field.Group` with three child controls. Asserts the group has `role="group"` and the `dsx-field-group` class.
+
+**Token story:**
+
+- Renders `Field` inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`. The component does not currently paint accent-color rules, so the story asserts the row still renders without an accent-color override and the description text uses `var(--dsx-color-on-surface-variant)`.
+
+**A11y story:**
+
+- Uses `vitest-axe` against a labelled row with a description. Asserts there are no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `orientation` | select | `vertical` |
+| `size` | select | `md` |
+| `invalid` | boolean | `false` |
+| `disabled` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Label` (DS primitive): the `Field.Label` slot renders through the `Label` primitive. The runtime imports the primitive directly to pick up the `htmlFor` association and the disabled handling.
+- `Text` (DS primitive, ramp only): the typography ramps used by `Field.Description`, `Field.Error`, and `Field.Title` match the `body-medium` and `headline-medium` ramps the `Text` primitive exposes. The runtime does not import `Text`; the CSS file consumes the same `--dsx-typography-*` tokens.
+- `@radix-ui/react-slot`: enables `asChild` on every subcomponent.
+
+**Used by:**
+
+- `Form` (per the roster's `Composed From` column) uses `Field` as its label, description, and error carrier. The `Form` runtime does not import `Field` directly; it composes the same primitives (`Label`, `Text`).
+- Every DS form-row spec (e.g. `Select`, `Combobox`, `InputOtp`) is intended to live inside `Field.Root` for label, description, and error wiring.
+
+**State boundaries:**
+
+- Owned by Field: the `FieldContext` (disabled / invalid / state), the `data-*` attribute contract on the root, the row gap, and the orientation grid.
+- Owned by the consumer: the wrapped control, the label's `htmlFor` binding, the description content, the error content, and the form submission.
+
+**Boundary rules:**
+
+- App-owned data: the control value, the persistence target, the disabled reason, the validation predicate, and the error message text.
+- DS-owned visuals: token bindings, the `dsx-field*` slot classes, the `data-*` attribute contract, and the `role="alert"` on `Field.Error`.
+
+**Anomalies** (open items that this spec flags for the next promotion):
+
+1. **Horizontal orientation layout collapsed; label claimed 75% of the row width, leaving the content a sliver.** The root grid for `orientation="horizontal"` uses `grid-template-columns: minmax(var(--dsx-size-field-label-min), var(--dsx-size-field-label-max)) 1fr`. In CSS Grid, `minmax()` non-flexible tracks (those without `fr` in the min) are sized up to their max before the `1fr` content column receives whatever remains. The token `--dsx-size-field-label-max` was `280px`, and at realistic form widths (~360px, the playground fixture's own container width), the label column would claim the full 280px, leaving the content column only ~64px. This visible symptom was "layout collapse": an Input inside the content column displayed truncated placeholder text ("Hori" instead of "Horizontal") due to insufficient space. FIXED 2026-07-03: lowered `--dsx-size-field-label-max` from `280px` to `160px`. The reduced label-max still comfortably fits normal label text ("Email address", "Password") while leaving the content column usable at common field widths. The token `--dsx-size-field-label-min` (`80px`) was not changed.
+
+2. **Canonical horizontal Field width is 420px; playground fixture is 360px.** The Penpot recipe for `Field` specifies the canonical horizontal width as `420 × auto`, which is wider than the shared playground container (360px). The label-max fix (#1 above) makes the layout degrade gracefully to widths narrower than the canonical 420px, rather than depending on callers to supply a sufficiently wide container. Below the canonical width, the label column shrinks to `minmax(80px, 160px)`, and the content column still receives whatever remains, allowing the layout to adapt to constrained spaces (e.g., mobile, sidebar regions).
+
+## 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 Field. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / Field`.
+- **Dimensions**: `360 × auto` (vertical), `420 × auto` (horizontal).
+- **Layout**: `Grid` (1 column for vertical, 2 columns for horizontal, auto-fit for responsive).
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board: Field>
+  ├── <Text: label>
+  ├── <Frame: content>
+  │     └── <Child control: input | select | textarea | ...>
+  ├── <Text: description (optional)>
+  └── <Text: error (optional, data-state='invalid')>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Row gap | spacing | `--dsx-space-xs` | Spacing | `row-gap` |
+| Label | text | `--dsx-color-on-surface` | Color | `fills` |
+| Label (invalid) | text | `--dsx-color-error` | Color | `fills` (state) |
+| Description | text | `--dsx-color-on-surface-variant` | Color | `fills` |
+| Error | text | `--dsx-color-error` | Color | `fills` |
+| Error | typography | `--dsx-typography-body-medium-*` | Typography | `typography` |
+| Title | typography | `--dsx-typography-headline-medium-*` | Typography | `typography` |
+| Fieldset | stroke | `--dsx-color-outline-variant` | Color | `strokes` |
+| Fieldset | radius | `--dsx-rounded-lg` | Radius | `radius` |
+| Fieldset (invalid) | stroke | `--dsx-color-error` | Color | `strokes` (state) |
+
+### State transformations
+
+| State | Label fill | Error visible | Fieldset stroke |
+|---|---|---|---|
+| `default` | `--dsx-color-on-surface` | hidden | `--dsx-color-outline-variant` |
+| `invalid` | `--dsx-color-error` | shown | `--dsx-color-error` |
+| `disabled` | `--dsx-color-on-surface` (opacity `--dsx-opacity-disabled`) | hidden | `--dsx-color-outline-variant` |
+
+### Variant model
+
+- `orientation`: `vertical`, `horizontal`, `responsive`. Default `vertical`.
+- `size`: `sm`, `md`, `lg`. Default `md`.
+- `invalid`: `true`, `false`. Default `false`.
+- `disabled`: `true`, `false`. Default `false`.
+- Total members: 3 × 3 × 2 × 2 = 36.
+
+### 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.
+- [ ] `Field.Error` is hidden by default and only appears in the `invalid` state.