paintcheck: measuring contrast where CSS has no answer

The problem

WCAG asks for a contrast ratio between text and its background. Tools like axe-core compute it from color and background-color. When the background is a photograph, a gradient, or a semi-transparent scrim over either, the CSS has no single colour to offer; axe reports the element as incomplete and leaves it to a human.

I hit this on my own site. The hero text sat on a photo under a gradient scrim. The checkers said nothing was wrong. When I finally measured it, the real ratio at the worst point was about 3:1 against a 4.5:1 requirement.

Two attempts that were wrong

The first version sampled the background next to the text. On a gradient the pixel beside a letter is a different colour from the pixel under it, so readings were confidently wrong in both directions: false alarms on passing text, clean bills of health on failing text.

The second version estimated glyph coverage from how much each pixel changed between a normal screenshot and one with the text hidden. On a gradient that change scales with background darkness, so the estimate only picked pixels in the highest-contrast region and reported 4.47:1 on text whose real worst point was 1.1:1. The test fixture gradient.html caught it; I did not.

The method that held

Five screenshots of the same viewport: the page as rendered (A), the same 300 ms later to exclude anything still moving (A2), all text forced transparent (B), all text forced black (C), all text forced white (D).

C and D give the coverage of every pixel exactly, independent of the background and of the text's real colour: a pixel covered by a fraction α reads α·0 + (1−α)·bg in C and α·255 + (1−α)·bg in D, so α = (D − C)/255. Pixels near the element's maximum α are the glyph core; antialiased edges are dropped because they are blends.

Then the foreground is read from A at those pixels and the background from B at the same pixels. Nothing is computed from CSS. opacity: .5 on a parent with .8 on the child, an rgba colour, a pseudo-element scrim: Chrome already applied all of it, and the result is what gets measured.

Where glyph stems are thinner than a pixel, no pixel is fully covered, so even the densest one is a mixture. Since α is known the mixture is undone: E = B + (A − B)/α. Without that step 12 px footer links at a real 5.85:1 came out as 3.81:1.

Two more corrections the suite forced

On Windows, Chrome's subpixel antialiasing gives each colour channel a different coverage, so pixels treated as fully covered were still blends and every reading came out about half a point low: 3.92 measured against 4.48 computed. Chrome is now launched with greyscale antialiasing.

The antialiasing correction initially divided both the element's opacity and the colour's own alpha out of the coverage map. The black and white probes override the colour but not the opacity, so only opacity belongs in that division; dividing alpha too made the correction skip thin rgba text entirely. Authored transparency stays in the result, because it genuinely reduces readability and WCAG counts it.

Whole pages and sticky headers

By default only the first viewport is measured. With --full-page the document is scrolled in overlapping steps, because an element on a step boundary would otherwise be clipped in both steps and never measured.

Sticky and fixed elements are measured at every scroll position and reported once, at their worst. In the benchmark, axe-core passes the fixture header at 4.54:1 where it starts; three screens down, over a grey band, it measures 1.32:1.