What a tool can and cannot know
An automated checker finds about a third of WCAG failures — the mechanical ones. It can tell that an image has no alt; it cannot tell that the alt says "IMG_4821". It can tell that contrast is 3.1:1; it cannot tell that the only way to reach the menu is a hover. It can tell that a button has no name; it cannot tell that the name is wrong.
So: run the tool on every pull request, because a third for free is excellent — and never report the score as a result.
The mechanical third
- Missing alt, missing labels, empty buttons and links.
- Contrast below the threshold, for plain text on a solid background.
- Duplicate ids, missing
lang, a missing document title. - ARIA that is invalid: an unknown role, a required state missing, an
aria-labelledbypointing at nothing. - Positive
tabindex,aria-hiddenon a focusable element.
import { axe } from "jest-axe";
test("the quote form has no detectable violations", async () => {
const { container } = render(<QuoteForm />);
expect(await axe(container)).toHaveNoViolations();
});The browser extension while building, axe-core in component tests, and a crawl of the deployed site for the pages nobody thought about. The three catch different things: the extension sees the real rendered state, the unit test sees every component including the error states, the crawl sees the page that only exists after a login.
The ten-minute manual pass
- Unplug the mouse. Tab through the whole page. Can you reach everything? Can you see where you are? Can you get out of everything you got into?
- Zoom to 400%. Does it reflow, or does it need sideways scrolling?
- Turn the sound on and the screen off. Use a screen reader for one task — buy something, submit the form. This is the part nobody does, and it is the part that finds the real problems.
- Read the page with the stylesheet disabled. The order you read in is the order it is announced in.
- Look at the headings list in the browser's outline view or the extension. Does it read like a table of contents?
Screen readers, briefly
You do not have to be fluent. Learn four keys — next heading, next link, next form control, read from here — and you can test anything you build. Expect to be bad at it for a week; the point is not speed, it is hearing what your page sounds like.
| Reader | Platform | Turning it on |
|---|---|---|
| VoiceOver | macOS, iOS | ⌘ + F5 — and Ctrl+Option are the modifier keys |
| NVDA | Windows | free, and what most testers use |
| JAWS | Windows | the commercial one, common in workplaces |
| TalkBack | Android | in the accessibility settings |
And ask people
Everything above is a proxy for the only real test: somebody who relies on assistive technology using what you built, for a task they care about. If you can pay for that once a year, it will teach you more than the other four sections combined — and it will change what you build, not only what you fix.