Skip to content
GitHub
Sections

Reference · Components and layout

Form

This is a spec: descriptive guidance, not a checkable rule. It carries no forbidden and instead pair, and no jig check detector applies to it directly.

The spec

Anatomy: heading → intro → required/optional convention → error summary slot → fields grouped by meaning → primary action → secondary action.

Layout

  • One column. It keeps a single downward path, so there is no decision about what to fill next, nothing gets missed, and screen-magnifier users — who see a narrow slice at a time — do not lose a second column entirely.
  • Exception: short, genuinely related fields may sit side by side *within* the column's width — expiry date and CVC, city and postcode. They stay inside the single-column bounds, so they avoid the problems above.
  • Group related fields under headings with <fieldset>/<legend>, spaced by --spacing-stack; fields within a group by --spacing-group.
  • Ask for the minimum. Every field costs completions, adds a chance of error, and asks someone to hand over information they would rather not.
  • Prefer an opt-in to an optional field (P-11).

Validation timing (F-38)

On blur first; on change once a field has already errored, so recovery is immediate; everything on submit, with a summary that receives focus and links to each failed field.

The reference sets out three approaches — on submit, on blur, on every keystroke — and prescribes none of them, because each has a cost: on-submit leaves people guessing until the end and then confronts them with everything at once; on-blur interrupts; keystroke validation fires before someone has finished typing, and people type at different speeds. What it does pair explicitly is on-blur with keystroke validation *for recovery only* — "remove the error message once the error has been resolved" — which is the combination above, and the reason the keystroke half is scoped to fields that have already failed.

The summary states the count — "2 errors were found" — and each entry links to the field it names. Do not disable the submit button to prevent an invalid submission (E-32): a disabled control cannot be focused, so it cannot explain itself.

An invalid field is marked by border, background tint, icon and text together — never by colour alone (C-20), and never by one channel that a magnifier or a colour-blind user might miss.

Multi-step

Beyond roughly three question groups, split it.

  • Say up front how long it takes and what they will need.
  • Group into few, fuller steps — six steps of five related questions, not thirty steps of one. More steps is more interaction cost, not less.
  • Order easiest to hardest, so early progress is quick.
  • Show progress. People push harder as they near the end.
  • Let them review and change answers before submitting, then confirm success and say what happens next.
  • Primary action start-aligned; "Back" as a tertiary button at the top left (P-02).
  • Each step still submits without JavaScript (F-41) — steps are server-tracked positions, not a client-only wizard.

Other rules

  • Echo every submitted value back on error (F-39).
  • The primary action works without JavaScript. Enhancement intercepts; it does not enable.
  • Destructive or irreversible submissions confirm; in operator, by typing.
  • Success navigates or updates in place with a persistent confirmation — not a toast that vanishes before it is read.
Kind
Spec
Section
Components and layout

Read as plain text