Writing status and alerts

The rule

Every status surface carries a word from a fixed vocabulary, and the word is what makes the colour non-load-bearing. The four levels are steady, watch, attention and urgent, and each one has a sentence shape, a permitted vocabulary and a set of words it may not use.

The canonical definition of the levels lives on Clinical status semantics: what each one asserts, who is allowed to assign it, and what it must never be read as. This page is only about the words.

Three rules govern all four levels.

The level and the wording may never disagree. A banner rendered at watch whose text says "call your doctor now" is a defect of the same class as a wrong number. The level drives the colour, the icon, the announcement politeness and the sentence; if the sentence needs to be stronger, the level was wrong.

The action is a clause, not an implication. "Keep an eye on it" is not an action. "Take another reading tomorrow morning" is. Every level above steady ends with something the reader can do, or with an explicit statement that there is nothing to do.

Escalation is rationed. At most one urgent surface may be on screen at a time, and the budget for the level below it is small. This is a content rule as much as a design rule, because it is writers who escalate wording under pressure to seem helpful. The budget is on Alarm fatigue.

Writing when the news is bad

The hardest case, and the one most style guides skip.

1. Say it in the first sentence. Delay reads as evasion, and a reader who has to scroll to find out whether something is wrong has already assumed the worst.
2. Say what it is, not what it might be. "Your reading was higher than the range your GP set" is a fact. "This could indicate a problem" is a speculation the product is not entitled to make.
3. Do not soften with a compliment. No "you have been doing so well, but". Sandwiching bad news between praise makes the news harder to find and the praise worthless.
4. Give exactly one next step. A frightened reader cannot choose between three.
5. Say what happens if they do nothing, where that is knowable and true. This is usually the most reassuring sentence available, and it is a sentence about the process, not about their health.
6. Never say it is fine. You do not know that.

Approved / Rejected

The last pair shows the sandwich. Both sentences contain the same two facts; only one of them lets the reader find the important one.

Patterns

One pattern per level. The parts in backticks are variables.

steady requires nothing of the reader

Your measure was value unit. That is in your usual range / the range your GP set.

Stop there. No praise, no streak, no encouragement to keep it up.

watch marks a pattern worth noticing and asks for no action today

Your measure has been higher / lower than usual for duration. On its own this is not unusual. Mention it at your next appointment / We will tell you if it continues.

attention names one specific thing to do

Your measure was value unit, which is above / below the named reference. One imperative action. What happens if it is the same again.

urgent means the reader must act now

Imperative action. How to do it. What to say.

No greeting, no product voice, no explanation before the action. Emergency wording specifically is governed by Emergency and escalation, which is canonical, and disclosure of self-harm has its own rules on Crisis and self-harm.

Any level carries the status word itself

Steady · Watch · Needs attention · Urgent

These four words appear verbatim in the interface, and Not known is a fifth word that covers the absence of a reading rather than a fifth degree of urgency. They are not decorated, not translated into a synonym, and not replaced with a symbol. A StatusPill renders one of exactly these, read from CLINICAL_STATUS_META[level].word in lib/status.ts rather than typed into the component. The word and the token id are not the same string, which is the detail people get wrong: the attention level says "Needs attention".

A notification that precedes an in-app alert

What changed. Open app name to see what to do.

A push notification is read on a lock screen, possibly by somebody else, possibly in a queue. It says that something needs attention; it does not say what the value was. See Notifications and off-screen alerts and On-screen privacy.

Banned words

Banned at every level. The attention level's own word, "Needs attention", is exempt from the first row: it is a status label, not the opening of a sentence.

Banned at specific levels:

Related components

• StatusPill renders one status word. The whole colour-independence guarantee rests on that word being present and correct.
• AlertBanner has a level that drives the wording, the colour, the icon and the announcement politeness together; the patterns above are its content contract.
• CareCard carries the action. The "one imperative action" rule is its rule.
• ResultCard says the steady and watch patterns in its body.
• DisclaimerNote is the standing statement of what the product cannot tell the reader, which is what makes the restraint above sustainable.