Colour roles

Overview

A ramp of eleven steps is not a colour system, because it does not tell you which step to use. Roles are the layer that does. The four opsinjs roles are surface, line, ink and accent, and there are four rather than thirty because three is the number of distinct contrast obligations a colour can have, plus one deliberate exception. accent clears no floor of its own: it is chosen for recognition rather than for legibility, which is exactly why it may never carry text and may never be an element's only boundary.

The important idea on this page is not the naming. It is this:

A contrast guarantee attaches to a pair, not to a colour.

--opsin-status-attention-ink is not "an accessible colour". It is the foreground half of a measured pair whose background half is --opsin-status-attention-surface. Put it on anything else and you have left the guarantee behind.

Everything below follows from that sentence.

How it works

The four roles

line and ink are separate roles rather than one "foreground" role because their floors differ, and collapsing them means either over-darkening every chart stroke or under-darkening every label. A stroke that is 2px wide and 40px long is not held to the same figure as a 15px sentence, and pretending otherwise produces a system whose charts are muddy.

The naming grammar

--opsin-<axis>-<name>-<role>

axis  ∈ { category, status }
name  ∈ { sleep, heart, activity, nutrition, mind, labs }   when axis = category
      ∈ { steady, watch, attention, urgent, unknown }       when axis = status
role  ∈ { surface, line, ink, accent }

unknown is a fifth status stem and deliberately not a fifth level. It is the absence of an assertion, which covers a reading never taken, a stale reading, or a reading whose reference range the product does not own. It is therefore never ordered against the four; see Two colour axes.

There is no fourth segment. No -hover, no -subtle, no -2. Interaction states are derived from the role token at use time, in OKLCH, by the rules in Interaction states. They are not additional tokens, because a hover variant of every role on every one of the eleven stems is another forty-four tokens nobody can hold in their head.

Tailwind utilities are exposed for each token through @theme inline, so bg-status-attention-surface and text-status-attention-ink resolve to the same custom properties and follow the theme, the gamut escalation and the media-query overrides automatically. Two of those utilities are shorter than they look, and the two axes disagree about which role the bare name means: bg-status-urgent resolves to the line, bg-category-heart resolves to the accent. The other roles are always spelt out. Raw var() access is supported for consumers who are not on Tailwind; see CSS variables.

The category axis also exposes one role fewer, and this is the rule that keeps the two axes apart. surface is bridged to a utility only on the status axis, so a status can tint a card with bg-status-attention-surface while a category has line, ink and accent and no surface utility to reach for. The reason is not chroma. Both axes 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 no difference a reader could use. So a category paints a stroke, a word or an identity fill and never a tinted card, and only a status owns the tinted surface. A category surface value still exists as the measurement reference its ink is gated against, and it is what the ramp specimen shows, but nothing paints a card with it.

Chrome roles are a separate namespace

Alongside the two axes there is an ordinary application palette. --background, --foreground, --card, --muted, --muted-foreground, --border and --input are inherited from the shadcn convention so that a team already using it is not asked to relearn anything. These seven are unprefixed on purpose: they are the neutral system, they carry no clinical meaning, and they are the correct default for almost everything on a screen.

Two more roles ship under the same convention and are not neutral. --ring and --primary are a brand blue, seeded at chroma 0.13 and 0.135, which is as chromatic as the category axis, whose labs seed sits at 0.11 and whose heart seed at 0.17. Calling them neutral would be wrong. They carry no clinical meaning either, but they are a third saturated presence on the screen, one that competes with both measurement axes for the reader's eye, so a focus ring or a primary button is a deliberate accent rather than a quiet default. Whether the chrome palette should stay this chromatic is a design question the system has not yet closed.

The --opsin-* tokens are the exception you reach for when the element is genuinely saying something about a measurement.

If most of your screen is coloured from the two axes, the screen is shouting. See Alarm fatigue.

The declared pair set

scripts/check-contrast.mts measures a declared list of pairs, in both themes and in sRGB. Each measured pair is gated, advisory or exempt, the three states Contrast and APCA defines, and the clauses below say which state each pair takes rather than restating what the states mean. The list is, exactly:

1. every ink against the surface of the same axis and name, at the body-text floor;
2. every line against that same surface, at the non-text floor;
3. every accent against that same surface and against the page, at the non-text floor and advisory rather than gated, because an identity fill is chosen for recognition and is not something a reader has to read;
4. every ink against the page, at the body-text floor, because a status or category word frequently sits on the page rather than on its own tint;
5. the neutral roles: body text and secondary text against the page at the body-text floor; the card hairline and the focus ring against both the page and a card at the non-text floor, gated on the chrome tokens the theme renders; and one grouping hairline between list rows against the page, left advisory because a row divider carries no meaning that SC 1.4.11 covers;
6. body text against every material rung's opaque fallback, scrim excepted because nothing is written on a dimmer (see The contrast floor).

"The page" in clauses 3 to 6 is --opsin-chrome-background, which resolves to --opsin-neutral-50 in light and --opsin-neutral-950 in dark. It is not --card, which is --opsin-chrome-card and resolves to --opsin-neutral-0 in light and --opsin-neutral-900 in dark. In both themes the card sits one ladder step lighter than the page, so a card is one step away from the measured pair rather than inside it.

Anything not on that list is unmeasured. Unmeasured is not the same as failing, because an unmeasured pair may well be fine. It is still not something this system is promising you, and a health product should not be built on a promise nobody made. The focus ring used to be the gap worth knowing about, and it no longer is: --ring against the page and against a card is measured and gated in both themes, on the chrome tokens the theme actually renders, so the boundary a keyboard reader depends on is now something the system checks rather than something it hopes.

The neutral and chrome pairs, measured in both themes, render below. The card hairline rows sit in the neutral scope, and the focus ring rows in the chrome scope, because the ring is a chrome role rather than a neutral one.

Using it

Use a whole pair or neither half. A status or category word on a neutral card is ink, not line: ink against the page is clause 4, measured and gated in both themes, while line is tuned to the non-text floor, so moving a word onto it lowers the contrast the reader actually gets. Two cautions come with that. The measured ground is the page rather than --card, which is the same colour in light and one step lighter in dark, so in dark a word on a card inherits a guarantee made a step away from it. And line on a neutral ground is not measured at all. It is the role for a stroke, a boundary or a chart mark, and its floor is guaranteed only against its own surface.

Never take ink from one axis onto a surface from the other. Heart ink on an urgent surface is both an unmeasured pair and a violation of the never-mix rule in Two colour axes. It is the most common way the axis invariant is broken in practice, because each half looks defensible on its own.

Do not invent a role to solve a layout problem. If a surface needs a slightly different tint to separate it from its parent, the answer is a material rung or a border, not a new colour token.

Extending is a supported operation; redefining is not. Adding a seventh category adds four tokens and no risk, because categories carry no verdict. Redefining a status role changes what the product asserts about somebody's health, which is why Status palettes exists as a page-length argument rather than a recipe.

Tokens

Accessibility impact

The pair rule is the accessibility mechanism on this page, and it has a consequence people find unintuitive: a token cannot be accessible on its own. Contrast is a relationship. A design review that says "this colour passes" has not said anything checkable, and a token table that prints a single contrast number per colour is printing a number against an assumed background it did not declare.

That is why Contrast and APCA and every <ContrastReport> on this site print a pair, a theme and a floor, and why <TokenSwatch> shows a token's resolved value in both themes together with the pair it was measured in.

Two related obligations sit with the implementer rather than with the tokens:

• The line role is not a text role. If you set body copy in a line colour it may well be below the text floor. The role name is the warning.
• Icons that carry words are ink, not line. An icon whose meaning is duplicated by adjacent text is decorative and may use line; an icon that is the only carrier of a piece of information is text as far as WCAG 2.2 SC 1.4.3 is concerned, and it should not exist at all under Colour independence.

Related

• How the engine works covers both stages. Stage 6 is where a ramp becomes these four roles, and stage 7 is where the pairs are validated.
• Interaction states explains why hover, press and selected are derived at use time rather than shipped as more tokens.
• Token architecture has the three-tier model, and the rule that a component never references a primitive.