# The contrast check that failed on its first run

My site's metadata grey was 4.46:1 on its background, below the 4.5:1 WCAG AA floor, from launch on 2026-07-27 until 2026-08-11. An axe pass in jsdom could not see it: jsdom loads no stylesheet and has no canvas, so axe returns the contrast rule as incomplete on every page. A check that computes the ratio from the design tokens found it on its first run.

Published: 2026-11-18
Canonical: https://umar.codes/contrast-check-first-run

## Revisions

- 2026-11-18 — 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.
- 2026-11-18 — Published on its Nov 18 slot; auto-drafted by the publishing run because no draft existed for the row.

---

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.
