Skip to content
opsinjs
Edit this page

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

  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

  1. 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.
  2. The level's word appears in full on every status surface and in its accessible name, never as the token name.
  3. One element carries one level. A container never inherits its children's highest status by default.
  4. A change of level is stated in words, saying that it changed and why.
  5. A status change is announced to assistive technology politely, and assertively only at urgent.
  6. urgent is reserved for clinical urgency and never carries a product's own problem. Informational messages go in Callout, which has no status, severity or color prop.
  7. The levels are not a triage scale and are never mapped onto one. No level asserts a condition.

Category

  1. A category colour identifies a family. It never expresses value, quality, severity, direction, urgency or brand.
  2. A category colour is never the only cue. Every category-coloured element names the family in text.
  3. A category namespace never gains a role that carries a verdict, such as --opsin-category-heart-danger.
  4. A category colour is never a brand accent or a chart series colour. Series use the ramps in Data visualisation.
  5. One metric takes one category on every surface in the product.
Category only. Identity, no verdict.

Heart

148/92

Blood pressure, resting heart rate, rhythm

Status levels

Colour vision simulation
  1. 1Steady

    This reading is where it is expected to be.

    Assigned by: The consuming product, from a reference range it owns.

  2. 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.

  3. 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.

  4. 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.

LevelWord and iconAsserts, and its toneNever means
steadySteady, CircleInside the range set for this reader. Neutral, never congratulatoryHealthy, safe, normal, good, "you are fine"
watchWatch, CircleDotSlightly outside the usual range, or moving in a direction worth noticing. Informative, and says what happens next or that nothing is neededA mild diagnosis, or a hint to act without saying how
attentionNeeds attention, DiamondSomeone qualified should look, reasonably soon. Direct and calm, with one named action first, and incomplete without itAn emergency, a diagnosis, "you have X"
urgentUrgent, OctagonThe value may need help today. Short and unambiguous, with the action in the first lineAnything merely important to the product, such as an expiring trial or an unsynced device
unknownNot known, MinusNothing. 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

CategoryCovers
HeartBlood pressure, heart rate, resting heart rate, rhythm, variability, circulation
ActivitySteps, workouts, active minutes, movement, energy expenditure
SleepDuration, timing, consistency, disturbance, sleep-derived recovery
NutritionIntake, hydration, glucose, cholesterol, weight, body composition
MindMood, stress, cognition, wellbeing check-ins
LabsTest 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 status takes no category for the same painted surface.
  • Every component that accepts a status, StatusPill included, takes it from the exported ClinicalStatus union in Types, 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.
  • 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

  • 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.