Check your app's pages for accessibility
Run pfdl a11y on your running app to find WCAG 2.2 problems in a real browser, and read what it reports.
pfdl a11y opens your app's pages in a real browser and checks them. Run it on your machine while you build, before
you add it to CI.
What you need
- Node.js 20 or later.
- playwright-core in the project:
npm i -D playwright-core@1.64.1. It downloads no browser. - Google Chrome or Microsoft Edge on the machine.
pfdl.mjs, from the portal's Connect page or/downloads/pfdl.mjs(see The pfdl command line).
On a new machine, run node pfdl.mjs a11y self-test once. If it fails, results from that machine can't be relied on.
Run a check
Start your app.
Set it up once. This adds an
a11yblock topfdl.config.jsonand.pfdl-a11y/to.gitignore:node pfdl.mjs a11y init http://localhost:5173/Run the check:
node pfdl.mjs a11y http://localhost:5173/
One address is crawled from: the check follows links on that origin. Several addresses are checked as given, and
--no-crawl checks one page alone. The check only reads pages: it never clicks, types or submits.
What it checks
- WCAG 2.2 A and AA rules (axe-core) in light, dark and high contrast.
- Reflow at 320 px wide, 200% zoom and text spacing.
- The keyboard: a real Tab walk for order, traps and visible focus.
- The design language's rules on the rendered page, such as one primary button and headings in order.
- Page problems: HTTP errors, console errors and blocked resources.
Automated checks find part of what matters. A clean run doesn't mean the page is accessible: test keyboard and screen reader use too.
Read the output
The terminal lists each problem once, with how many pages it was found on, then a line with the counts.
- Errors fail the run (exit code 1).
- Warnings fail it only with
--fail-on warnor over--max-warnings. - To review never fail a run: the check can't decide them, so look at them yourself.
- Notes say what wasn't checked, and page problems.
To learn what a check means and how to fix it:
node pfdl.mjs a11y explain axe/color-contrast
For a report to read and share, add --out a11y-report. It writes report.html with screenshots, report.json and
junit.xml.
If something goes wrong
| What you see | What to do |
|---|---|
| Exit code 2 | The check couldn't run. Read the message: playwright-core missing, no browser, or a start page that didn't load. |
| Many addresses end at a sign-in page | Those pages need signing in: see node pfdl.mjs a11y --help for --sign-in and --storage-state. |
| Too many issues to fix at once | Accept them as known with a baseline: see Accessibility checks in CI. |