Skip to content
Agentic Experience Design Language Help Go to the portal

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.

For developers2 min read

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

  1. Start your app.

  2. Set it up once. This adds an a11y block to pfdl.config.json and .pfdl-a11y/ to .gitignore:

    node pfdl.mjs a11y init http://localhost:5173/
  3. 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 warn or 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

If something goes wrong
What you seeWhat to do
Exit code 2The 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 pageThose pages need signing in: see node pfdl.mjs a11y --help for --sign-in and --storage-state.
Too many issues to fix at onceAccept them as known with a baseline: see Accessibility checks in CI.