Patterns

Foundations tells you what a token means. Components tell you what one part does. Neither of them tells you what happens on the second screen, and almost every failure in a consumer health product happens on the second screen. That is the one where the result arrives, the one where validation fires, the one where the network was gone and nobody said so.

Patterns are that layer. Each page here takes a single user task, follows it from entry to exit, and says what the system knows at each step, what it must not assume, and where the person can leave.

60 shipped

When to use

Reach for a pattern when the thing you are building spans more than one moment in time:

• More than one screen. Onboarding, a consent flow, a result that arrives after the reader has closed the app.
• More than one state. The same surface has to be right when the data is fresh, stale, partial, missing and wrong, and the interesting design work is in the transitions between those.
• A decision with a consequence. Disclosing a result, escalating an alert, asking for a permission the reader can refuse. If getting it wrong costs the reader something, it is a pattern, not a component.
• A shape you have built twice already. Three teams inventing three different validation timings is how a product stops feeling like one product.

Two sub-families sit under this group because they are keyed differently from the rest:

• Form design shows how a question behaves, as distinct from how a form is wired up. One question per page or grouped, when validation fires, where the error summary goes.
• Ask users for… is keyed by the data being requested: a date of birth, a name, a set of medications. This is the highest reuse in the whole system, because every health product asks for the same fifteen things and gets roughly the same eight of them wrong.

When not to use

• The whole thing fits inside one component. If your guidance is "the label goes above the input", that belongs on the component page, not here. Write it on Field.
• You want working steps, not a shape. A pattern describes the shape of a solution and the reasoning behind it. If you want an ordered list that ends with something on screen, go to Recipes instead. A recipe is a task with an ending.
• You want the rule rather than the sequence. "Never let motion carry urgency" is doctrine and lives in Health. Patterns apply doctrine; they do not restate it, and assert-ia will fail a build in which they do.
• You want a whole composed surface. A finished results screen with real composition and a preview is a Screen.
• It is a mechanics question. "How do I write a transition against data-starting-style" is Handbook.

How it works

Every page in this group is written to the same six working sections, and they are the same six because they correspond to the six ways a sequence fails.

flowchart TD
A["Reader arrives"] --> B{"Is this the right pattern?"}
B -->|"no"| C["When not to use names the alternative"]
B -->|"yes"| D["How it works: the sequence and its states"]
D --> E["Content: the words, in the order they are met"]
E --> F["Accessibility: focus, announcement, recovery"]
F --> G["Research: why it is shaped this way"]

A pattern page is never a picture of a happy path. The interesting content is concentrated in three places: what the system does when it does not know something, what it does when the reader refuses, and what it does when the reader leaves halfway through and comes back a week later.

How a pattern says what a team can follow

A pattern page carries no status; only a component page does. The question a pattern has to answer is narrower: can a team follow this today?

Most of them can be followed with any component library, including one that is not opsinjs. The form-design and "Ask users for…" families are in that group, and they carry no honesty marker because there is nothing outstanding to mark. A pattern whose assembly nobody has built carries a <Todo> or a <NotBuiltYet> naming the specific gap, and that marker is the thing to read. The reasoning is real either way; the assembly is what varies.

Content

Patterns do not own copy rules. Content & language owns voice, tone and banned words; Numbers, units and precision is canonical for anything numeric; Grammar and mechanics is canonical for capitalisation, punctuation and abbreviation in UI strings.

What a pattern page contributes is sequence: which sentence the reader meets first, what the second screen may assume the first one said, and which words must be repeated because a person arriving from a push notification never saw the first screen at all.

Accessibility

A sequence fails differently from a component. Every screen can pass its own audit and the journey can still be unusable, because the failures live in the joins:

• Focus across a transition. When the second screen replaces the first, focus has to land somewhere deliberate, usually the new heading. If it does not, it returns to the top of the document and a screen-reader user has to re-orient from scratch on every step.
• Announcement of change. A value that updates in place without a status message is invisible to anyone not looking at it. WCAG 2.2 SC 4.1.3 is the floor here, not the ambition.
• Recovery. What happens when the reader gets it wrong on step three, and can they get back to step two without losing what they typed. WCAG 2.2 SC 3.3.7 (Redundant Entry) exists because most products cannot.
• Leaving. Every pattern in this group states where the exit is. A health flow with no exit is a dark pattern regardless of intent.

The per-page accessibility sections here name the specific failure; the general contract is in Accessibility.

Research

Updates to this page

Last read through against the system on 2026-09-20. Due for review every 12 months; expiry is reported by pnpm run check:freshness.