---
title: "Writing status and alerts"
description: "One sentence pattern per clinical status level, the words banned at each, and how to write when the news is bad."
url: "https://opsinjs.pensievelabs.org/content/writing-status-and-alerts"
source: "https://opsinjs.pensievelabs.org/content/writing-status-and-alerts.md"
section: "Content & language"
kind: "content"
reviewed: "2026-09-20"
reviewer: "content"
aliases: ["alert copy", "warning wording", "escalation copy", "breaking bad results"]
---
> Elements written as `` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> Nothing is missing from this page. The data simply does not live in
> the prose.
## The rule [#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](../health/clinical-status-semantics.mdx): 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](../health/alarm-fatigue.mdx).
### Writing when the news is bad [#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.
The rule we would defend hardest: **no health product may tell a reader that a
result is nothing to worry about.** It may tell them how common something is,
what the next step is, and who can interpret it. The difference between those and
reassurance is the difference between describing and diagnosing, and only one of
them is available to software that is not a medical device.
## Approved / Rejected [#approved--rejected]
Your reading was 152 over 96. That is higher than the range your GP set for you. Take another reading tomorrow morning before breakfast. If it is still above that range, book an appointment.
Warning! Elevated blood pressure detected. This could indicate hypertension. Please consult a healthcare professional.
Your readings have been a little higher than usual for the past week. This is worth mentioning at your next appointment.
Attention needed: your 7-day average has exceeded threshold.
Your reading was 118 over 74. That is in your usual range.
All good. Nothing to see here!
You have been doing well and your average is down. Your reading this morning was higher than usual.
You have been doing so well! Unfortunately your reading this morning was very high. But keep going, you have got this!
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 [#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](../health/emergency-and-escalation.mdx), which is
canonical, and disclosure of self-harm has its own rules on
[Crisis and self-harm](../health/crisis-and-self-harm.mdx).
**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](../health/notifications-and-off-screen-alerts.mdx)
and [On-screen privacy](../health/on-screen-privacy.mdx).
## Banned words [#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 | Why | Use instead |
| ------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
| warning, alert, attention (as the opening word of a sentence) | A label where a sentence is needed; adds urgency without information. | say what happened |
| detected, flagged, triggered | Machine register; puts an algorithm between reader and data. | your reading was |
| could indicate, may suggest, is consistent with | Clinical inference the product is not entitled to make. | describe the reading and name who can interpret it |
| threshold, exceeded, out of bounds | Systems language for a health fact. | higher than the range your GP set |
| nothing to see here, all good, you're fine | Reassurance without grounds, and it fails the moment it is wrong. | the fact, stated plainly |
| please | Softener that lengthens the sentence at the moment it must be shortest. | the imperative |
Banned at specific levels:
| Level | Additionally banned | Why |
| ----------- | --------------------------------------------------------- | ----------------------------------------------------------------- |
| `steady` | well done, great, streak, on track, keep it up | Turns a body into a score, and creates an implicit failure state. |
| `watch` | any imperative verb | If there is something to do, the level is `attention`. |
| `attention` | urgent, emergency, immediately, right now | Reserved for `urgent`. Using them here destroys the distinction. |
| `urgent` | might, could, consider, we recommend, as soon as possible | Hedging at the one moment hedging costs something. |
## Related components [#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.