# Form

## Overview

The form composition layer normalizes native form grouping patterns that combine multiple controls into one horizontal affordance.

Use it for semantic search forms and grouped control wrappers. Individual controls still come from the input, button, select, checkbox, radio, switch, and related component stylesheets.

## Usage

```html
<form role="search">
  <input type="search" name="q" placeholder="Search" />
  <button type="submit">Search</button>
</form>
```

```html
<fieldset role="group">
  <legend>Amount</legend>
  <input type="number" name="amount" />
  <button type="button">Apply</button>
</fieldset>
```

Use `form[role="search"]` for compact search bars. Use `fieldset[role="group"]` when grouped controls need a native legend. Use `div[role="group"]` only when a fieldset would be semantically incorrect.

Unlike most component styles, labels and legends do not map these values through component-specific variables. They consume the shared `--form-label-*` variables directly. This is intentional: customize these variables on the form or a containing region so every label and legend in that form retains the same visual treatment.

## Behavior

- FRM-001: `form[role="search"]`, `fieldset[role="group"]`, and `div[role="group"]` render as single horizontal control groups.
- FRM-002: Adjacent controls overlap one border width so joins read as one divider.
- FRM-003: Interior control corners are square; only the first and last grouped controls keep the outer radius.
- FRM-004: `fieldset[role="group"]` resets native border, margin, and padding so it behaves like the other group wrappers.
- FRM-005: Inputs and text buttons in grouped controls grow and shrink together, while icon-only buttons retain their square content-based width.
- FRM-006: Native fieldsets that keep their border chrome derive their corner radius from `--form-control-radius`.
- FRM-007: Group wrappers fill their available inline space and contain their children’s intrinsic sizing so they do not force page-level horizontal overflow.
- FRM-008: Visible field labels and native legends consume the shared `--form-label-*` variables directly so their color, font size, and line height remain consistent across form control types.

## Accessibility

- Use `form[role="search"]` only for search behavior.
- Prefer `fieldset[role="group"]` with a visible `legend` when controls need a shared label.
- Keep grouped controls in logical source order.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--form-control-border-width` | `<length>` | Sets the border width used to join adjacent controls in semantic form groups; change it when grouped controls need to match a different control border rhythm. |
| `--form-control-radius` | `<length>` | Sets the fallback outer corner radius for grouped form controls; change it when a grouped control does not provide its own radius hook. |
| `--form-icon-button-inline-size` | `<length>` | Sets the square inline size of icon-only buttons inside grouped controls; change it when their typography or control padding requires a different footprint. |
| `--form-label-color` | `<color>` | Shared color for field labels and native legends. |
| `--form-label-font-size` | `<length>` | Shared font size for field labels and native legends. |
| `--form-label-line-height` | `<number>` | Shared line height for field labels and native legends. |
| `--grouped-control-radius` | `<length>` | Corner radius hook for controls inside native form groups. Buttons and inputs map this hook back to their component radius aliases so grouped controls keep compatible outer corners. |

## Depends On

- `--color-text-accent`
- `--font-line-height-body`
- `--font-size`
- `--layout-control-border-width`
- `--layout-control-min-height`
- `--layout-control-radius`