Why CSS was not enough

Tools like axe-core compute contrast from color and background-color. On my own site the text sat on a photograph under a gradient scrim; there was no background colour to read, so the checkers reported the element as incomplete. The real ratio at the worst point was about 3:1 against a 4.5:1 requirement, and nothing had told me.

Attempt one: sample next to the text

The first version took a screenshot and read the background colour from pixels beside each glyph. On flat backgrounds this works. On a gradient the pixel beside a letter is a different colour from the pixel under it, so the readings were wrong in both directions: false alarms on passing text and clean results on failing text. I noticed because the numbers did not match what I could see.

Attempt two: estimate coverage from change

The second version took two screenshots, one normal and one with all text hidden, and estimated how much each pixel was covered by a glyph from how much it changed. Then it read the colours from the most-covered pixels.

On a gradient the change between the two screenshots scales with background darkness. The estimate therefore selected pixels only in the highest-contrast region and never looked at the light end. The fixture gradient.html, where the background crosses the text's own colour, has a worst point near 1.1:1. This version reported 4.47:1 and passed it. The test failed; I had not.

The method that held

Five screenshots of the same viewport:

• A: the page as rendered
• A2: 300 ms later; pixels that changed are excluded (fonts still loading, animations)
• B: all text forced transparent
• C: all text forced black
• D: all text forced white

C and D give the coverage of each pixel exactly. If a pixel is covered by a fraction α over background bg, then C = (1−α)·bg and D = α·255 + (1−α)·bg, so α = (D − C)/255, independent of the background and of the text's real colour. Pixels near the element's maximum α are the glyph core; antialiased edges are dropped.

The foreground is then read from A at those pixels and the background from B at the same pixels. Nothing is computed. Opacity chains, rgba colours and pseudo-element scrims were already applied by Chrome when it painted.

Two corrections the suite forced afterwards

Subpixel antialiasing. On Windows, ClearType gives each colour channel a different coverage. 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 for #777 on white. Chrome is now launched with greyscale antialiasing (--disable-lcd-text).

Thin glyphs. Where a stem is narrower than a pixel, no pixel is fully covered, so even the densest one is a mixture. Since α is known the mixture can be undone: E = B + (A − B)/α. Without it, 12 px footer links at a real 5.85:1 came out as 3.81:1. The first version of this correction also divided the colour's own alpha out of the coverage, which is wrong: the black and white probes override the colour but not the element's opacity, so only opacity belongs in that division. An rgba .68 line that must pass and an rgba .5 line that must fail at 3.32:1 now pin both directions.

What is verified and what is not

The recorded 57-test run for revision 37bbe2a passed locally on Windows 11 with Chrome 152. The benchmark runs axe-core and paintcheck on the same fixtures, using calculated reference ratios for flat backgrounds. Photo and scrim fixtures have no hand-computed reference value. These results describe the local revision, which has not been published to GitHub.

Update, 16 September 2026: revision 37bbe2a is now on GitHub and its CI run on Ubuntu with Node 20/22 passed. macOS is still untested. Font rendering can change measured ratios; cross-machine pass/fail stability has not been established beyond these two environments.

The tool is not on npm yet. It runs from the repository with npx github:hasanyahsitr/paintcheck and needs a local Chrome.

paintcheck: the accent colour

The reference design uses a bright blue, #4770ff, for links and buttons on white cards. It looks fine. Measured from the rendered pixels it is not fine:

! [contrast] section.hy-kart > div.hy-kart-bas > a.hy-ok
    "More About Me"
    16px — 4.09:1 — needs 4.5:1
    rgb(73,114,255) on rgb(255,255,255)
! [contrast] div.hy-profil-dugmeler > a.hy-dugme
    "Write to me"
    16px — 4.16:1 — needs 4.5:1
    rgb(254,254,255) on rgb(71,112,255)

Twelve findings on the home page, six on the about page, six on the contact page. All the same cause: blue text on white, or white text on that blue, at 4.09 to 4.18 to 1 against a 4.5 to 1 threshold. This is the flat-background case where CSS arithmetic is exact, so axe-core would have caught it too. I simply had not run anything yet.

Fix: the accent became #3457e8 for text and button backgrounds in the light theme (5.8:1 on white), and a lighter #6b8cff for text on the black cards in the dark theme. Visually the difference is small. After the change paintcheck reports zero contrast findings on all four pages. The remaining findings are target-size notes on the visually hidden radio inputs inside labelled chips; the label is the click target, the input is 1×1 by design.

Lighthouse: 26 requests to files that do not exist

Desktop Lighthouse on the home page: performance 96, accessibility 96, best practices 96, SEO 100. The "errors in console" audit listed ten 404s during the run, and a puppeteer script that hovers the links counted 26 on a full visit.

The requests looked like /about/__next.!KGVuKQ.about.__PAGE__.txt. Next.js 16.2 static export writes segment prefetch payloads as nested folders, out/about/__next.!KGVuKQ/about/__PAGE__.txt, while the client asks for the dotted, flat name. Every prefetch failed and every client-side navigation fell back to a full page load.

I did not find a config switch for this, so the build now runs a 30-line script that copies each nested payload to its flat name. After that: zero 404s, client navigation keeps the trailing slash, and Lighthouse desktop reads 95 / 100 / 100 / 100 with LCP 1.5 s and CLS 0.

Lighthouse mobile: the photo

The mobile run scored 76 on performance with LCP at 7.1 s under Lighthouse's simulated slow 4G. The largest element was my own photo, served as an 800×800 WebP with loading="lazy". Lazy-loading the first thing on the screen is exactly wrong; I had copied the attribute from a component that is also used lower on the page.

Fix: the profile photo is now eager with fetchpriority="high", and a 480 px variant is offered through srcset for phone widths. Measured again, the simulated mobile LCP went from 7.1 s to 6.2 s and the score from 76 to 77. That is a small move, and the breakdown says why: the image itself loads in about 120 ms; the delay is the 173 KB HTML document and the render work before it, not the picture.

So I tried the document. The logo paths were embedded twice per logo, once in the markup and once in Next's inline data payload. Moving them into one external SVG sprite took the home page from 170 KB to 82 KB. Measured again, twice, with nothing else running: 78 and 74 on mobile, LCP 5.9 s and 6.1 s. Half the document, same LCP. The lever is somewhere else, and I stopped guessing for tonight; the smaller page is still worth keeping.

Update, 16 September 2026. The lever was the local server. Every mobile number above came from serve on my laptop, which sends the HTML uncompressed and without cache headers. The same build on Firebase Hosting, measured with Lighthouse 12 against the live hasanyahsi.com: mobile 90 / 100 / 100 / 100 with LCP 2.4 s, desktop 99 / 100 / 100 / 100 with LCP 0.6 s. The 6 s was never the page; it was how I served it. Measuring the deployed site should have been the first step, not the last.

The accessibility audit on mobile also flagged the menu links: below 1100 px I had hidden the label text with display: none, which removes it from the accessible name as well. It is now visually hidden instead, and the mobile accessibility score is 100.

What this note is not

None of these numbers are a certificate. Lighthouse runs on one machine with simulated throttling; paintcheck measures one viewport at one moment. The point is smaller: I copied a colour from a reference and it failed the threshold my own tool exists to check, and I only found out because I ran the tool.

On measurement day I looked at the Cloudflare dashboard first. Under security rules:

AI Crawl Control - Block AI bots by User Agent · Active

The rule blocked 16 bots on every path except robots.txt, including ChatGPT-User, OAI-SearchBot, Claude-SearchBot, PerplexityBot and bingbot. In the previous 24 hours, 163 of 212 AI crawler requests had been rejected. Allowed requests for OpenAI, Anthropic, Perplexity and Bing: zero.

How I measured

I did not trust the dashboard; I tested from outside, requesting the same page with different User-Agent strings:

Googlebot        200
ChatGPT-User     403
PerplexityBot    403
bingbot          403

Two weeks of writing had gone into pages the bots could not read.

Where the rule came from

Cloudflare's AI Crawl Control screen generates this rule from a single Block button. It was probably pressed months earlier with the reflex "AI should not scrape my content". Reasonable that day; today the same button turns away the bot that would bring the customer.

There was a second layer: the managed "Block AI bots" setting under Security settings. Even after narrowing the custom rule, the search bots kept getting 403 until that was switched off too.

What I did

I did not delete the rule; I narrowed it. Training crawlers (GPTBot, ClaudeBot, CCBot, Bytespider) stay blocked. Search and live-fetch agents (ChatGPT-User, OAI-SearchBot, Claude-SearchBot, PerplexityBot, bingbot) are allowed. Then the same test again:

ChatGPT-User     200
OAI-SearchBot    200
PerplexityBot    200
bingbot          200
GPTBot           403
ClaudeBot        403

The lesson

Check the door before writing content. If your site is behind Cloudflare, look once at Security → Rules and Security → Settings → Bot traffic. Anything with "AI" in its name may be blocking the search bots too.

I will measure again a week later. I do not know when the bots will come back; if the first numbers are low, that goes here too.