---
title: "Two colour axes"
description: "Category colour says what a measurement is about and status colour says how urgent it is. They never meet on one element."
url: "https://opsinjs.pensievelabs.org/docs/health/two-colour-axes"
source: "https://opsinjs.pensievelabs.org/docs/health/two-colour-axes.md"
section: "Health"
kind: "health"
evidence: "mixed"
reviewed: "2026-10-08"
reviewer: "design"
aliases: ["status levels", "category colour"]
implements: ["status-pill", "alert-banner", "range-bar", "result-card", "care-card", "metric-tile", "score-dial", "trend-sparkline", "range-legend", "body-map", "goal-ring", "card", "surface"]
---

> Elements written as `<PascalCase … />` 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.

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 [#the-rules]

### Axes [#axes]

1. 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.
2. A category colour never changes with a value or a status, and a status colour never changes hue with a category.
3. 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.
4. Motion, sound and haptics never carry a level on their own.

### Status [#status]

5. There are exactly four levels. They are ordinal and their meanings are fixed. `unknown` is the absence of an assertion, not a fifth level, and is never coloured near `watch`.
6. The level's word appears in full on every status surface and in its accessible name, never as the token name.
7. One element carries one level. A container never inherits its children's highest status by default.
8. A change of level is stated in words, saying that it changed and why.
9. A status change is announced to assistive technology politely, and assertively only at `urgent`.
10. `urgent` is reserved for clinical urgency and never carries a product's own problem. Informational messages go in [Callout](../components/callout.mdx), which has no `status`, `severity` or `color` prop.
11. The levels are not a triage scale and are never mapped onto one. No level asserts a condition.

### Category [#category]

12. A category colour identifies a family. It never expresses value, quality, severity, direction, urgency or brand.
13. A category colour is never the only cue. Every category-coloured element names the family in text.
14. A category namespace never gains a role that carries a verdict, such as `--opsin-category-heart-danger`.
15. A category colour is never a brand accent or a chart series colour. Series use the ramps in [Data visualisation](../foundations/data-visualisation.mdx).
16. One metric takes one category on every surface in the product.

<StatusAxisDemo />

## Status levels [#status-levels]

<CvdSimulator>
  <StatusLadder />
</CvdSimulator>

| 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-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](../theming.mdx).

## Tokens [#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](../foundations/colour.mdx).

## Enforcement [#enforcement]

* The two namespaces are disjoint, so a mixed colour has to be assembled by hand.
* A component that takes a `status` takes no `category` for the same painted surface.
* Every component that accepts a status, [StatusPill](../components/status-pill.mdx) included, takes it from the exported `ClinicalStatus` union in [Types](../reference/generated/types.mdx), so an invalid level is a type error.
* `scripts/check-contrast.mts` projects both axes through protanopia, deuteranopia, tritanopia and greyscale, and lists every collapsing pair in [Contrast](../reference/generated/contrast.mdx).
* The lint rule `opsinjs/no-mixed-axes` is specified and not written, so a mixed axis on a hand-written surface is caught in review or not at all.

## Evidence [#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.
