Keep the colour. Move the lightness.

Almost every contrast snippet on the web answers one question: given a background, should the text be black or white? That question has a tidy shape.

(background) → black | white

But the question I actually ask, and the one I hear designers ask, is a different one: I picked this colour, it isn’t readable on that background, give me the nearest version of it that is.

(foreground, background, target) → foreground′

The second signature takes the foreground as an argument. The first one does not. That is the whole difficulty in one line, and it took me an embarrassingly long time to see it: no amount of improving the first function ever turns it into the second, because the colour you are trying to keep is not even in the room. This page works through both, in order, the easy one first and honestly labelled as easy.

Everything on it is live. The swatches, the six cases and the five approaches in the lab all compute against whatever the controls say, and the panes that demonstrate CSS carry the real declarations rather than a drawing of them.

It takes a colour and returns black or white, whichever contrasts more, white on a tie. I checked it against the exact luminance threshold, the one part one derives below, over 1.89 million colours and found zero mismatches, which is unsurprising once you see it: it is that formula, in C++, running in the style engine before paint. That makes it strictly better than anything I could hand-roll. No main-thread work, no bundle, no reimplementation of mine to get wrong. If ink is genuinely all you need, stop reading and use it.

The last line of each swatch is the one nothing above it can produce: the colour itself, moved until it is readable on itself. Same hue, same chroma, only the lightness changed, and still recognisably the colour you started with rather than the black or white that replaced it three lines up. That is the whole point of this page, and part two is how it is done.

What the YIQ formula actually is

The snippet everybody has pasted at least once computes this, and compares it to 128.

(r × 299 + g × 587 + b × 114) / 1000

It is worth being precise about what that number is, because it is not luminance and it never was. It is the Y channel of NTSC’s YIQ colour space, a 1953 broadcast trick that let one signal serve colour and black-and-white sets at once, on analogue hardware where a squaring circuit was an expensive thing to ask for. Three consequences follow, and they compound rather than cancel. It is applied to gamma-encoded values, with no linearisation step, so what comes out is neither physical light nor perceptual lightness but a number in between that is neither. The coefficients are for the wrong primaries: 0.299, 0.587 and 0.114 are Rec.601, tuned for 1953 phosphors, where sRGB is Rec.709 and wants 0.2126, 0.7152 and 0.0722. And 128 is the midpoint of the encoding rather than of contrast, since it is simply 255 divided by two; for neutrals the real crossover sits at a code value nearer 118.

None of that would matter if the answers came out the same, and the reason to care is that they do not. Ask YIQ to order two random colours and it gets them backwards 7.5% of the time; ask it to pick ink and it chooses the lower-contrast option on 14.7% of colours. That is not a tail of pathological cases either. Tailwind’s blue-500, red-500 and violet-500 all sit in the disagreement zone, as do steelblue, chocolate and indianred, which is to say: exactly where user interface palettes actually live. A formula from the era of vacuum tubes, shipping today, on the colours we use most.

The correct threshold, and where it comes from

You do not need a lookup table for this, and you do not need to try both and compare. Solve for the luminance at which black and white contrast equally under WCAG:

(1 + 0.05)/(Y + 0.05) = (Y + 0.05)/0.05 → Y = √0.0525 − 0.05 = 0.1791288

Above that value black wins, below it white does. Use the exact number rather than 0.179, because the rounded form disagrees with the greater-of-black-or-white rule on about 0.03% of sRGB colours, and if you are going to bother being right you may as well be right everywhere. It is also not the same thing as L*=50, which lands at Y=0.184. Neighbours, not synonyms.

Rolling it by hand, and why you might have to

Before the native function, people built this out of relative colour syntax, and those expressions are still worth understanding: for older browsers, and because their failure modes are a good lesson in how a correct-looking declaration can be silently useless.

The version that circulates has two bugs. The first is a comma after the origin colour, which is a parse error, since relative colour syntax is space-separated only. The declaration is dropped, the text inherits, and nothing anywhere tells you. The second is subtler.

clamp(0, (luma − 128) × −1000, 255)

That only saturates once the difference exceeds 0.255, and inside that window it returns a grey. It is 28,358 colours, or 0.169%, about one background in six hundred. On #e25d32 it emits #878787, which is 1.00:1 against its own background. Invisible text, from a declaration that parses and looks fine.

The fix is one character: −100000 instead of −1000, which narrows the grey band to 0.00255, below the 0.001 quantisation of 8-bit luma, so nothing can land in it. It is still YIQ though. Correct as written, wrong as designed. To fix the maths as well you need pow(), which lets CSS compute real relative luminance and threshold it at 0.1791288. Both are in the lab at the top of the page, computing live rather than being described, and both are in the code at the end.

Here is why this one feels hard: RGB has no lightness axis. There is no direction you can move in that means “lighter” without dragging hue and saturation along with it. Scaling the channels towards white desaturates, adding a constant shifts hue, and every naive attempt turns the colour into mush. Which is why people conclude it cannot be done and fall back to black or white, and I did that for years too.

Switch to a perceptual polar space and the problem collapses. In OKLCh a colour is lightness, chroma and hue, three axes that move independently. So:

1. Hold H and C, which is what keeps the colour recognisably itself.
2. Move L away from the background’s lightness.
3. Contrast is monotonic in L on either side of the background, so bisect for the smallest move that hits the target.

Monotonic is the load-bearing word there. It is the difference between a fifteen-line binary search and a pile of heuristics with magic numbers in them. I checked that it holds for APCA as well, across three thousand random sweeps, and found no non-unimodal case.

The two things that go wrong

The gamut runs out. Saturated colours hit the edge of sRGB before they run out of lightness, since a vivid yellow simply cannot get dark at full chroma, so either the chroma gets clipped or the colour is allowed to desaturate. The target is unreachable. Sometimes no colour at that hue clears the bar at all, and when that happens a plausible-looking wrong answer is worse than an admission, so the result carries reached: false and returns its best effort rather than pretending.

Both show up below. #fde047 on white comes back olive, which is the gamut telling you that this yellow wants to be a background and not text.

The dividing line is not really CSS against JS. It is evaluation against search. CSS evaluates an expression per element, extremely fast, and that is genuinely all it does: it cannot iterate towards an answer, and it cannot report that it failed. Every “no” in that table is one of those two. So the practical split is to use contrast-color() for ink, always, and to reach for JS only when the colour itself has to survive. Run it at build time if you can, since the shift is deterministic and a design token pipeline is a much better home for it than the main thread.

WCAG 2.1’s ratio is a legal standard and very often the thing you are actually required to meet. It is also a poor perceptual model: it ignores polarity, ignores font weight and size, and is unreliable at the dark end. Black on white and white on black both score 21:1, which anybody who has stared at both knows is not true of how they read.

APCA scores those two as Lc 106.0 and Lc −107.9. Signed, asymmetric, polarity-aware, and built for text legibility rather than as a general colour-difference metric. Flip the metric toggle in the lab above and watch every number move.

They do not just differ in precision, they pick different colours. On #3b82f6 WCAG prefers black, at 5.71:1 against white’s 3.68:1, and APCA prefers white, at Lc 69.4 against black’s 40.2. Same background, opposite answers, and the same thing happens on #787878 and #ef4444. APCA is also far stricter about mid-tone backgrounds: at Lc 75, its body-text minimum, nothing at any hue clears the bar against #3b82f6, because white itself only reaches 69.4. The honest reading of that is that a saturated mid-blue cannot host body text at all, which WCAG will cheerfully let you ship.

Everything above runs on @daformat/contrast-color, which is the same code with tests around it. It has no dependencies and nothing in it is React, so it runs just as happily in a token pipeline at build time as it does under your cursor here. It also handles a translucent foreground, scoring the composite over the background rather than the colour you handed it.

Install

Open the repo on Github (and drop a star if you like it!)

npm install @daformat/contrast-color

The source

The listing below is concatenated from the installed package when this page is built rather than copied into it, so it cannot quietly drift away from the thing running above.

import { contrastShift } from "@daformat/contrast-color";

// WCAG 2.1, body text on a blue background
contrastShift("#1e3a8a", "#3b82f6", { target: 4.5 });
// -> { hex: "#041262", score: 4.5, direction: "darker", reached: true }

// APCA, same pair, Lc 60
contrastShift("#1e3a8a", "#3b82f6", { target: 60, metric: "apca" });

// Let it desaturate when the gamut runs out
contrastShift("#fde047", "#ffffff", { target: 4.5, preserveChroma: false });

// reached: false means no colour at this hue clears the target.
// What comes back is the best available, so check it before shipping.
const result = contrastShift(fg, bg, { target: 75, metric: "apca" });
if (!result.reached) {
  console.warn("unreachable, best is", result.score);
}

OKLab conversions: Björn Ottosson. APCA: SA98G constants from apca-w3 0.1.9, checked numerically against the reference implementation.
APCA is not a drop-in substitute for WCAG 2.x conformance, so check what your project is actually required to meet.