Color Converter: My Contrast Audit Flagged 11 Colors That Already Passed WCAG AA

Last Tuesday I ran a contrast check over our design tokens before a release. The script reported 11 failures out of 42 text/background pairs. I spent the afternoon darkening grays and pulling the brand blue down two steps, pushed it, and went home.

The next morning our designer opened the staging build and asked why the primary button looked muddy. Then axe-core in CI flagged three pairs my script had marked as clean.

Both of us were looking at the same CSS. My checker was wrong in two different directions at once, and it took me a while to see why.

The scene, with numbers

The palette was small. Body text #767676 on #FFFFFF. Brand link #5B8DEF on white. A muted placeholder #9AA4B2 on #F8FAFC. A disabled label written as eight-digit hex, #00000080.

My first script did what a lot of quick scripts do. It grabbed the three channel bytes, divided by 255, and plugged them straight into the luminance formula. No gamma step. That single omission dragged every ratio down toward 1.0, so pairs that passed looked like failures. Meanwhile the alpha bug below pushed three real failures up to a perfect score.

#767676 on white came out as 2.05:1. The real number is 4.54:1, which passes AA for body text at any size. I darkened 300-odd paragraphs for nothing.

The formula I should have used is the one in the WCAG 2.2 definition of relative luminance: linearize each channel first, then weight them 0.2126 / 0.7152 / 0.0722.

Method 1: a Python script that gets the math right

Python 3.11.1, standard library only. Save as check_contrast.py and run it.

def channel(c: int) -> float: c = c / 255 return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4 def luminance(hex_color: str) -> float: h = hex_color.lstrip("#") r, g, b = (int(h[i:i + 2], 16) for i in (0, 2, 4)) return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b) def ratio(fg: str, bg: str) -> float: a, b = luminance(fg), luminance(bg) hi, lo = max(a, b), min(a, b) return (hi + 0.05) / (lo + 0.05) PAIRS = [ ("#767676", "#FFFFFF", "body text on surface"), ("#5B8DEF", "#FFFFFF", "brand link on surface"), ("#9AA4B2", "#F8FAFC", "placeholder on page bg"), ] for fg, bg, label in PAIRS: r = ratio(fg, bg) size = "AA" if r >= 4.5 else "AA-large" if r >= 3.0 else "fail" print(f"{label:28} {fg} on {bg} {r:5.2f}:1 {size}") 

Output on my machine:

body text on surface #767676 on #FFFFFF 4.54:1 AA brand link on surface #5B8DEF on #FFFFFF 3.23:1 AA-large placeholder on page bg #9AA4B2 on #F8FAFC 2.41:1 fail 

Read that middle line before you touch your brand color. #5B8DEF is a perfectly good link color for 24px headings and a failing one for 16px body copy. There is no single "is this color accessible" answer. Size and weight decide it, and a checker that returns one boolean will keep lying to you.

The placeholder line is the only genuine failure in that list, and it was the one pair I had not touched.

Method 2: Node, reading the tokens straight from CSS

Python is fine for a one-off list. For CI I wanted the audit to read the actual tokens.css so nobody could hand-edit a hex in the script and drift from production.

Node 22.13.1, no dependencies:

import { readFileSync } from "node:fs"; const lin = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4); const lum = ([r, g, b]) => 0.2126 * lin(r / 255) + 0.7152 * lin(g / 255) + 0.0722 * lin(b / 255); const ratio = (fg, bg) => { const [a, b] = [lum(fg), lum(bg)]; return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05); }; function parse(css) { const hex = css.match(/^#([0-9a-f]{3,8})$/i); if (hex) { let h = hex[1]; if (h.length === 3) h = [...h].map((c) => c + c).join(""); const n = (i) => parseInt(h.slice(i, i + 2), 16); return [n(0), n(2), n(4), h.length === 8 ? n(6) / 255 : 1]; } const m = css.match(/rgba?\(([^)]+)\)/i); if (!m) throw new Error(`unparsed color: ${css}`); const p = m[1].split(/[\s,\/]+/).filter(Boolean).map(Number); return [p[0], p[1], p[2], p.length > 3 ? p[3] : 1]; } const over = (fg, bg) => fg.slice(0, 3).map((c, i) => Math.round(c * fg[3] + bg[i] * (1 - fg[3]))); const tokens = Object.fromEntries( [...readFileSync("tokens.css", "utf8").matchAll(/--([\w-]+):\s*([^;]+);/g)] .map((m) => [m[1], m[2].trim()]) ); const bg = parse(tokens.surface ?? "#FFFFFF"); for (const [name, raw] of Object.entries(tokens)) { if (!name.startsWith("text-")) continue; const fg = over(parse(raw), bg.slice(0, 3)); console.log(`${name.padEnd(18)} ${ratio(fg, bg.slice(0, 3)).toFixed(2)}:1`); } 

Against this tokens.css:

:root { --surface: #FFFFFF; --text-body: #767676; --text-muted: #8A8F98; --text-disabled: #00000080; } 

It prints:

text-body 4.54:1 text-muted 3.25:1 text-disabled 4.00:1 

Two things to notice. text-disabled is 4.00:1, not the 21:1 my old script reported, because the alpha channel finally gets composited. And text-muted at 3.25:1 fails AA for small text, which is the kind of finding I actually wanted.

Wire this into CI with an exit code and a 4.5 threshold, and the audit stops being a thing I remember to run.

Method 3: the browser tool for the handoff

The script tells me a pair fails. It does not tell the designer what to change.

That is where a free online color converter earned a permanent tab. I paste #5B8DEF and get HEX, RGB and HSL side by side with a live swatch. The HSL row is what I forward: "same hue 220°, saturation 82%, lightness 64.7% down to 48%". She adjusts one number instead of guessing at a new hex.

The round trip matters too. When a designer sends hsl(220 82% 65%) in Slack and the codebase stores hex, this browser-based tool gives me the hex and the swatch to confirm nothing shifted. I do the ratio math in the script, not in my head. The converter handles the notation, the script handles the threshold.

One habit worth building: after you pick a shade in the color converter, check it in DevTools on the real element. Computed color can differ from the token you think you set, especially when a parent has opacity or a gradient overlay.

Three pitfalls that cost me real time

1. Missing linearization, silently. My first pass returned 2.05:1 for #767676 on white. Nothing errored. The number just looked plausible, and I acted on it. Any contrast function that does not contain a ** 2.4 or a pow(x, 2.4) is wrong. Compare against one known pair before trusting a batch of 42.

2. Eight-digit hex read as six. #00000080 sliced at h[0:2], h[2:4], h[4:6] yields black, and the 80 disappears without a warning. My audit gave text-disabled a 21.00:1 and passed it. Composited over white it is #7F7F7F, 4.00:1, below the AA floor for small text. MDN's hex color reference covers the #RRGGBBAA form; if your parser only accepts six digits, make it throw instead of truncating.

3. Interpolating hue the short way round. Building a hover ramp from a red brand color, I stepped hue from 350° to 10° in equal increments. The midpoint landed on 180°:

hue 350 -> 10, linear midpoint = #19E5E6 shortest-path midpoint = #E61919 

Cyan, in the middle of a red ramp. Hues are angles, so the shortest path crosses 0°, not the middle of the wheel. Same trap in reverse for 10° to 350°.

Also worth knowing: #767676 is HSL lightness 46.3%, not 50%. "Add 10% lightness" is not a predictable number of contrast points, so re-measure after every nudge.

Summary

Approach Good for Watch out for
Python 3.11.1 script One-off audits, exact numbers, no install Must linearize channels; no alpha support unless you add it
Node 22.13.1 + tokens.css CI gates, catching token drift Composite alpha first, then measure
Browser converter HSL handoff, notation round trips, visual check Gives you colors, not ratios

The audit did not fail because the palette was bad. It failed because my checker had no gamma correction and no alpha handling, and I trusted its output over the rendered page.

More free browser-based utilities at utilvy.com