Colour

Overview

In most design systems colour is presentation. In a system whose reader is looking at their own blood pressure, colour is an assertion. A red surface behind a number says something is wrong with you. A green one says you are fine. Neither of those sentences is one a component library is qualified to say by accident, so opsinjs makes colour a decision rather than a palette you pick from, and that decision carries a stated owner, a stated meaning, and a measured floor.

Two things follow, and they are the whole of this section:

1. Colour comes from exactly one of two axes. Category says what kind of measurement this is. Status says how urgent it is. An element may take colour from one axis; never from both. The full argument, and the vocabulary for the four status levels, lives in Two colour axes. That page is doctrine, and this section is the mechanism that implements it.
2. Every value is derived, not chosen. You give the engine one brand colour. It produces the ramps in OKLCH, clamps each step into the display's gamut, assigns the semantic roles, and then checks every pair it emitted against the published contrast floor. If a pair fails, the derivation fails loudly instead of shipping a theme that is pretty and unreadable.

The thing this is most often confused with is theming. Foundations tells you what a token means; Theming tells you how to change it; Reference is the generated list of every one. If a paragraph here starts explaining how to override something, it is in the wrong pillar.

How it works

The two axes, in tokens

Every colour token in opsinjs is named --opsin-<axis>-<name>-<role>. The axis is category or status; there is no third. The role is one of four, and only four:

So --opsin-status-urgent-ink is guaranteed legible on --opsin-status-urgent-surface, and on nothing else. Pairs are the unit of guarantee; Colour roles states that rule properly and lists what it excludes.

The six categories are sleep, heart, activity, nutrition, mind and labs. The four status levels are steady, watch, attention and urgent, in that order, plus a fifth stem unknown that is the absence of a verdict rather than a fifth degree of one. The two axes are not told apart by chroma: both run the same lightness ladder and the same chroma envelope, so at a given step a category surface and a status surface measure Lc 0.00 and WCAG 1.00 against each other, which is a difference of nothing. They are told apart by role instead. A category paints ink, a line or an accent and never tints a surface, while a status owns the tinted surface, so a card is only ever tinted by a verdict. That asymmetry, role rather than chroma, is the single most important thing about the palette, and Colour roles states it in full.

A second asymmetry catches people in code rather than in prose: the bare Tailwind name resolves to a different role on each axis. bg-status-urgent is the line; bg-category-heart is the accent. Every other role is spelt out.

The derivation engine, in one line

Brand colour → OKLCH → a fixed lightness ladder → per-step chroma clamp to the sRGB gamut → Display-P3 chroma escalation behind a media query → role assignment → APCA validation loop → emitted CSS custom properties.

Each of those stages has a failure mode worth knowing about, which is why How the engine works is a page of its own rather than a diagram here.

Where the values live

Authored input is tokens/color.json. scripts/build-tokens.mts reads it and writes app/tokens.generated.css, which app/globals.css imports at a fixed position. Until that script has run, the authored fallback block in globals.css is what renders. A clean clone therefore looks correct rather than unstyled, and pnpm check:generated fails the build if the two ever disagree.

No colour value on this site is typed into MDX. If you see one, it is inside a fenced code block, illustrating the shape of a declaration.

Using it

Pick the axis before you pick the colour. The question is never "what colour should this card be". It is "is this card identifying a kind of measurement, or delivering a verdict about one". Category and status answer different questions and a surface that tries to answer both answers neither.

Reach for a role, not a step. Product code uses --opsin-status-attention-surface, never a ramp step and never a raw oklch(). The step numbers exist so the engine can talk about itself; they are not an API. The opsinjs ESLint and Stylelint rules described in the Handbook exist to catch the raw value before review does.

Do not add a status level. Four is a design decision with a clinical argument behind it, not a starting point. If you need a fifth, what you almost certainly need is a different component. See Alarm fatigue.

Adding a category is fine. Categories are identity, and a product that measures something we did not anticipate should say so. Category palettes is the supported recipe, and it is supported precisely because a new category cannot contaminate the status axis.

Colour is never the only carrier. A status always ships with a word, and with an icon where the layout allows one. This is not a nicety for a minority of readers; it is what makes the system survive greyscale printing, direct sunlight, a cheap screen and a photocopier. See Colour blindness.

Tokens

Accessibility impact

Colour is the foundation with the largest accessibility surface in the system, and it carries three distinct obligations that people routinely collapse into one:

• Contrast (WCAG 2.2 SC 1.4.3 and 1.4.11). Every emitted pair is measured in both themes by scripts/check-contrast.mts and published in Contrast and APCA. WCAG 2.2 is the conformance obligation; APCA is the tool the engine optimises against. Both are printed, side by side, because they disagree in ways a designer should be able to see.
• Use of colour (SC 1.4.1). No opsinjs component may express state through colour alone. That is a structural rule enforced at the component level, not a guideline. Colour independence is where that rule is written down.
• Adaptation. prefers-contrast: more, forced-colors: active and dark mode are three different requests and the engine owes each a different answer. Dark mode is the one that is fully shipped: it is a re-derivation, not an inversion (Dark mode). prefers-contrast: more is honoured in exactly one place and nowhere else. That place is Surface, which drops its translucent layer under contrast-more:. forced-colors: active is partly answered: Surface draws its edge as an outline, which forced colours keeps and recolours to CanvasText, and it stops rendering the backdrop. The scrim's dimming is still lost, because the system palette replaces the tint with Canvas, and no forced-colours capture exists yet. See Increased contrast.

The failure mode that motivates all of this is specific: a reader with a red-green colour vision deficiency, on a phone at 40% brightness outdoors, glancing at a result. If the only difference between "Steady" and "Needs attention" is hue, that reader gets the wrong answer and acts on it. Those two are precisely the pair the generated audit finds indistinguishable under deuteranopia.

Related

• Two colour axes is the doctrine this section implements, and the argument for why an element may take colour from only one axis.
• Materials is a separate foundation. Colour decides what a surface is; the material ladder decides what is behind it, and the two multiply.
• Theme generator is the same engine, wired to an input box, with the APCA verdict shown as you type.