Health
Two colour axes
Category colour says what a measurement is about and status colour says how urgent it is. They never meet on one element.
Identity lets a reader find the sleep tile at a glance, and status says whether its reading needs anything. Each axis has its own palette and its own token namespace.
The rules
Axes
- No element is tinted by both axes or resolves a colour from both
--opsin-category-*and--opsin-status-*. A card may have a category-tinted header and a status-tinted badge, but never a blend. - A category colour never changes with a value or a status, and a status colour never changes hue with a category.
- Status is never expressed by colour alone. Every status carries a colour, an icon and a word together, and an element that drops the icon or the word has dropped the status.
- Motion, sound and haptics never carry a level on their own.
Status
- There are exactly four levels. They are ordinal and their meanings are fixed.
unknownis the absence of an assertion, not a fifth level, and is never coloured nearwatch. - The level's word appears in full on every status surface and in its accessible name, never as the token name.
- One element carries one level. A container never inherits its children's highest status by default.
- A change of level is stated in words, saying that it changed and why.
- A status change is announced to assistive technology politely, and assertively only at
urgent. urgentis reserved for clinical urgency and never carries a product's own problem. Informational messages go in Callout, which has nostatus,severityorcolorprop.- The levels are not a triage scale and are never mapped onto one. No level asserts a condition.
Category
- A category colour identifies a family. It never expresses value, quality, severity, direction, urgency or brand.
- A category colour is never the only cue. Every category-coloured element names the family in text.
- A category namespace never gains a role that carries a verdict, such as
--opsin-category-heart-danger. - A category colour is never a brand accent or a chart series colour. Series use the ramps in Data visualisation.
- One metric takes one category on every surface in the product.
Heart
148/92
Blood pressure, resting heart rate, rhythm
Status levels
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.
Simulated with SVG colour matrices. The design question is whether this can still be read without hue, and the simulation is close enough to answer that. It is not a clinical instrument. The audited version is lib/color/cvd.ts.
| Level | Word and icon | Asserts, and its tone | Never means |
|---|---|---|---|
steady | Steady, Circle | Inside the range set for this reader. Neutral, never congratulatory | Healthy, safe, normal, good, "you are fine" |
watch | Watch, CircleDot | Slightly outside the usual range, or moving in a direction worth noticing. Informative, and says what happens next or that nothing is needed | A mild diagnosis, or a hint to act without saying how |
attention | Needs attention, Diamond | Someone qualified should look, reasonably soon. Direct and calm, with one named action first, and incomplete without it | An emergency, a diagnosis, "you have X" |
urgent | Urgent, Octagon | The value may need help today. Short and unambiguous, with the action in the first line | Anything merely important to the product, such as an expiring trial or an unsynced device |
unknown | Not known, Minus | Nothing. No reading, a stale one, or a range the product does not own | "Probably fine" |
Your clinically accountable role assigns every level, and opsinjs ships no threshold for any metric, in any population, ever. steady and watch come from a reference range your product owns, attention from a clinically reviewed threshold, and urgent from one with a named clinical owner. Each traces to a rule written down outside the component with its source, owner and population. Use a device's or laboratory's own flag where one exists and say whose it is, and label a model's output as an estimate.
Category identity
| Category | Covers |
|---|---|
| Heart | Blood pressure, heart rate, resting heart rate, rhythm, variability, circulation |
| Activity | Steps, workouts, active minutes, movement, energy expenditure |
| Sleep | Duration, timing, consistency, disturbance, sleep-derived recovery |
| Nutrition | Intake, hydration, glucose, cholesterol, weight, body composition |
| Mind | Mood, stress, cognition, wellbeing check-ins |
| Labs | Test results, panels, assays, anything a laboratory reports |
A result's interpretation is status, never Labs. Where a metric fits two families, as weight and glucose do, your product picks one and opsinjs does not adjudicate. Symptoms, medications and appointments take no category colour. There is no Cycle category, and adding a seventh is a design-system decision shown in Theming.
Tokens
Both axes expose four roles, under --opsin-category-<name>-* and --opsin-status-<level>-*: -surface for the ground, -line for strokes and badge edges, -ink for text and meaningful icons, and -accent for identity fills and chart marks. Only -ink carries text, and text on a -surface is always the matching -ink. A bare bg-status-urgent resolves to the line and a bare bg-category-heart to the accent, so spell every other role out. Contrast floors are in Colour.
Enforcement
- The two namespaces are disjoint, so a mixed colour has to be assembled by hand.
- A component that takes a
statustakes nocategoryfor the same painted surface. - Every component that accepts a status, StatusPill included, takes it from the exported
ClinicalStatusunion in Types, so an invalid level is a type error. scripts/check-contrast.mtsprojects both axes through protanopia, deuteranopia, tritanopia and greyscale, and lists every collapsing pair in Contrast.- The lint rule
opsinjs/no-mixed-axesis specified and not written, so a mixed axis on a hand-written surface is caught in review or not at all.
Evidence
- WCAG 2.2 success criterion 1.4.1 (Use of Colour), with the requirement that information is not conveyed through a single sensory characteristic, is the basis for rules 3 and 4.
- The ARIA live-region model is the basis for rule 9, because an assertive announcement interrupts.
Everything else is opinion, including the two axes, the six categories and the four levels. No study comparing a two-axis palette with a merged one is cited, and the recognition speed category colour is kept for is unmeasured.