I build web apps and I always mean to audit accessibility before shipping, and I never do. axe-core...

title: Audit WCAG 2.1 accessibility on every pull request (free GitHub Action) published: true description: tags: accessibility, github, webdev, devops

cover_image: https://direct_url_to_image.jpg

Use a ratio of 100:42 for best results.

published_at: 2026-04-24 18:01 +0000

I build web apps and I always mean to audit accessibility before shipping, and I never do. axe-core DevTools is great but it's a browser extension
I have to remember to open. So I built the thing I actually wanted:
a GitHub Action that runs axe-core on every PR and fails the job if it
finds serious violations.

The install

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

That's it. You'll get a PR comment like:

3 violations (2 critical, 1 serious)

• button-name — Buttons must have discernible text (WCAG 4.1.2 A)
• image-alt — Images must have alternative text (WCAG 1.1.1 A)
• link-name — Links must have discernible text (WCAG 2.4.4 A)

The optional source-mapping plugin

axe-core reports violations by CSS selector — button.sc-dkPtRN — which
is useless. a11yscout ships an optional Vite plugin that makes the violations say src/components/Button.tsx:12:4 instead:

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

The plugin injects a data-a11yscout-src attribute at build time, and the
scanner reads it back.

What it doesn't do (yet)

• Next.js / webpack plugins — only Vite
• Auto-detect Vercel/Netlify preview URLs — you pass them explicitly
• AI fix suggestions
• Persistent history

Links

• Marketplace: https://github.com/marketplace/actions/a11yscout
• Source: https://github.com/jpatel3/a11yscout
• License: MIT

It's day one. Feedback welcome — especially on which framework plugin to
build next.