Automating WCAG 2.1 Accessibility Audits with a11yscout GitHub Action

Audit WCAG 2.1 accessibility on every pull request (free GitHub Action)

Developer Jaimin launched a11yscout to eliminate the friction of manual accessibility testing using browser extensions. The system integrates axe-core directly into CI/CD pipelines to fail builds when serious violations are detected.

Why This Matters

While accessibility is a critical requirement for modern web applications, manual audits often fail because developers forget to run browser-based tools before shipping. Moving these checks into a GitHub Action shifts accessibility left, ensuring that WCAG 2.1 compliance is a hard requirement for merging code rather than an after-the-fact consideration.

Key Insights

• Automated PR comments report specific violations including button-name (WCAG 4.1.2 A) and image-alt (WCAG 1.1.1 A).
• Source-mapping via a dedicated Vite plugin allows the scanner to report errors at the source file level (e.g., src/components/Button.tsx:12:4) instead of generic CSS selectors.
• The Action supports configurable failure levels, allowing teams to block merges specifically on ‘serious’ or ‘critical’ violations.
• a11yscout requires explicit preview URLs to be passed to the scanner, as it currently lacks auto-detection for Vercel or Netlify environments.
• The project is open-source under the MIT license and specifically targets Vite-based workflows for its advanced source-mapping capabilities.

Working Examples

Basic GitHub Action configuration to audit accessibility on pull requests.

on: pull_request
jobs:
  a11y:
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write }
    steps:
      - uses: jpatel3/a11yscout@v1
        with:
          urls: https://your-preview-url.example.com
          level: AA
          fail-on: serious

Vite plugin configuration to enable source-mapping for accessibility violations.

import { a11yscout } from "@a11yscout/vite-plugin";
export default defineConfig({
  plugins: [react(), a11yscout()],
});

Practical Applications

• Use Case: A team using Vite can integrate a11yscout to automatically block pull requests that include buttons without discernible text.
• Pitfall: Relying on the default CSS selector reports in complex apps makes debugging difficult; teams should use the Vite plugin to map violations back to specific component lines.

References:

• https://github.com/marketplace/actions/a11yscout
• https://github.com/jpatel3/a11yscout