DEV Community

imta71770-dot
imta71770-dot

Posted on • Originally published at accessibleweb-guide.pages.dev

How to Automate Accessibility Fixes in Your CI/CD Pipeline

#a11y #webdev #githubactions #javascript

Originally published at AccessibleWeb Guide.

You already know your website has accessibility problems. Every scan lights up like a Christmas tree -- missing alt text, unlabeled form fields, no page title, iframes without descriptions. The list goes on.

The standard advice is to fix them one by one, manually. That takes forever. And every new pull request introduces new violations faster than you can fix the old ones.

What if your CI/CD pipeline caught those issues and fixed the easy ones automatically, on every single PR?

The Gap in Today's Accessibility Tooling

The accessibility tooling market has a strange hole in it. You can find plenty of tools that detect problems:

  • Lighthouse flags violations in your browser
  • axe DevTools lists every issue with detailed descriptions
  • WAVE shows you exactly where errors live on the page

And then there are overlay products that promise to fix everything with a single line of JavaScript. But those don't actually work and are getting companies sued. The FTC fined one major overlay provider $1 million for misleading claims.

What's missing is the middle ground -- a tool that automatically fixes the issues it can fix, honestly reports the ones it cannot, and integrates directly into the workflow developers already use.

Introducing A11y Fix Engine

A11y Fix Engine is a free, open-source GitHub Action that does exactly this. Drop it into your workflow, and every pull request gets:

  1. Scanned against WCAG 2.2 AA using axe-core (the same engine used by Microsoft, Google, and the US government)
  2. Auto-fixed where possible -- alt attributes added, labels applied, lang attributes set, titles inserted
  3. Reported with a clear breakdown of what was fixed and what needs your attention

Setup Takes 30 Seconds

Create a file at .github/workflows/a11y.yml:

name: Accessibility Check
on: [pull_request]

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: imta71770-dot/a11y-fix-engine@v0.1.0
        with:
          standard: 'wcag2aa'
          fix: 'commit'
          fail_on: 'serious'
Enter fullscreen mode Exit fullscreen mode

Done. Every PR touching HTML files now runs through an accessibility check.

What It Actually Fixes

Let me be specific. Here are real before-and-after examples from a test run on a typical small business page:

Missing Alt Text

Images without alt text are the single most common accessibility violation on the web. Screen reader users hear the filename or nothing at all.

Before:

<img src="/images/team-photo-2025.jpg">
Enter fullscreen mode Exit fullscreen mode

After:

<img src="/images/team-photo-2025.jpg"
     alt="TODO: Describe this image — team photo 2025">
Enter fullscreen mode Exit fullscreen mode

The engine adds a placeholder that reminds you to write a real description. It is intentionally a TODO rather than an AI-generated guess, because bad alt text is worse than a placeholder that gets caught in code review.

Icon Buttons Without Labels

A button with only an SVG icon inside it is invisible to screen readers. The user hears "button" with no indication of what it does.

Before:

<button type="submit">
  <svg viewBox="0 0 24 24">
    <path d="M2.01 21L23 12 2.01 3 2 10l15 2-15 2z"/>
  </svg>
</button>
Enter fullscreen mode Exit fullscreen mode

After:

<button type="submit" aria-label="TODO: Add accessible label for this button">
  <svg viewBox="0 0 24 24">
    <path d="M2.01 21L23 12 2.01 3 2 10l15 2-15 2z"/>
  </svg>
</button>
Enter fullscreen mode Exit fullscreen mode

Missing Language Declaration

Without a lang attribute on the <html> element, screen readers cannot determine which language to use for pronunciation.

Before:

<html>
Enter fullscreen mode Exit fullscreen mode

After:

<html lang="en">
Enter fullscreen mode Exit fullscreen mode

The Full List of Auto-Fixes

  • Missing alt attributes on images
  • Missing form labels
  • Missing lang attribute
  • Missing <title> element
  • Missing skip navigation links
  • Icon buttons without accessible names
  • Iframes without titles
  • Invalid autocomplete attributes
  • aria-hidden incorrectly set on body
  • Missing landmark roles

What It Does Not Fix (And Why That's Honest)

About 70% of WCAG criteria require human judgment. Things like:

  • Is the alt text actually meaningful? The engine can add a

Top comments (0)