Luminance Scorer: Batch Contrast Checker

How the Luminance Scorer works

Batch contrast checker: checking a palette at once

Checking one colour pair is easy. Checking the forty pairings a design system actually uses, with every text colour on every surface in both themes, is where a one-pair-at-a-time checker stops being useful. Paste the whole list here, one pair per line, and every row is scored at once against WCAG, with the luminance of each colour alongside.

Why it matters. Low contrast is the most common accessibility failure on the web. WebAIM's annual Million report, which audits the home pages of the top million sites, has found low contrast text on roughly four in five pages every year it has run. Around one in twelve men and one in two hundred women have some form of colour vision deficiency, and far more people read on a phone in sunlight or on a dim laptop. Contrast is also a legal matter: WCAG 2.1 and 2.2 level AA underpin the European Accessibility Act, the UK public sector regulations and most ADA settlements in the US.

How the luminance scorer works

Relative luminance is the perceived brightness of a colour, from 0 for black to 1 for white. Each sRGB channel is divided by 255, put through a curve that undoes display gamma, and weighted: 0.2126 red, 0.7152 green and 0.0722 blue. Those weights are why pure green has a luminance of 0.72 and pure blue only 0.07, even though both are one channel at full strength.

The contrast ratio formula is (lighter + 0.05) ÷ (darker + 0.05). It runs from 1:1 for identical colours to 21:1 for black on white. The 0.05 approximates light reflecting off the screen, and it is why the formula flattens small differences between very dark colours.

The thresholds follow WCAG 2.2:

• Body text: 4.5:1 for AA and 7:1 for AAA.
• Large text, meaning 24 px regular or about 18.66 px bold and above: 3:1 for AA and 4.5:1 for AAA.
• Interface components and meaningful graphics, such as input borders, focus rings, icons and chart lines: 3:1. Score these with the large-text setting.

Input format. Put the foreground first and the background second, separated by a space, comma, semicolon or pipe. The # is optional and three-digit shorthand such as #333 works, so you can paste straight from a spreadsheet, a CSV export or a design-token file.

Reading the results

Each row shows the two colours, the ratio, AA and AAA pass or fail, and both luminances.

• Pairs checked counts rows that contained two valid hex colours.
• Passing AA is how many of those meet the AA level for the text size you chose. It is the one figure to track over time.
• Threshold confirms which pair of targets was applied, so a screenshot of the results is self-explanatory.
• Skipped appears when lines had no usable hex pair, such as a header row, an rgb() value or a named colour. Check it is the number you expect.

Worked example. Tailwind's gray-500 (#6b7280) on gray-100 (#f3f4f6) scores 4.39:1 and fails AA for body text, even though the same grey on white passes. #767676 on white is the lightest neutral grey that passes, at 4.54:1; one step lighter, #777777, scores 4.48:1 and fails. Pure red on white is 4.00:1, fine for a large heading but not for an error message in body text.

Tips and pitfalls.

• The rounding trap. Ratios are shown to two decimals, but pass or fail uses the exact value. A row showing 4.50:1 can still fail if the true figure is 4.497. WCAG does not allow rounding up.
• Check the pairs nobody designed. Batch checks surface combinations like secondary text on the alternate surface, a muted label inside a highlighted row, or a disabled style reused as a real label. Those are where failures live.
• Check both themes. Dark mode palettes often fail differently, because the 0.05 constant compresses differences at the dark end.
• Sort a palette by luminance. Six "distinct" colours that all sit between 0.18 and 0.24 will look flat together whichever pairs you pick, and no pairwise check will tell you that.
• Transparency is not scored. Semi-transparent text changes with whatever sits behind it. Flatten it to the solid colour it renders as, then paste that.
• Automate once the palette settles. The same formula runs in a linter or CI check against your design tokens, so contrast cannot quietly regress.

For a single pair with a live preview, use the contrast checker. To build a palette that has room for contrast from the start, try the colour harmonizer, and read colour contrast that passes WCAG for fixes that keep the brand look.

Related tools