DEV Community

Vijay Govindaraja
Vijay Govindaraja

Posted on

I Built a Free WCAG Accessibility Audit CLI for Government Teams

#a11y #cli #opensource #showdev

Every government website in the US is required to meet Section 508 accessibility standards. Most commercial tools cost hundreds per month. So I built an open source alternative.
**

The Problem **

If you're a developer working on a .gov site, you need to verify WCAG compliance before every deploy. Your options

are:

  • Manual testing — slow, inconsistent, doesn't scale
  • Commercial tools (Siteimprove, Level Access) — $500+/month
  • Browser extensions (axe DevTools) — great for one page, but can't scan a whole site or run in CI

I wanted something that:

  1. Runs from the terminal
  2. Scans entire sites via sitemap
  3. Outputs JSON/CSV for CI pipelines
  4. Costs nothing

wcag-audit

npx wcag-audit scan https://your-site.gov

That's it. No API keys, no account, no config files.

It launches a headless browser, injects https://github.com/dequelabs/axe-core (the same engine Google and Microsoft

use), and returns a report with every WCAG violation, the affected elements, and how to fix them.

What the output looks like

════════════════════════════════════════════════════
WCAG ACCESSIBILITY AUDIT REPORT

════════════════════════════════════════════════════

URL:      https://example.gov                                                                                     
Title:    Example Government Site
Level:    WCAG AA

Critical: 2  Serious: 5  Moderate: 8  Minor: 3                                                                      

[critical] image-alt: Images must have alternate text                                                               
  WCAG: wcag2a, wcag111                                                                                           
  Elements affected: 4
    → img.hero-banner
      Fix: Element does not have an alt attribute

[serious] color-contrast: Elements must meet minimum
  color contrast ratio                                                                                              
  WCAG: wcag2aa, wcag143                                                                                          
  Elements affected: 12
    → .nav-link
      Fix: Element has insufficient color contrast
Enter fullscreen mode Exit fullscreen mode

════════════════════════════════════════════════════

Every violation tells you:

  • The rule that failed
  • The severity (critical, serious, moderate, minor)
  • Which WCAG criterion it violates
  • The CSS selector of the affected element
  • How to fix it

Scan an Entire Site

wcag-audit crawl https://example.gov/sitemap.xml --max-pages 50

Reads the sitemap, scans each page, and produces a consolidated report.

Drop it into CI

The CLI exits with code 1 when violations are found:

# GitHub Actions

  • name: Accessibility Audit run: npx wcag-audit scan ${{ env.DEPLOY_URL }} --level AA

Now accessibility is enforced on every deploy. No violations, no merge.

JSON and CSV for Reporting

# JSON for programmatic use

wcag-audit scan https://example.gov --format json --output report.json

# CSV for spreadsheets and compliance reports
wcag-audit scan https://example.gov --format csv --output report.csv

The CSV is designed for compliance teams who need to track violations in spreadsheets and produce audit reports for

management.

WCAG Levels

# Level A (minimum)
wcag-audit scan https://example.gov --level A

# Level AA (required for US federal, most common)

wcag-audit scan https://example.gov --level AA

# Level AAA (strictest)

wcag-audit scan https://example.gov --level AAA

Most government sites need AA. The tool defaults to AA.

Use it as a Library

const { scanUrl, formatTextReport } = require('wcag-audit');

const results = await scanUrl('https://example.gov', {
level: 'AA',
viewport: { width: 1280, height: 720 },
});

if (results.summary.impactBreakdown.critical > 0) {

console.error('Critical accessibility violations found!');
process.exit(1);

}

Why I Built This

I've been contributing to accessibility-related projects across multiple government agencies — the US Web Design

System (USWDS), the UK's GOV.UK Frontend, Singapore's GovTech accessibility tool (oobee), and Grafana's
colorblind-safe palette. Every one of these projects deals with the same problem: making sure websites are accessible
to everyone.

The tooling gap was obvious. Developers who care about accessibility shouldn't need to pay for the privilege of

testing it.

Tech Stack

Install

npm install -g wcag-audit

Or try without installing:

npx wcag-audit scan https://example.com

Links

The tool is MIT licensed. PRs welcome. If you work on a government site and this saves you time, I'd love to hear
about it.

Top comments (0)