@d4gger/design-system 2.7.0

package/dist/docs/text-field.md

@@ -0,0 +1,394 @@
+---
+title: TextField
+status: canonical
+category: Components
+archetype: composite
+package_path: packages/d4gger-design-system/src/components/textField/TextField.tsx
+css_path: packages/d4gger-design-system/src/styles/components/text-field.css
+props_path: packages/d4gger-design-system/src/components/textField/textField.props.ts
+test_path: packages/d4gger-design-system/src/test/components/TextField.test.tsx
+demo_path: apps/playground/app/page.tsx
+depends_on:
+  - Field (the canonical form-row wrapper; `TextField` is a convenience composition that bundles label, control, helper, and error into one slot, and is intended to live inside a `Field.Root` for app-level form rows)
+  - Input (the inner input reuses the body-medium typography and the disabled / autofill contract from `baseInput.css`; the runtime does not import the `Input` component)
+  - Label (the label slot renders through the `Label` primitive for accessible `<label htmlFor>` association)
+  - Text (the helper and error text slots render through the `Text` primitive at the `label-small` ramp)
+  - "_internal/baseInput.css (shared shell, border, hover, focus, disabled, and autofill contract)"
+  - "@radix-ui/react-slot"
+---
+
+# TextField
+
+> 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 composite label-plus-input-plus-error field for fast form rows. The component bundles a label, an inner input, an optional inline slot region, an optional error text, and an optional helper text into one element, so simple rows do not have to compose `Field` + `Input` by hand. For richer form rows with grouped fields, custom descriptions, or validation orchestration, use `Field` directly.
+
+## Anatomy & slots
+
+**Parent:** `TextField` (root, attached to compound subcomponents via `Object.assign`).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `TextField.Root` | `<div>` (or slotted host) | `dsx-text-field`, `dsx-text-field--{density}`, `dsx-text-field--{variant}`, `dsx-text-field--invalid` (when invalid) + `data-accent-color`, `data-radius`, `data-size`, `data-variant` | Owns the field-row layout, the label, the shell, and the helper / error text. |
+| `TextField.Input` | `<input>` | `dsx-text-field__input` | The actual text entry. Inherits `id` and `aria-invalid` from the root via context. |
+| `TextField.Slot` | `<div>` | `dsx-text-field__slot` | Inline region for icons, badges, or short text. The slot is rendered next to the input inside the shell and is the only way to add non-text children to the field row. |
+
+The roster's `Parent / Slots` column currently lists `-` (flat export) for `TextField`. The runtime in `TextField.tsx` ships a compound surface (`TextField.Input`, `TextField.Slot`); the test file in `src/test/components/TextField.test.tsx` exercises both. The roster also lists `Field` and `Input` as the components `TextField` is "Composed From", but the runtime does not import `Field` or `Input`; the label uses the `Label` primitive and the helper / error use the `Text` primitive. See the Anomalies section for the gap.
+
+**Internal layout (not slots):**
+
+| Element | Class | Notes |
+|---|---|---|
+| Root (`<div>`) | `dsx-text-field` (+ density / variant / invalid modifiers) | Hosts the column layout. |
+| Label (`<label>`) | `dsx-text-field__label` | Renders through the `Label` primitive; bound to the input's `id` via `htmlFor`. |
+| Shell (`<div>`) | `dsx-text-field__shell` | The token-aligned input border, background, and focus contract, reused from `baseInput.css`. |
+| Error (`<span>`) | `dsx-text-field__error` | Renders through the `Text` primitive at `label-small` with the error color. |
+| Helper (`<span>`) | `dsx-text-field__helper` | Renders through the `Text` primitive at `label-small` with the muted tone. |
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `label` | `string` | `undefined` | no | Optional label string. When set, renders a `<label>` bound to the input's `id` via `htmlFor`. | no |
+| `helperText` | `string` | `undefined` | no | Optional helper text. Renders only when not invalid. | no |
+| `errorText` | `string` | `undefined` | no | Optional error message. Renders only when `invalid` is `true`. | no |
+| `id` | `string` | `undefined` | no | The id used for the label `htmlFor` and the input `id`. | no |
+| `invalid` | `boolean` | `false` | no | Marks the field as invalid. Adds the `dsx-text-field--invalid` modifier class, sets `aria-invalid="true"` on the input, and switches the error / helper visibility. | no |
+| `density` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control height and inner padding. Writes `data-size="sm"\|"md"\|"lg"` on the root and adds the `dsx-text-field--{value}` modifier class. | no |
+| `variant` | `'classic' \| 'surface' \| 'soft'` | `'surface'` | no | Shell surface treatment. `'surface'` is the bordered resting state; `'classic'` adds an elevation shadow; `'soft'` removes the border and uses the raised surface. | no |
+| `color` | `string` (any `data-accent-color` value) | `undefined` | no | Accent color override. Writes `data-accent-color` on the root. The prop def is `type: 'enum | string'` with an empty `values` array, so any string the consumer passes is accepted; the CSS does not currently declare `[data-accent-color='...']` rules. | no |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner radius override. Writes `data-radius`. The CSS does not currently declare matching `[data-radius='...']` rules. | no |
+| `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. The label, shell, error, and helper stay on their default elements. | no |
+| `className` | `string` | `undefined` | no | Extra classes appended to the root. | no |
+| `style` | `React.CSSProperties` | `undefined` | no | Inline style forwarded to the root. | no |
+| `children` | `React.ReactNode` | `undefined` | no | Slot composition. Must include `TextField.Input`; `TextField.Slot` is optional. The component does not render anything else from `children`. | no |
+
+`TextField.Input` props:
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| (extends `React.ComponentPropsWithoutRef<'input'>`) | n/a | n/a | no | Standard input attributes. `id` and `aria-invalid` are inherited from the root via context. | no |
+
+`TextField.Slot` props:
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| (extends `React.ComponentPropsWithoutRef<'div'>`) | n/a | n/a | no | Standard div attributes. The slot renders an inline-flex region next to the input. | no |
+
+Rules that apply to this row:
+
+- `TextFieldRootProps` extends `Omit<React.ComponentPropsWithoutRef<'div'>, 'color'>` because `color` is redefined by the prop bag.
+- `density` is the prop name on the bag, but the runtime writes `data-size`. The modifier class `dsx-text-field--{value}` is added in the TSX. (Same naming split as `PasswordInput`.)
+- `color` is typed as `enum | string` with an empty `values` array, so the runtime accepts any string. The test file in `src/test/components/TextField.test.tsx` uses `color="blue"` to assert the `data-accent-color` attribute is forwarded.
+- The `id` and `invalid` props are pushed into a React context (`TextFieldContext`) and consumed by `TextField.Input`. Consumers that supply `id` on `TextField.Input` directly will conflict with the context.
+- The label renders through the `Label` primitive with `htmlFor={id}`. If `id` is not supplied, the label is still rendered but the `htmlFor` association is missing; consumers should always supply `id` when using a label.
+- The `Text` primitive is used for both the error and helper slots, with `variant="label-small"`. The error uses the default tone; the helper uses `tone="muted"`.
+
+## CSS class contract
+
+**Root class:** `dsx-text-field`
+
+**Modifier classes** (driven by the TSX's class merging and `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `dsx-text-field--sm`, `dsx-text-field--md`, `dsx-text-field--lg` (applied in TSX, not via `extractProps`); no CSS rule for `[data-size='...']` | `text-field.css` |
+| `data-variant` | `classic`, `surface`, `soft` | `dsx-text-field--classic`, `dsx-text-field--surface`, `dsx-text-field--soft` (applied in TSX) plus `.dsx-text-field[data-variant='soft']` shell rules | `text-field.css` |
+| `data-radius` | `none`, `sm`, `md`, `lg`, `full` | (no CSS rule declared today; reserved) | `text-field.css` |
+| `data-accent-color` | any string | (no CSS rule declared today; the attribute is mirrored for theme-aware descendant styling) | `text-field.css` |
+
+**Visual modifier classes (root level):**
+
+| Class | Role | CSS file |
+|---|---|---|
+| `dsx-text-field--sm` | Density override (sm). | `text-field.css` |
+| `dsx-text-field--md` | Density override (md, default). | `text-field.css` |
+| `dsx-text-field--lg` | Density override (lg). | `text-field.css` |
+| `dsx-text-field--surface` | Variant override (surface, default). | `text-field.css` |
+| `dsx-text-field--classic` | Variant override (classic) — adds `var(--dsx-effect-shadow-1)` to the shell. | `text-field.css` |
+| `dsx-text-field--soft` | Variant override (soft) — uses `var(--dsx-color-surface-raised)` and a transparent border. | `text-field.css` |
+| `dsx-text-field--invalid` | Adds the error border to the shell via the `:where(.dsx-text-field--invalid) .dsx-text-field__shell` rule in `baseInput.css`. | `_internal/baseInput.css` |
+
+**Slot classes:**
+
+| Slot | Class | CSS file |
+|---|---|---|
+| `TextField.Root` | `dsx-text-field` (+ modifiers) | `text-field.css` |
+| `TextField.Input` | `dsx-text-field__input` | `text-field.css` |
+| `TextField.Slot` | `dsx-text-field__slot` | `text-field.css` |
+| Label | `dsx-text-field__label` | `text-field.css` |
+| Shell | `dsx-text-field__shell` | `text-field.css` (+ shared rules in `_internal/baseInput.css`) |
+| Error text | `dsx-text-field__error` | `text-field.css` |
+| Helper text | `dsx-text-field__helper` | `text-field.css` |
+
+**Data slots:** the runtime does not write `data-slot` attributes on `TextField`. (See the Anomalies section — sibling components like `PasswordInput` and `Editable` do write `data-slot` attributes; `TextField` is inconsistent.)
+
+**Responsive behavior:**
+
+- The component does not write `@media` rules. None of its prop defs are `responsive: true`. Density and radius are single-value only.
+- The component's CSS file is breakpoint-agnostic.
+
+**Reduced motion:**
+
+- The shell transitions `border-color` and `box-shadow` against `var(--dsx-motion-duration-fast)` and `var(--dsx-motion-easing-standard)`. The runtime does not import `usePrefersReducedMotion`; rely on the global stylesheet to honor the media query.
+
+## Token mapping
+
+Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| Root gap | `var(--dsx-space-xs)` | Vertical rhythm between label, shell, and helper / error. |
+| Shell border | `var(--dsx-border-width-sm)` + `var(--dsx-color-outline)` | Default edge. |
+| Shell background (default) | `var(--dsx-color-surface)` | Resting surface. |
+| Shell background (classic) | `var(--dsx-color-surface)` | Elevated surface. |
+| Shell background (soft) | `var(--dsx-color-surface-raised)` | Soft surface. |
+| Shell background (light theme, default) | `var(--dsx-color-surface-field-autofill)` | Light-theme shell background (see Anomalies). |
+| Shell shadow (classic) | `var(--dsx-effect-shadow-1)` | Classic variant elevation. |
+| Shell focus border | `var(--dsx-color-primary)` (via `baseInput.css`) | Focus state. |
+| Shell focus shadow | `var(--dsx-shadow-focus-ring)` (via `baseInput.css`) | Focus ring. |
+| Shell error border | `var(--dsx-color-error)` | Invalid state. |
+| Shell radius | `var(--dsx-rounded-md)` (via `baseInput.css`) | Default corner radius. |
+| Shell hover border | `var(--dsx-color-outline-variant)` (via `baseInput.css`) | Hover state. |
+| Shell hover background | `var(--dsx-color-surface-hover)` (via `baseInput.css`) | Hover state. |
+| Shell disabled border | `var(--dsx-color-disabled-border)` | Disabled state. |
+| Shell disabled background | `var(--dsx-color-disabled-surface)` | Disabled state. |
+| Shell disabled cursor | `var(--dsx-cursor-disabled, not-allowed)` | Disabled cursor. |
+| Input typography | `var(--dsx-typography-body-medium-*` | Body ramp. |
+| Input color | `var(--dsx-color-on-surface)` | Typed value. |
+| Input placeholder color | `var(--dsx-color-on-surface-variant)` (via `baseInput.css`) | Placeholder. |
+| Input disabled text color | `var(--dsx-color-disabled-text)` | Disabled state. |
+| Slot color | `var(--dsx-color-on-surface-variant)` | Slot text / icon. |
+| Slot padding inline | `var(--dsx-space-sm)` | Inline gutter for the slot. |
+| Error text color | `var(--dsx-color-error)` | Error message. |
+| Helper text color | `var(--dsx-color-on-surface-variant)` | Helper message. |
+| Density `sm` shell min-height | `var(--dsx-density-control-height-sm, var(--dsx-size-lg))` | Small control. |
+| Density `sm` shell padding inline | `var(--dsx-density-control-padding-inline-sm, var(--dsx-space-sm))` | Small inline gutter. |
+| Density `sm` shell padding block | `var(--dsx-density-control-padding-block-sm, var(--dsx-space-xs))` | Small block gutter. |
+| Density `sm` input font size | `var(--dsx-typography-body-small-font-size)` | Small body ramp. |
+| Density `md` shell min-height | `var(--dsx-density-control-height, var(--dsx-size-xl))` | Default control. |
+| Density `md` shell padding inline | `var(--dsx-density-control-padding-inline, var(--dsx-space-md))` | Default inline gutter. |
+| Density `md` shell padding block | `var(--dsx-density-control-padding-block, var(--dsx-space-sm))` | Default block gutter. |
+| Density `lg` shell min-height | `var(--dsx-density-control-height-lg, var(--dsx-size-2xl))` | Large control. |
+| Density `lg` shell padding inline | `var(--dsx-density-control-padding-inline-lg, var(--dsx-space-lg))` | Large inline gutter. |
+| Density `lg` shell padding block | `var(--dsx-density-control-padding-block-lg, var(--dsx-space-md))` | Large block gutter. |
+| Density `lg` input font size | `var(--dsx-typography-body-large-font-size)` | Large body ramp. |
+| Motion | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Shell transitions. |
+
+Rules:
+
+- Tokens come from `DESIGN.md` and the generated `tokens.css`. The only intentional non-token value is the `0` border and `transparent` background on the input element, which lets the shell show through.
+- `data-accent-color` and `data-radius` are written by the runtime and reserved for future CSS hooks; today there are no matching declarations.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| Shell border and box-shadow on focus-within | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Border swap to `var(--dsx-color-primary)` plus focus ring | `none` — relies on the global `prefers-reduced-motion` stylesheet. |
+| Shell border swap on invalid | (uses the same transition as the focus-within rule) | Border swap to `var(--dsx-color-error)` | `none` — relies on the global stylesheet. |
+
+Rules:
+
+- This row does not import `MOTION_TRANSITIONS` from `src/_internal/motion.ts`. All motion is CSS-only.
+- A future promotion that uses framer-motion should pick a preset from `MOTION_TRANSITIONS` and gate it with `usePrefersReducedMotion`.
+
+## Accessibility
+
+**Roles:**
+
+- The root is a `<div>`. The label is a `<label>` bound to the input via `htmlFor`. The input is a standard `<input>`.
+- `aria-invalid` is reflected on the input when `invalid` is `true`. The `Field.Error` integration is the consumer's job; `TextField` only paints the error text and the error border.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to or from the input, then to the optional `TextField.Slot` (which is a `<div>` and is not focusable by default), then out. |
+| `Enter`, `Space` | Standard input behavior; consumers that need to submit a form can wrap the `TextField` in a `<form>` and rely on the browser. |
+| Type | Standard input behavior. |
+
+**Focus:**
+
+- Visible focus ring on the input is owned by the shell via the `dsx-text-field__shell:focus-within` rule (border color + `var(--dsx-shadow-focus-ring)`). The inner input is `outline: none` because focus is delegated to the shell.
+- The label is a `<label>` and is not focusable; clicking the label focuses the input via the standard `htmlFor` association.
+
+**Reduced motion:**
+
+- The component does not currently gate motion at runtime. The CSS transitions honor the global `prefers-reduced-motion` media query.
+
+**Color and meaning:**
+
+- The invalid state is communicated by the `dsx-text-field--invalid` modifier class, the `var(--dsx-color-error)` border, the `aria-invalid="true"` reflection on the input, and the `dsx-text-field__error` text. Color is not the only signal.
+- The error / helper text colors are token-driven; the meaning is in the text, not the color.
+
+**Naming:**
+
+- The label provides the accessible name when supplied. Consumers that do not supply a `label` must pass `aria-label` on the input.
+- The `TextField.Slot` is decorative by default. If the slot carries a control (an icon button, a clear button, a copy button), the control owns its own accessible name.
+
+## Playground demo spec
+
+The demo file at `demo_path` exposes the component to the playground. The playground lives at `apps/playground/app/` (Next.js app router, no per-component routes today). The `demo_path` recorded here is the current playground root; the spec assumes a single shared page that renders all components. Per-component routes are an aspirational target and not yet present in the repo.
+
+**Default story:**
+
+- Renders `TextField` with `id="email"`, `label="Email"`, `helperText="We will never share your email."`, and a `TextField.Input aria-label="Email"`. Asserts the root class is `dsx-text-field`, the `data-size` attribute is `md`, the `data-variant` attribute is `surface`, the label is bound to the input via `htmlFor`, and the helper text is visible.
+
+**Variant story** (one per density and variant):
+
+- Renders with `density="sm"`, `density="md"`, and `density="lg"`. Asserts the matching `dsx-text-field--{value}` modifier class and the `data-size` attribute.
+- Renders with `variant="surface"`, `variant="classic"`, and `variant="soft"`. Asserts the matching `dsx-text-field--{value}` modifier class and the variant-specific shell background, border, and shadow.
+
+**State story:**
+
+- Renders with `invalid={true}` and `errorText="Invalid email"`. Asserts the `dsx-text-field--invalid` modifier class, the `aria-invalid="true"` on the input, the `var(--dsx-color-error)` border, and the error text being visible while the helper is hidden.
+- Renders with a `TextField.Slot` containing a `⌘K` glyph. Asserts the slot renders next to the input inside the shell.
+- Renders with `color="blue"`. Asserts the `data-accent-color="blue"` attribute on the root.
+
+**Composition story** (for `asChild`):
+
+- Renders the component with `asChild` wrapping a custom `<section>` element. Asserts the host element receives the `dsx-text-field` class and the `data-*` attributes.
+
+**Token story:**
+
+- Renders inside a `Theme` wrapper with `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`. Asserts the focus border color tracks `var(--dsx-color-primary)` (which is theme-aware) across all three accent settings. The `color` prop is also exercised: when set to `silver` or `bronze`, the `data-accent-color` attribute is forwarded to the root and the focus border tracks the active accent.
+
+**A11y story:**
+
+- Uses `vitest-axe` against the rendered default TextField. Asserts the input has an accessible name (via the label), the error text is associated with the input (via proximity in the DOM), and the component has no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `label` | text | `Email` |
+| `helperText` | text | `We will never share your email.` |
+| `errorText` | text | `Invalid email` |
+| `invalid` | boolean | `false` |
+| `density` | select | `md` |
+| `variant` | select | `surface` |
+| `color` | select | (none) |
+| `radius` | select | (none) |
+| `asChild` | boolean | `false` |
+
+## Wiring notes
+
+**Composes from:**
+
+- `Label` (primitive): the label slot renders through the `Label` primitive for accessible `<label htmlFor>` association. The TSX imports `Label` directly.
+- `Text` (primitive): the helper and error slots render through the `Text` primitive at `label-small` (`tone="muted"` for the helper). The TSX imports `Text` directly.
+- `Input` (primitive, via `baseInput.css`): the inner input reuses the body-medium typography, the placeholder color, the disabled text color, and the autofill contract. The TSX does not import the `Input` component; the CSS contract is the alignment layer.
+- `_internal/baseInput.css`: shared shell, border, hover, focus, disabled, placeholder, and autofill contract.
+- `@radix-ui/react-slot`: enables `asChild` on the root.
+- `Field` (consumer pattern, not a runtime import): the canonical wrapper for grouped fields. `TextField` is a convenience composition; for richer form rows (groups, sets, legends, multiple descriptions), use `Field` directly. The component does not own a `Field` integration; the consumer composes `Field.Root` around `TextField` when needed.
+
+**Used by:**
+
+- App-level form rows where label + input + helper + error fit a single column. For richer rows, switch to `Field`.
+
+**State boundaries:**
+
+- Owned by TextField: the controlled-or-not layout state, the invalid border and error text, the helper / error visibility toggle (`errorText` only when `invalid` is true, `helperText` only when `invalid` is false), the `aria-invalid` reflection, the `data-accent-color` mirror from the `color` prop, and the slot region for inline add-ons.
+- Owned by the consumer: the value, `onChange`, the validation rules, the host element when `asChild` is set, and the surrounding form context (groups, sets, legends) that the consumer wires through `Field` when needed.
+
+**Boundary rules:**
+
+- App-owned data: the persisted value, the validation rules, the persistence strategy, and the surrounding form context.
+- DS-owned visuals: token bindings, the `dsx-text-field` and slot classes, the `data-size`, `data-variant`, `data-radius`, and `data-accent-color` attributes, the `aria-invalid` reflection, and the label / helper / error typography ramps.
+- The component does not own a `Field` integration. Wrap in `Field.Root` at the app level for grouped fields or for richer description / error orchestration.
+
+## Anomalies
+
+- **Roster vs. runtime shape.** The roster's `Parent / Slots` column lists `-` (flat) for `TextField`, but the runtime in `TextField.tsx` exports a compound surface: `TextField.Input` and `TextField.Slot` are attached via `Object.assign`. The test file in `src/test/components/TextField.test.tsx` exercises both. The spec records the runtime shape as the source of truth; the roster row should be updated to list `TextField.Root`, `TextField.Input`, `TextField.Slot`.
+- **Roster says "composed from Field + Input" but the runtime composes `Label` + `Text` + the `Input` CSS contract.** The roster's `Composed From` column names `Field` and `Input` as the components `TextField` builds on. The runtime imports `Label` and `Text` from the package, and the inner `<input>` is a plain HTML element that reuses the `Input` shell via `baseInput.css`. `Field` is not imported. The `depends_on` block at the top of this spec records the actual import graph plus the `Field` consumer-pattern relationship.
+- **`density` prop writes `data-size`, not `data-density`.** The prop is named `density` on the bag, but the runtime writes `data-size="sm"\|"md"\|"lg"`. The CSS consumes the modifier class `dsx-text-field--{value}` (added in the TSX), not the `data-size` attribute. The naming split matches `PasswordInput` and `NumberInput`; it is a convention in the package but the attribute name is misleading for consumers that inspect the DOM.
+- **`color` prop is `enum | string` with empty values.** The `color` prop def is `type: 'enum | string'` with an empty `values: []` array, so the runtime accepts any string. The test file uses `color="blue"` to assert the `data-accent-color="blue"` attribute is forwarded. The CSS does not currently declare `[data-accent-color='...']` rules on the root, so the attribute is mirrored for theme-aware descendant styling but does not affect the field's own visual treatment.
+- **`data-radius` is not CSS-backed.** The attribute is written by the runtime and listed on the prop bag, but `text-field.css` has no `[data-radius='...']` rule. The shell uses the default `var(--dsx-rounded-md)` from `baseInput.css`. The contract is reserved.
+- **`data-accent-color` is not CSS-backed on this component.** The attribute is written by the runtime when `color` is set, but `text-field.css` has no `[data-accent-color='...']` rule. The attribute is forwarded for descendant styling (the focus border on the shell uses `var(--dsx-color-primary)` regardless, which is theme-aware), but the field's own background and border do not change with `data-accent-color`.
+- **Light-theme shell background is the autofill color.** `[data-dsx-theme='light'] .dsx-text-field__shell` declares `background: var(--dsx-color-surface-field-autofill)`. This is a special-case override for the light theme; the dark theme uses the default `--dsx-color-surface`. The override means a light-theme `TextField` shell looks like a browser-autofill state at rest, which is a visual inconsistency with `PasswordInput` and `Input` (which do not apply this override). The intent is unclear; the override may be a bug or a design choice that should be promoted to the shared `baseInput.css` rules.
+- **No `data-slot` attributes on the runtime.** Sibling components (`Editable`, `PasswordInput`) write `data-slot` attributes for QA and audit tooling. `TextField` does not. This is a consistency gap; the spec does not prescribe a fix.
+- **`TextField.Slot` is always rendered next to the input, never as a separate column.** The slot lives inside the shell and is laid out with `display: inline-flex`. Consumers that need a slot outside the shell (a leading icon column, a trailing badge column with separate background) cannot use this slot; they must compose `Field` + `InputGroup` instead.
+
+## 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 TextField. Recipe is visual reference only and tracks the CSS contract.
+
+### Root board
+
+- **Name**: `Components / TextField`.
+- **Dimensions**: `320 × auto` (default), `280 × auto` (sm), `360 × auto` (lg).
+- **Layout**: `Flex` (column).
+- **Sizing**: `horizontalSizing = 'fix'`, `verticalSizing = 'auto'`.
+
+### Layer tree
+
+```
+<Root Board: TextField / md>
+  ├── <Text: label (when set)>
+  ├── <Frame: input shell>
+  │   ├── <Text: input value (or placeholder)>
+  │   └── <Text: optional slot content>
+  └── <Text: helper (default) or error (when invalid)>
+```
+
+### Token bindings (Penpot properties)
+
+| Shape | Property | Token | Token type | Penpot property name |
+|---|---|---|---|---|
+| Root | gap | `--dsx-space-xs` | Spacing | `gap` |
+| Shell | stroke | `--dsx-color-outline` | Color | `strokes` |
+| Shell | fill | `--dsx-color-surface` | Color | `fills` |
+| Shell | radius | `--dsx-rounded-md` | Radius | `radius` |
+| Shell (focus) | stroke | `--dsx-color-primary` | Color | `strokes` (state) |
+| Shell (focus) | shadow | `--dsx-shadow-focus-ring` | Effect | `shadow` (state) |
+| Shell (hover) | stroke | `--dsx-color-outline-variant` | Color | `strokes` (state) |
+| Shell (hover) | fill | `--dsx-color-surface-hover` | Color | `fills` (state) |
+| Shell (classic) | shadow | `--dsx-effect-shadow-1` | Effect | `shadow` (variant) |
+| Shell (soft) | fill | `--dsx-color-surface-raised` | Color | `fills` (variant) |
+| Shell (soft) | stroke | `transparent` | Color | `strokes` (variant) |
+| Shell (invalid) | stroke | `--dsx-color-error` | Color | `strokes` (state) |
+| Shell (light theme) | fill | `--dsx-color-surface-field-autofill` | Color | `fills` (theme) |
+| Input | text | `--dsx-color-on-surface` | Color | `fills` |
+| Input | placeholder | `--dsx-color-on-surface-variant` | Color | `fills` (state) |
+| Input | typography | `--dsx-typography-body-medium-*` | Typography | `typography` |
+| Slot | text | `--dsx-color-on-surface-variant` | Color | `fills` |
+| Slot | padding inline | `--dsx-space-sm` | Spacing | `padding` |
+| Helper | text | `--dsx-color-on-surface-variant` | Color | `fills` |
+| Error | text | `--dsx-color-error` | Color | `fills` |
+| Helper / error | typography | `--dsx-typography-label-small-*` | Typography | `typography` |
+
+### State transformations
+
+| State | Shell stroke | Shell fill | Shell shadow | Helper / error text |
+|---|---|---|---|---|
+| `default` (dark) | `--dsx-color-outline` | `--dsx-color-surface` | none | helper `--dsx-color-on-surface-variant` |
+| `default` (light) | `--dsx-color-outline` | `--dsx-color-surface-field-autofill` | none | helper `--dsx-color-on-surface-variant` |
+| `hover` | `--dsx-color-outline-variant` | `--dsx-color-surface-hover` | none | helper `--dsx-color-on-surface-variant` |
+| `focus` | `--dsx-color-primary` | `--dsx-color-surface` | `--dsx-shadow-focus-ring` | helper `--dsx-color-on-surface-variant` |
+| `invalid` | `--dsx-color-error` | `--dsx-color-surface` | none | error `--dsx-color-error` |
+| `disabled` | `--dsx-color-disabled-border` | `--dsx-color-disabled-surface` | none | helper `--dsx-color-on-surface-variant` |
+| `classic` | `--dsx-color-outline` | `--dsx-color-surface` | `--dsx-effect-shadow-1` | helper `--dsx-color-on-surface-variant` |
+| `soft` | `transparent` | `--dsx-color-surface-raised` | none | helper `--dsx-color-on-surface-variant` |
+
+### Variant model
+
+- `density`: `sm`, `md`, `lg`. Default `md`.
+- `variant`: `classic`, `surface`, `soft`. Default `surface`.
+- `color`: any string. Default `undefined`. (See Anomalies — no visual change today.)
+- `radius`: `none`, `sm`, `md`, `lg`, `full`. Default `md` (from the shell).
+- `invalid`: `true`, `false`. Default `false`.
+- Total members: 3 × 3 × N × 5 × 2 (where N is the open set of `color` strings).
+
+### 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.
+- [ ] `data-accent-color` and `data-radius` slots exist in Penpot but resolve to no visual change today; document the reservations.
+- [ ] Light-theme shell background override is documented; the spec marks it as a future investigation.