What building a contrast checker taught me about WCAG that I had wrong

"Passing AA" isn't one number

The 4.5:1 ratio everyone quotes only applies to normal text. Large text (18pt+, or 14pt+ bold) only needs 3:1. UI components and graphical objects have their own 3:1 threshold under WCAG 2.1's non-text contrast rule. A tool that only checks one ratio against one threshold is giving wrong answers for half the content on a real page.

AAA isn't just "AA but stricter"

AAA bumps normal text to 7:1, but the large-text threshold only moves to 4.5:1 - not a flat multiplier. Building the "suggest a fix" feature meant handling these as genuinely different target ratios per content type, not one formula scaled up.

The relative luminance formula is not intuitive

WCAG doesn't compare RGB values directly - it converts to relative luminance first, which weights green far more heavily than red or blue in how humans perceive brightness. Two colors that look similarly "light" or "dark" to the eye can have meaningfully different contrast ratios against the same background, which is exactly why eyeballing contrast doesn't work and a checker is worth having.

Most "suggest a fix" tools miss the mark

Most tools I looked at just darken or lighten until they hit the threshold, ignoring the original hue. That technically passes WCAG but can produce a color that no longer matches the brand or design intent. I ended up preserving hue and adjusting lightness within the same color family first, only shifting saturation as a fallback if that alone couldn't reach the target ratio.

None of this is exotic once you know it, but I'd been treating "contrast checking" as basically solved logic before actually building one. It isn't - it's a small pile of specific rules that don't generalize the way intuition suggests.

Live at quietbench.dev/contrast-checker if you want to check your own palette against it.