Color and contrast: relative luminance is not an average
Converting between notations is just the entry point. The real trap is WCAG contrast, which needs gamma decoding before weighting, and deciding between black and white text, which is not a brightness threshold.
Three notations, three jobs
hex is a delivery format, rgb suits channel arithmetic, and hsl is the only one that matches intuition while picking colours. Conversion is not hard; the easy mistake is round-trip precision. Hue in hsl is a float, so rounding it and converting back changes the colour. Keep the intermediate representation floating point and format only on output.
Relative luminance is not an average of channels
The first step of WCAG contrast is decoding the sRGB channels back to linear values using the gamma approximation:
c = channel / 255
linear = c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ^ 2.4
L = 0.2126 * R + 0.7152 * G + 0.0722 * BContrast is then (L1 + 0.05) / (L2 + 0.05), with the lighter value on top.
Skipping the gamma step and averaging RGB directly is the most common bug in tools like this. The resulting number looks plausible, but it drifts from the specification in the mid-tones, which makes the AA and AAA verdicts untrustworthy.
Thresholds
Body text needs 4.5:1 for AA or 7:1 for AAA; large text relaxes to 3:1 and 4.5:1. The tool labels the level rather than printing only a number, because a number means nothing without the specification beside it.
A ramp is not a blend toward white and black
If a 50 to 900 ramp simply interpolates toward white and black, the middle steps collapse into each other and lose separation. Holding hue and saturation and sampling evenly in perceived lightness keeps the visual distance between adjacent steps roughly constant.
Black or white text
The common rule is to test whether brightness exceeds 128. It gives the wrong answer across the yellow-greens, whose lightness is mid-to-high while contrast against white is still insufficient. The reliable approach is to compute both candidates and take the higher contrast, reporting the number honestly.
Backed by known values
These calculations are ideal for known-value tests: black on white must be exactly 21, a colour against itself must be 1, and a round trip through all three notations must return the original. With those three assertions in the suite, a refactor never has to re-derive the formulas.
Comments
…