Recipes
Task-first builds gather the components, tokens, copy and safety checks for one job into one scroll.
Overview
A component reference answers "what is this thing?". A recipe answers the question people actually arrive with: "I have a blood pressure reading and a reference range. What do I put on the screen?" Every surveyed design system documents the first question well and the second one barely at all, which is why the same three mistakes keep being shipped: a value with no unit, a range with the word normal in it, and a red banner used for something that is not urgent.
A recipe is one task. It names the components and tokens involved, the order to assemble them in, the words that go on the screen, and the safety and accessibility checks that specific task can fail. It ends where the task ends. That is not the last instruction, but the point where you can tell for yourself whether you got it right.
Recipes sit in the middle of a three-layer split that the whole site follows:
- Foundations says what a token means.
- Handbook and Theming show how you change it.
- Recipes say what to assemble for one job. Patterns are the same job at flow scale; Screens are the whole surface.
If you are choosing between a recipe and a pattern: a recipe fits in one scroll and produces one composed thing. A pattern spans several screens and describes a sequence of decisions.
The parts install; the recipes are still specifications
Every component a recipe names is shipped. They are installable, and
free to change their API in any release, and none of them has been reviewed.
Each recipe's What you need table
carries the current status of every part, and that table is the thing to trust; no
recipe restates a count in prose. What a recipe itself contains is a specification of
the build, not a transcript of one: it tells you what to assemble and why, and
it deliberately holds no code you could paste, because a recipe that names the
wrong component or approves the wrong sentence would be wrong whether or not the
code beneath it existed.
What a recipe contains
Every recipe has the same seven sections, in the same order, so you can skim to the one you need.
| Section | What it is for |
|---|---|
| The task | The goal in the reader's terms, and the situation that produces it. If your situation is not this one, stop here. |
| What you need | The components and tokens involved, each with its status, so you can see immediately how much of this is real. |
| Build it | The ordered steps, each with the reasoning that lets you adapt it rather than copy it. |
| The copy | The words on the screen and the rule each one follows. Health UI fails in its sentences at least as often as in its markup. |
| Get it right | The safety and accessibility checks this task can fail, phrased so you can run them. |
| Variations | The near-miss versions of the task and how each changes the steps. |
| Related | Where to go next, with the reason to go there. |
Two conventions are worth knowing before you read one:
A recipe carries no status of its own. Only a component page does. However
finished the writing is, and however much of the component roster is now
installable, no recipe has been assembled and reviewed end to end as a working
example, and each says so in its own <Todo> or <StubNotice>. The per-part
statuses in What you need are the ones that tell you what will compile.
Recipes name components; they never define behaviour. If a recipe seems to be inventing a rule, it is quoting one. The rule lives in Health or Content & language and the recipe links to it. Where the two disagree, the doctrine page wins and the recipe is a bug.
The recipes
Start with Choose a component if you are not sure what you are building yet. It is the only recipe whose output is a decision rather than a surface, and every other recipe assumes you have already made it.
The remaining six are ordered from the most common job to the least:
- Build a health metric card puts one number on a dashboard, with its unit, its age and its category.
- Show a value against a reference range is the highest-stakes display in the system, and the one with the most ways to imply a diagnosis by accident.
- Capture a daily log entry covers repeated one-handed entry, where friction decides whether the data exists at all.
- Show a trend with an honest caption separates the direction of a change from whether it is good news.
- Escalate an alert without alarming covers the escalation ladder and the per-screen budget that stops it collapsing into noise.
- Ask for consent before collecting keeps consent granular, revocable and recorded, asked at the moment of value.
Recipes we have not written yet
These are known gaps, listed here rather than left to be discovered. Each is a real task that a health product has to solve and that no recipe currently covers end to end.
Disclose a result somebody may not want to see. The moment between tapping a notification and reading an out-of-range result. Covered as a flow in Result disclosure; not yet as a build.
Explain a number in plain English. Turning a measured value into a sentence a reader without numeracy confidence can act on. The vocabulary exists in Plain-English A to Z and the formatting rules in Numbers, units & precision; the assembly step between them is unwritten.
Show data you cannot vouch for. Stale, partial and estimated values on a screen that also carries fresh ones. The states are defined in Data states and the doctrine in Uncertainty & staleness; the recipe that composes them is missing.
A today screen. The dashboard that most consumer health apps open on. The five Screens specimens do not include one, which is the largest single gap in the specimen set.
Verify it worked
You have read a recipe correctly if you can answer these three questions about what you just built, without looking anything up:
- Which axis is each colour on? Every coloured element on the screen is either identifying a category or grading a clinical status, never both. If you cannot say which, read The two colour axes before you ship.
- What does the screen say if the colour is gone? Turn the screen grey. The status must still be legible from the word and the icon. This is the single check that catches the most defects.
- Who assigned the status? Not the component, and not the recipe. A clinical rule owned by your product assigned it, and you can name where that rule lives. If the answer is "the UI decided", you have shipped an unlicensed clinical judgement.
Troubleshooting
"The recipe uses a component that does not exist." Check its chip in What
you need. A shipped chip means the code is there and the install command on
the component's own page will fetch it. No recipe shows a planned chip today.
Were one to appear it would mean a specification with nothing behind it yet, and
you would reach for a deliberate substitute rather than invent an API that
happens to share the name.
"The recipe and a component page disagree." The component page wins on the component's own API and anatomy; the doctrine page wins on the rule. Recipes are the layer most likely to drift, so please report it rather than picking one.
"My data does not match any recipe." Read Choose a component. It covers several shapes that have no recipe yet, and names the shapes that have no component either.
"I need to change a token to make this work." Then the recipe is probably wrong for your case, or the token is. Recipes never instruct you to override a token; if you need to, Theming is the place, and Adding your own tokens is the way that survives an upgrade.
Next
- Choose a component is the decision table, if you do not know what you are building yet.
- Screens covers the same components composed into whole surfaces, which is where a correct component and a wrong page order still produce an unusable result.
- Safety review checklist is the pre-ship pass for anything that puts a health value on a screen.