Form field
==========

Spec: descriptive guidance, not a checkable rule.
It carries no forbidden and instead pair, and no `jig check` detector applies to it directly.
Section: Components and layout

**Anatomy, in this order:**
1. `<label>` — always visible, **stacked above** the input (`F-98`)
2. Required or optional marker, in the label (`F-97`)
3. Hint text — **above** the input, below the label
4. Error message — **also above the input**, after the hint, `role="alert"`
5. Input

**States:** `default`, `focus`, `filled`, `invalid`, `disabled`, `read-only`.

### Label

- **Above the input, never beside it.** Left-placed labels force the eye to zig-zag; right-aligning them to fix that creates a jagged left edge that is harder to scan; and long labels wrap badly in the narrow column. Stacked above, the label and input are taken in with a single focus.
- **Close to its input** — `--spacing-label` (4px), against `--spacing-stack` between fields. The label must be visibly closer to its own input than to anything else, or the pairing is ambiguous (`D-25`).
- **No instructional verbs.** "Email", not "Enter your email" or "Type your email here". The input field already implies the verb.
- No "my" or "your" (`I-88`).

### Required and optional

**Mark both.** Marking only optional fields, with "all fields are required unless marked optional" at the top, fails because people scan past instructions — and marking both is an accessibility requirement for screen reader users anyway.

| | Marker |
| --- | --- |
| Required | `*` with the convention stated at the top, **or** the word "required" |
| Optional | The word "optional" |

The word "required" is the safer of the two: no instruction needed anywhere, no assumption that the asterisk is understood. The asterisk is more concise and lets people scan the count of required fields at a glance. Either is fine; be consistent.

**Never colour the asterisk red.** Red means error.

You may leave required fields unmarked only when: the product has no optional fields anywhere; the form is short and familiar (login, newsletter signup); the form asks one question per screen with the reason explained; or testing has shown it is unnecessary.

### Hints

Above the input, not below. Two reasons: a rule about a password's minimum length is useful **before** typing, not after failing; and the space below an input gets covered by autofill menus and on-screen keyboards, so a hint placed there may never be seen.

Do not hide a hint in a tooltip if it is needed to complete the field.

**The error message goes above the input too, and for the second of those reasons.** The space below a field is covered by autofill menus and on-screen keyboards at exactly the moment an error appears — so an error placed there is hidden from the person who most needs to see it. Putting the hint above and the error below would have taken half of one argument and ignored the other half.

Order between them: hint first, then error. The hint is standing guidance about the field; the error is a transient response to what was just typed, so it sits closest to the input it is about.

### Placeholders

Not a label (`F-36`). Placeholders vanish on focus, make an empty field look pre-filled and skippable, and are light enough by design that they usually fail contrast.

Use one only as a **format example** — `MM / YY` — or in a single-field search box, and then at 4.5:1 with a real accessible label present.

### Width

**Match the width to the expected input.** A four-character postcode gets a four-character field. Uniform full-width fields look tidy and lie about the input: width is the strongest hint people have about how much is wanted. Where length varies, size for the common case.

### Conventional styling

Keep the iconic parts (`E-52`): a rectangle with the label above, a square with a tick for checkbox, a circle for radio. If you restyle — enlarging a radio's target area, say — **keep the circle on the left of the label**. Without it, nobody can tell whether one option or several can be chosen.

### Other rules

- Error text says what to do (`F-37`), signalled by border **and** text **and** `aria-invalid` — never colour alone (`C-20`).
- `type`, `inputmode`, `autocomplete`, `enterkeyhint` set correctly (`F-40`).
- Field borders clear **3:1** (`02-tokens.md`). Low-contrast borders are the single most common form defect, and they fail for a sighted user in sunlight as readily as for someone with low vision.
- Never reformat or truncate a value while it is being typed.