{
  "id": "field",
  "name": "Field",
  "level": "molecule",
  "status": "stable",
  "purpose": "One form question: its label, the control, a hint and any error.",
  "description": "**Purpose.** The canonical accessible form composition. `Field` is the molecule that *binds* a label, a control, a description and an error into a single semantic unit, owning the wiring (`id`, `htmlFor`, `aria-describedby`, `aria-invalid`, `aria-required`) so the consumer never forgets it.\n\n**When to use.**\n- Any input that needs a visible label (almost always).\n- A choice control (radio, checkbox, switch) that participates in a form.\n- A composite control (Select, Combobox, DateField, FileDropzone) that should expose the same a11y contract as a plain Input.\n\n**When NOT to use.**\n- Inline single-input search bars where the placeholder *is* the label (controversial, but accepted) — use the bare control.\n- Toolbar-style toggles where the affordance is a `Switch` without descriptive copy — use the atom directly.\n- A list of independent options *not* tied to a label (a permission grid, a settings switchboard) — use `ChoiceGroup` or `SettingsField`.\n\n**Composes with.**\n- `Field.Label` (always), `Field.Control` (wraps the input atom), `Field.Description` (intent / hint), `Field.Error` (validation).\n- Controls: `Input`, `Textarea`, `Select`, `Combobox`, `Checkbox`, `Radio`, `Switch`, `DateField`, `Slider`, `FileDropzone` — anything that accepts standard ARIA attributes on its rendered DOM element.\n- `FormSection` consumes Field as the row unit; `ErrorSummary` aggregates errors that originate in Field.\n\n**Accessibility.**\n- `Field.Label` becomes the control's accessible name via `htmlFor` ↔ `id`. Required fields expose `aria-required` automatically.\n- `Field.Description` and `Field.Error` are joined into the control's `aria-describedby` so assistive tech reads the hint and the error in order.\n- `invalid` propagates `aria-invalid=\"true\"` and triggers the error tone on the control's chrome.\n- `disabled` propagates to the control and visually demotes the label without removing it from screen readers.\n- Radio / Checkbox / Switch controls keep their native semantics; the molecule never wraps them in extra interactive divs.\n\n**Related patterns.**\n- `Patterns/Forms · FieldAnatomy` — the four-slot anatomy this molecule renders.\n- `Patterns/Forms · ValidationFlow` — when and where the error appears.\n- `Patterns/Feedback · InlineFeedback` — why the error stays next to its cause.\n- `Patterns/Composition · AtomToMolecule` — Field as the first molecule a form needs.",
  "role": "input",
  "import": "@rrios-forge/ui/molecules/field",
  "exports": [
    "Field",
    "FieldRoot",
    "FieldControl",
    "FieldDescription",
    "FieldError",
    "FieldLabel",
    "useFieldContext",
    "FIELD_ORIENTATIONS",
    "fieldVariants"
  ],
  "source": "packages/ui/src/molecules/field",
  "axes": [
    {
      "axis": "orientation",
      "part": null,
      "values": [
        "vertical",
        "horizontal"
      ],
      "default": "vertical",
      "meaning": "The direction the parts run: a row (horizontal) or a column (vertical); responsive stacks on phones and runs in a row from sm."
    },
    {
      "axis": "disabled",
      "part": null,
      "values": [
        "true",
        "false"
      ],
      "default": "false",
      "meaning": "Not available: dimmed, skipped by the keyboard, ignores the pointer."
    }
  ],
  "needs": [
    {
      "need": "Field with label + helper + error",
      "answer": "`Field` + `Input`/`Textarea`/`Select`"
    }
  ],
  "patterns": [
    "Patterns/Forms · FieldAnatomy",
    "Patterns/Forms · ValidationFlow",
    "Patterns/Forms · ChoiceControls",
    "Patterns/Feedback · InlineFeedback",
    "Patterns/Composition · AtomToMolecule"
  ],
  "a11yExceptions": [],
  "decisions": [
    {
      "id": "ADR-004",
      "title": "Migrate boolean configuration props to semantic axes"
    },
    {
      "id": "ADR-006",
      "title": "Geometry and typography signature"
    },
    {
      "id": "ADR-035",
      "title": "Motion grammar: the gate before motion, slop by repetition, and what reduced motion keeps"
    }
  ],
  "stories": [
    {
      "name": "Playground",
      "id": "components-molecules-field--playground",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-field--playground",
      "frame": "/iframe.html?id=components-molecules-field--playground&viewMode=story"
    },
    {
      "name": "With Input",
      "id": "components-molecules-field--with-input",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-field--with-input",
      "frame": "/iframe.html?id=components-molecules-field--with-input&viewMode=story"
    },
    {
      "name": "With Textarea",
      "id": "components-molecules-field--with-textarea",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-field--with-textarea",
      "frame": "/iframe.html?id=components-molecules-field--with-textarea&viewMode=story"
    },
    {
      "name": "With Select",
      "id": "components-molecules-field--with-select",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-field--with-select",
      "frame": "/iframe.html?id=components-molecules-field--with-select&viewMode=story"
    },
    {
      "name": "With Checkbox",
      "id": "components-molecules-field--with-checkbox",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-field--with-checkbox",
      "frame": "/iframe.html?id=components-molecules-field--with-checkbox&viewMode=story"
    },
    {
      "name": "Invalid",
      "id": "components-molecules-field--invalid",
      "interaction": false,
      "snapshots": [
        "dark",
        "high-contrast",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-field--invalid",
      "frame": "/iframe.html?id=components-molecules-field--invalid&viewMode=story"
    },
    {
      "name": "Disabled",
      "id": "components-molecules-field--disabled",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-field--disabled",
      "frame": "/iframe.html?id=components-molecules-field--disabled&viewMode=story"
    },
    {
      "name": "Required",
      "id": "components-molecules-field--required",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-field--required",
      "frame": "/iframe.html?id=components-molecules-field--required&viewMode=story"
    },
    {
      "name": "Density examples",
      "id": "components-molecules-field--density-examples",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-field--density-examples",
      "frame": "/iframe.html?id=components-molecules-field--density-examples&viewMode=story"
    },
    {
      "name": "Accessibility",
      "id": "components-molecules-field--accessibility",
      "interaction": false,
      "snapshots": [
        "dark",
        "high-contrast",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-field--accessibility",
      "frame": "/iframe.html?id=components-molecules-field--accessibility&viewMode=story"
    }
  ],
  "storyFile": "tooling/storybook/stories/components/molecules/field.stories.tsx"
}