The contrast check that failed on its first run
The grey I use for dates, captions and metadata was #71736e, which is 4.46:1
on my background: below the 4.5:1 WCAG AA floor. It was live on every page for
15 days and passed every check I had. An arithmetic check over the design
tokens found it the first time it ran.
What the defect was
This site has one source of colour, src/styles/tokens.css. The light theme
puts --muted text on --paper, which is #f6f7f5. The rebuild went live on
2026-07-27 with --muted: #71736e. The contrast ratio of that pair is
4.462:1.
The token colours text at --text-s, which is 15.2px. That is normal text in
WCAG terms, not large text, so the floor is 4.5:1, not 3:1. The grey failed by
0.04. That is small, and it is still a failure, on text that is on every page.
On 2026-08-11 I moved it to #6f716c, which is 4.593:1. I kept the margin
small on purpose. The aim was to clear the floor without changing how the grey
reads. A bigger move would have been a design change that I called an
accessibility fix.
Why the axe pass could not catch it
The site’s accessibility gate runs axe-core over every built page in jsdom.
I re-ran axe-core 4.13.0’s color-contrast rule alone over the 77 pages the
site had this morning, in jsdom 30.0.1:
| Result | Pages | Nodes |
|---|---|---|
| Violations | 0 | 0 |
| Passes | 0 | 0 |
| Incomplete | 77 | 77 |
Every page gives the same answer: one incomplete node, the first text element
it tries, with the message “Axe encountered an error; test the page for this
type of problem manually.” The error is jsdom’s: it has no canvas
implementation, and axe uses one when it works out a background colour.
There is a second reason under the first. The page’s colours live in an
external stylesheet, /_astro/BaseLayout.*.css, where var(--muted) appears
in 5 declarations. jsdom does not fetch it. When I read the computed colour of
a heading on the home page in the same jsdom window, it is rgb(0, 0, 0), the
browser default. Even with a canvas, axe would compare default black text to a
default white page and pass it.
So “axe passed” never meant “contrast is fine”. It meant “axe did not look”.
An incomplete result is not a violation, and a gate that reads only violations
counts it as green. The gate now turns the rule off by name
("color-contrast": { enabled: false }) with a comment that says why. That is
more honest than a rule that is on and can never fail.
The check that computes the ratio
The fix moved the check to the source. scripts/check-a11y.mjs parses the two
theme blocks out of tokens.css and computes the WCAG ratio of each text token
against its theme’s --paper. That is 4 tokens × 2 themes, 8 pairs:
| Token | Light | Dark |
|---|---|---|
--ink |
16.85 | 15.54 |
--muted |
4.59 | 5.40 |
--signal |
6.97 | 7.65 |
--signal-dim |
4.56 | 5.41 |
--rule is not in the list. It draws hairlines that carry no information, and
it sits at 1.18:1. Leaving it out is written down in the script, so the
omission is a decision and not a gap.
This works because of a constraint the site already had: every colour a page
renders comes from tokens.css. If the token pairs pass, page text passes,
because no other colour exists. The check does not need a browser, layout or a
cascade. It needs about 10 lines of arithmetic.
The first run failed with one line: --muted on --paper in light, 4.46:1.
A test now pins the ratio, so a change back to the old value fails the build.
The same grey was in two more files
The more useful finding came one step later. --muted was not only in
tokens.css. src/lib/og.ts held #71736E, because satori renders the OG
cards in Node and has no stylesheet to read. public/favicon.svg painted its
colours as literal fills for the same reason. The comment at the top of
tokens.css said it was the only place colour was defined. That had not been
true since the day the OG cards shipped.
The check now asserts both copies. og.ts must match the light theme key for
key. Every hex in favicon.svg must be a colour that tokens.css defines. The
third copy, favicon.ico, is binary pixels and stays hand-maintained. Adding a
fourth is now a decision that goes in the project instructions, not a
convenience.
What a Lighthouse 100 did not prove
Before the token check existed, the site scored 100 for accessibility in a Lighthouse run in July, and I did a manual pass. Both passed the 4.46:1 grey. Lighthouse runs in a real Chrome, so the jsdom explanation does not cover it. I do not know why it did not flag the grey, and I have not guessed in the decision log. What I do know: a green score from a tool that samples the page is not proof that every token pair clears the floor. Only a check that computes each ratio gives that.
Today’s run of the gate: check-a11y: all rules pass (4 tokens × 2 themes, og.ts and favicon.svg mirror the light theme, axe over 83 pages). The axe part
of that line checks structure. The contrast part is the arithmetic.
Revisions
- Created from the 2026-07-27 and 2026-08-11 decision entries, the git history of tokens.css and check-a11y, a fresh run of check-a11y, and a jsdom probe of axe-core 4.13.0's color-contrast rule over the 77 built pages, run that day.
- Published on its Nov 18 slot; auto-drafted by the publishing run because no draft existed for the row.