Clinical status semantics

The four status levels steady, watch, attention and urgent. Each has a fixed meaning, a fixed tone, a named threshold owner, and meanings it is never read as.

What this means

opsinjs defines four ordinal clinical status levels: steady, watch, attention and urgent. Each describes the relationship between one value and what is expected for one person, and the set is closed at four. A level is a presentation fact about a reading rather than a clinical fact about the reader, and the adopting product assigns it from a rule that product owns.

The four states in the table below are borrowed from server logging, where they classify what happened to a request and classify it accurately. Applied to a reading about a person's body, each of the four misdescribes it, and each misdescribes it in a different way.

Borrowed log state	What it classifies correctly	Why it misdescribes a person
`info`	A message that reports a state change and asks nothing of the reader.	`info` has no ordinal position, so it cannot be sorted against the other states or counted against an escalation budget, and a health message filed under it says nothing about what the reader should do.
`success`	An operation that completed as requested.	It congratulates someone on a number they may have very little control over, and its absence then reads as failure.
`warning`	A request that completed with a caveat worth recording.	It is a single level, so every non-ideal reading lands in the same bucket as the one that genuinely needs same-day attention.
`error`	A request that did not complete.	Nothing has failed when a reading is high. The value is a fact about a body rather than a bug in a system.

The four levels that replace them are ordinal, so a screen can rank two of them and an escalation budget can be applied to the higher one. Each level is carried by a colour, an icon and a word together, which keeps it readable in a greyscale screenshot and in a screen reader's output. The ladder below renders all four with the colour, the icon, the word and the example sentence each one carries, and with the party entitled to assign it.

1Steady
This reading is where it is expected to be.
Assigned by: The consuming product, from a reference range it owns.
2Watch
This reading is outside your usual range. On its own that is not unusual, and there is nothing to do before your next reading.
Assigned by: The consuming product, from a reference range it owns.
3Needs attention
Contact your care team about this reading. It is outside the range they set for you.
Assigned by: The consuming product, from a clinically reviewed threshold.
4Urgent
Contact your urgent care service now. Tell them this reading and when you took it.
Assigned by: A clinically reviewed threshold with a named clinical owner.

The rule

There are exactly four clinical status levels. They are ordinal, they describe a value's relationship to what is expected, and their meanings are fixed.

`steady`

steady asserts that one value sits inside one range, and it asserts nothing about the person the value came from. A reading can be steady in someone who is seriously unwell, so the level is never available as a summary of how the reader is.

`watch`

watch places no obligation on the reader to act now, which makes the next-step line load-bearing rather than optional: a watch surface states either what the reader should do next or that nothing is needed before the next reading. A watch surface that states neither leaves the reader to decide for themselves what the level asks of them, which is the condition under which a reader contacts a clinician the level did not call for.

`attention`

attention asserts that the number needs looking at by someone qualified, and it asserts nothing about what that person will find. The named action is part of the level rather than an addition to it, so an attention surface carrying no action is incomplete.

`urgent`

urgent is reserved for clinical urgency and is never available to a product's own problems, including those the product owner considers commercially important. What an interface must do at this level, and the wording it uses there, is governed by Emergency and escalation, which is why the table below carries no example sentence for urgent. Alarm fatigue sets the budget that keeps the level meaningful.

The four levels compared

The table fixes each level's meaning, the tone its copy takes and the obligation it places on the reader. None of its cells is a threshold: the relationship column describes a value's position against a range the adopting product owns, rather than a number opsinjs supplies.

Level	Relationship to what is expected	Required tone	Example sentence	What it must never mean	Action expected of the reader
`steady`	The value sits where it is expected to sit, inside the range the product has defined for this reader.	Neutral and unexcited, and never congratulatory.	"In your usual range."	Healthy, safe, normal, good, or "you are fine".	No action today.
`watch`	The value is slightly outside what is expected, or is moving in a direction worth noticing.	Informative rather than anxious.	"A little higher than your usual range."	A mild version of a diagnosis, or a hint that the reader should do something without saying what.	No action now, and no surprise if it comes up next time.
`attention`	The value is outside the expected range far enough, or for long enough, that something specific is due reasonably soon.	Direct and calm, with the action first.	"Book an appointment to have this checked."	An emergency, a diagnosis, or "you have X".	One named action, reasonably soon.
`urgent`	The value may need help today.	Short and unambiguous, with the action in the first line and no hedging or jargon.		Anything that is merely important to the product, such as an expiring trial, an incomplete profile or an unsynced device.	Help today, with the interface saying so and then getting out of the way.

Who assigns a status

The clinically accountable role in the adopting organisation assigns the level, and that named role carries the accountability rather than the implementing developer or opsinjs. opsinjs ships the vocabulary, the tokens, the tone and the presentation rules, and it ships no threshold for any metric, in any population, ever.

A status assignment must be traceable to a rule someone owns and can defend:

The rule is written down outside the component, with its source and its owner.
The rule states the population it applies to, because a threshold set for a 40-year-old does not transfer unchanged to pregnancy, to childhood, or to a long-term condition.
Where a device or a laboratory supplies its own flag, the product uses that flag rather than deriving one, and the surface says whose flag it is.
A status that comes out of a model or an estimate is labelled as such; see Data provenance and device accuracy.

Rules that hold at every level

Status is carried by colour, icon and word together. Colour is never the only carrier, and an element that drops the icon or drops the word has dropped the status.
Motion, sound and haptics never carry a level on their own. Each of the three is a single sensory characteristic, and each may be unavailable to the reader, so none of them may be the only channel carrying the level.
The visible label is the level's meaning in plain words. The word appears on every status surface, is not abbreviated, and is not the token name.
One element carries one level. An element does not carry two statuses, and a container does not inherit the highest status of its children by default.
A change of level is stated in words. Moving a reader from watch to attention between sessions requires saying that the level changed and why it changed.
A status change is announced to assistive technology. The announcement follows the contract on Screen readers: politely for steady and watch, and assertively only at urgent.

Why (evidence)

mixedas at 2026-09-02

Cited. Rules 1 and 2 rest on WCAG 2.2 SC 1.4.1 (Use of Colour) and on the broader requirement that information is not conveyed through a single sensory characteristic. Rule 6 follows the ARIA live-region model rather than our preference: an assertive announcement interrupts, so it is reserved for the level where interruption is warranted.

Opinion. Four levels, and these four names, are our judgement rather than a finding. A three-level scale collapses "worth noticing" into "do something", and we take that distinction to be the one a reader acts on. A five-level scale cannot, in our view, be assigned consistently by different people looking at the same number, and we consider reliable assignment more valuable than resolution.

What would change our mind: field evidence that readers cannot reliably distinguish watch from attention in context would collapse those two levels into one and revise the four-level ladder this page fixes. A comparison study finding that a two-level system (fine / not fine, plus an emergency path) produces better outcomes because it is harder to misuse would replace the vocabulary outright.

Why these four names

The names were chosen to be verbs-adjacent and non-diagnostic, and each was chosen against a named alternative for a different kind of reason.

Chosen name	Rejected alternative	Kind of objection	Reference
`steady`	`normal`	Banned vocabulary. "normal" is banned in any user-facing string that describes a person's own result.	Reference ranges
`watch`	`caution`	Names no action. `caution` describes a posture, where `watch` names what the reader does with the reading.
`attention`	`warning`	Wrong frame. A warning implies a threat, where this level describes a task.
`urgent`		Translation. No gentler word keeps its force across translation.

Applying it

Write an attention surface as "Blood pressure 158/96 mmHg. Higher than your usual range. Book an appointment in the next week to have this checked." It states the value, then its relationship to the reader's usual range, then the action and the window it falls in.

Don’t

Write an attention surface as "Warning: abnormal blood pressure detected." Three things are wrong with it: "abnormal" is a clinical judgement the interface has not earned, "detected" attributes the reading to a machine that has diagnosed something, and no action is named.

Write a steady surface as "72 bpm. In your usual range." and stop there. The surface states the value and its relationship to the range, which is the whole of what steady asserts.

Don’t

Write a steady surface as "Great work! Your heart rate is perfect." It congratulates someone for something they may not control, and it sets up the next reading to feel like a personal failure.

Reserve urgent for clinical urgency and let the product's own problems live at Callout or lower. A sync failure and a dangerously high reading are different kinds of event and take different surfaces.

Don’t

Style a subscription prompt with --opsin-status-urgent-surface. A reader who has learnt that the urgent surface carries commercial messages brings that learning to the next clinical alert, and that erosion is what the budget on Alarm fatigue is set to limit.

Keep the status word in the accessible name: "Needs attention: blood pressure 158 over 96". A screen reader user gets the level and the value in one utterance.

Don’t

Rely on an amber dot with aria-hidden on the icon and no text. The level is then available only to a reader who is sighted and can distinguish the hue, and it is absent from the accessible name entirely.

Components that implement this

Every component that accepts a status takes it from the same four-value union. That union is exported as ClinicalStatus and documented at Types. An invalid level is therefore a type error rather than an unstyled element. The same vocabulary is published as JSON at Machine-readable schemas, so an agent generating a screen enumerates the legal values rather than guessing at them.

What this does not cover

Thresholds. opsinjs does not state which number is watch and which is attention, for any metric, in any population, and that boundary is absolute.
Triage. These four levels are not a triage scale and must not be mapped onto one. Clinical triage systems are validated instruments; this is a presentation vocabulary.
Diagnosis. No level asserts a condition. A product that makes a diagnostic claim is likely to be a medical device, and Regulatory context sets out the frameworks that decide its classification.
The exact sentences. The wording used at each level, including the words banned at each, is set by Writing status and alerts.
Colour values. The palettes, their derivation and their measured contrast are documented on Colour.

Updates to this page

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

Clinical status semantics

On this page