Contrast and APCA

Overview

There are two ways to put a number on how readable text is against its background, they disagree, and most design systems quietly pick one and hope nobody notices. opsinjs publishes both, for every measured pair, in both themes, and states which one it is bound by:

WCAG 2.2 is the obligation. APCA is the tool.

A pair ships only if it clears the WCAG 2.2 requirement, because that is what conformance, procurement and the law are written against. APCA is what the derivation engine optimises with, and it is published so that a designer can see the cases where a pair is technically conformant and still hard to read.

The thing this is most often confused with is a contrast checker. A checker tells you about one pair you thought to check. This page is about a floor that is applied to the whole declared pair set, measured in CI, with the gated set held against regression by a nightly run, so that nobody has to remember to check.

How it works

WCAG 2.2 contrast ratio

The ratio is computed from relative luminance:

ratio = (L_lighter + 0.05) / (L_darker + 0.05)

where L is relative luminance from the sRGB channel values after linearisation. It runs from 1:1 to 21:1. Its properties, stated without enthusiasm:

• It is symmetric. Black text on white and white text on black score identically, although they do not read identically, particularly at small sizes where light-on-dark halates.
• It is size-blind except for one carve-out, so 14px and 40px text are held to the same figure. The carve-out is the 3:1 allowance for large text.
• The + 0.05 constant compresses the dark end, which is why two dark greys that are visibly different can score almost identically, and why dark themes are the ones that most often look fine and measure badly.

It is nonetheless the number that matters, because SC 1.4.3, SC 1.4.11 and every conformance claim built on them are written in terms of it.

APCA lightness contrast (Lc)

APCA is the Accessible Perceptual Contrast Algorithm, developed as part of the work toward WCAG 3, and it produces a value called Lc on a roughly 0 to 106 scale. It differs from the ratio in three ways that matter:

• It is polarity-signed. Dark text on a light background gives a positive Lc; light text on a dark background gives a negative one. The two are not interchangeable, and the model says so.
• It is size- and weight-aware. The published guidance is a lookup table: the Lc you need depends on the font size and weight you are actually using, so a 40px result value and a 13px unit label are not asked for the same number.
• It behaves sensibly at the ends. Two dark greys that WCAG 2.2 cannot tell apart have visibly different Lc.

The important caveat, and it is the reason APCA is not our gate: APCA is a draft. It is not a normative part of WCAG 2.2, its lookup tables have changed across revisions, and a conformance claim cannot be built on it today. We therefore pin our own Lc thresholds in tokens/color.json, record the date we pinned them, and re-examine when the upstream draft moves. We do not import a moving target into a health product's safety argument.

The published floor

These are thresholds we adopt, not measurements. They are what scripts/check-contrast.mts tests every declared pair against, in light and dark. Where the two models disagree, both have to pass.

Two of those rows are opinions rather than requirements and are marked as such:

The floor above is not a single switch. Every measured pair sits in one of three states, and whether a pair that falls below its floor blocks a build depends on which. The tables further down print each pair as Pass or Below floor without naming its state, so the three are defined here.

Gated. The pair is in the regression baseline. A commit that drives it below its floor fails the nightly regression run. Body text, an ink role against its own surface or against the page, and the neutral hairlines are gated, because a reader has to read them or leans on them to tell two regions apart.

Advisory. The pair is measured and published, but it sits outside the regression baseline, because it carries recognition rather than words. An accent fill is the case: it may never carry text and may never be an element's only boundary, so the nightly regression run does not block on it. A non-text advisory pair that measures below its floor does fail the --strict run, and its count is published beside the "failing" figure, so a "0 failing" total can never stand on its own while an accent or a hairline sits below the non-text floor.

Exempt. The pair is outside the floor's scope, and the reason sits beside it. A band fill measured against the page, a status tint measured on a card, a status ring measured against its own surface, and a placeholder fill on the page are exempt: none of them is text, and none is the only thing separating two regions, so no floor applies.

Where the numbers on this site come from

Every figure published on this site is measured, in CI, by hand-written implementations of both models in lib/color/, and rendered by <ContrastReport>. None is typed by a person, and a regression is caught by the nightly run rather than by an individual pull request. The current results for the two clinical axes:

Using it

Check a pair now

The oracle takes any two colours, prints both models, and states the verdict against the floor above. It is the same code path the build uses. If it and the build disagree, that is a bug in this repository, not a rounding difference.

How to read a disagreement

The two models disagree most often in three situations, and each has a different correct response.

Passes WCAG, low Lc. Usually a dark-on-dark pair in a dark theme, where the + 0.05 constant is flattering it. Trust Lc; the pair is genuinely hard to read. This is the single most common way a dark theme ships worse than its light counterpart.

Fails WCAG, comfortable Lc. Usually large, bold, dark-on-light type. It may well be perfectly readable, and you still cannot ship it, because the obligation is the ratio. Adjust the colour.

Both pass, still looks wrong. Check what is actually behind the text. If the answer is a translucent surface, an image or a video, neither number applies, because both models assume a known, opaque background. That case is The contrast floor.

Rules of thumb that are actually true

• Contrast is a property of a pair, so never say "this colour passes".
• Fixing contrast by lightening the background changes the design; fixing it by darkening the foreground usually does not. The engine only ever moves the foreground for the same reason.
• Opacity on text is a contrast change. text-foreground/70 is a new, unmeasured colour, and it is the most common accidental floor violation in Tailwind codebases.
• Placeholder text is text. So is a disabled label somebody still has to read to understand why the control is disabled.

Tokens

Accessibility impact

This page is the accessibility impact of the colour system, so what follows is the boundary rather than a restatement.

What is guaranteed. The gated set clears both models at the floor above, in both themes and in sRGB. The nightly run measures the whole gated set and fails on any pair that has dropped below its floor, so a regression is caught within a day rather than on the commit that introduced it. Advisory pairs are published as well, and one may sit below its floor: the number that do is printed beside the "failing" figure in the summary, so a clean total never hides a sub-floor accent or hairline. Exempt pairs are outside the floor's scope by design. The list of declared pairs, and which state each takes, is enumerated in Colour roles, and the measured results are published, dated, on Contrast conformance.

What is not guaranteed, and is yours.

• Any pair you assemble that is not in the declared set.
• Text over imagery, video, gradients or any translucent surface.
• Text you have made semi-transparent.
• Text rendered at a weight or size other than the one the row above assumes. Lc is size-aware and a thin 12px label is not the same problem as a 15px regular one.
• forced-colors: active, where the operating system replaces the palette entirely and the only thing that survives is your markup.

What contrast does not fix. Meeting the floor does not make a colour-coded status accessible; it makes it visible. A reader who cannot distinguish the four hues gets no benefit from any of these numbers, which is why the four levels always ship with a word. See Colour independence.

Related

• Colour blindness has the redundancy requirement that contrast alone cannot satisfy.
• The contrast floor covers the same problem when the background is not a known colour, and the worst-case composite that replaces it.
• Contrast conformance is the dated, generated conformance record for the whole token set.