One thing per page pattern

patterns specs/patterns/one-thing-per-page.kmd

A form-design constraint: each page in a flow asks the user for ONE thing — one decision or one logically-grouped piece of information — with a single primary action. Reduces cognitive load, makes validation and error recovery trivial, and is the structural reason multi-step wizards work on small screens and for assistive tech. Modeled after the GOV.UK "one thing per page" service-design principle.

When this pattern applies

Primary triggers

All triggers

Pattern — One thing per page

Status: v0.1.0 — Draft. Promoted from the GOV.UK parity scan (meta/docs/stack #096). A design constraint applied BY specs/patterns/wizard-multistep.kmd (each wizard step honors it). Source: https://www.gov.uk/service-manual/design/structuring-forms

R1 — The constraint

Each page asks for one thing. "One thing" is one decision or one logically-inseparable group of fields — not literally one input. A page may hold multiple fields when they describe a single concept:

  • ✅ One thing: a postal address (several fields, one concept).
  • ✅ One thing: a date of birth (day/month/year).
  • ❌ Two things: "address AND date of birth" on one page.

When in doubt, split. Pages are cheap; a confused or error-prone user is not.

R2 — What each page has

ElementRequiredNotes
One question headingYesThe page <h1> IS the question ("What is your address?")
Field(s) for that one thingYesGrouped in a <fieldset>+<legend> when multi-field
One primary actionYesA single forward button ("Continue" / "Save and continue")
Back linkYesTo the previous page; preserves entered data (specs/navigation/back-behavior.kmd)
Inline helpOptionalHint text under the heading, before the field

There is at most ONE primary button. Secondary paths (e.g. "I don't have this") are links or a clearly secondary control, never a second primary.

R3 — Why split (rationale, normative intent)

  • Validation becomes per-thing: one page can only fail for one concept, so error messages are unambiguous (pairs with specs/errors/user-facing-messages.kmd and the error-summary component).
  • Cognitive load: the user makes one decision at a time.
  • Small screens & AT: one thing fits a phone viewport (specs/app-layout/safe-area.kmd) and a single screen-reader pass.
  • Branching: the answer to one page can route the next page (see specs/patterns/wizard-multistep.kmd R1 branching).

R4 — When to group vs split

  • Group fields that the user thinks of as one item AND that are always needed together (address, full name, date).
  • Split when fields are independently optional, independently validated, or conditionally shown.
  • Never group merely to save pages — page count is not a cost to optimize against the constraint.

R5 — Relation to wizard & task list

  • A wizard-multistep step SHOULD be one-thing-per-page; this spec is the per-step granularity rule the wizard composes.
  • A task-list task is itself a short one-thing-per-page sequence.
  • Koder Sign's multi-step signing flow applies this constraint: each required field/decision (place signature, confirm intent, provide reason) is its own page/step.

R6 — Accessibility & i18n

  • The single question is the page <h1>; the field's label/legend is the same question (no orphan placeholder-as-label).
  • Focus on page enter lands on the heading or first field per specs/navigation/back-behavior.kmd.
  • Each page's strings are independent i18n keys (specs/i18n/contract.kmd); splitting/grouping decisions are language- invariant (do not regroup pages per locale).

Não-escopo

  • The step indicator / progress UI (in wizard-multistep.kmd).
  • Field-level component specs (text field, date input, radios — under specs/components/).
  • Server-side persistence of partial answers (multi-tenancy contract).

References