# Automated Remediation & Accessibility Fixing Patterns

Detecting accessibility violations is only half the pipeline; this section covers how teams programmatically fix the issues their scanners surface — turning a red build into a reviewable pull request instead of a backlog ticket. It complements the broader work of CI/CD Integration & Automated Quality Gating, where the focus is detection and gating rather than repair.

Automated remediation sits downstream of detection. Once a tool such as axe-core classifies a violation, a remediation layer decides whether the fix is mechanical enough to apply safely, applies it, re-scans to confirm, and opens a PR for human review. The goal is never to merge unreviewed machine edits — it is to compress the time between “violation found” and “correct fix proposed.”

• Mechanical violations (missing alt, unassociated labels, redundant roles) are bulk-fixable with deterministic codemods.
• Every auto-fix is followed by a re-scan; a fix that does not clear the original finding is discarded, not merged.
• No remediation merges without human review — the pipeline opens a PR, it does not push to the default branch.
• Roughly 30–40% of WCAG failures are machine-detectable, and a smaller subset of those are safely machine-fixable.

# Core principles

Three principles keep automated remediation safe. First, shift-left but gate the fix: a codemod can run in a feature branch the moment a scanner finds a violation, but the resulting diff is gated behind the same review and re-scan that any human change would face. Second, severity-aware thresholds: only fixes that clear a critical or serious finding should be auto-proposed; moderate and minor findings often need human judgment about intent. Third, the 30–40% automated rule: because scanners detect only a fraction of WCAG failures and codemods can only safely repair a subset of those, remediation automation is a force-multiplier for the mechanical, repetitive failures — not a substitute for manual audits of focus order, reading order, and cognitive load.

The remediation strategies below trade off differently across WCAG coverage, the effort to wire them into CI, the risk of a wrong-but-passing fix, and the review burden they impose on humans.

# Codemod-Driven Accessibility Fixes

The most predictable remediation layer is the codemod: a script that parses source into an abstract syntax tree, edits the tree, and prints it back. Because the edit is deterministic, the same input always produces the same diff, which is exactly what a reviewer wants when scanning a 200-file pull request. The Codemod-Driven Accessibility Fixes section covers writing transforms with jscodeshift, ts-morph, ESLint autofix, and PostCSS, plus how to dry-run them before committing.

Codemods shine on violations that are structurally obvious from the source: an <img> with no alt, a <label> with no associated control, a role attribute duplicating an implicit role. These map cleanly to WCAG 2.2 SC 1.1.1 and SC 1.3.1, and the fix shape is mechanical enough to encode as a tree edit.

Two focused walkthroughs live under this section: automating alt-text remediation with codemods, which inserts reviewable placeholder alt attributes that intentionally keep CI red until a human writes real text, and bulk-fixing form-label associations with jscodeshift, which wires orphan labels and inputs together with htmlFor/id pairs.

The hard part is not the transform — it is the dry-run discipline. A codemod that misfires across a monorepo can introduce hundreds of subtly wrong edits, so every transform ships with a jest-axe fixture proving it both fixes the target case and leaves correct code untouched.

# AI-Assisted Accessibility Remediation

Some violations need content, not structure. A missing alt on a meaningful image, an aria-label for an icon-only button, or a clearer error message all require a human-readable string that a deterministic codemod cannot invent. This is where AI-Assisted Accessibility Remediation fits: a model proposes the text, and the pipeline treats that proposal as untrusted until verified.

The risk profile is fundamentally different from codemods. An AI suggestion can be grammatically perfect and semantically wrong — describing a chart as “a photo of a person,” for example. Treating AI output as a draft, never a merge, is the entire discipline. The section’s guidance on validating AI-generated ARIA fixes in CI and using LLMs to suggest ARIA labels safely both enforce a re-scan plus mandatory human sign-off before any generated string reaches the default branch.

A practical pattern is to combine the two layers: a codemod inserts a TODO-tracked placeholder, an AI step drafts a candidate string into the PR description (not the code), and a reviewer accepts or rewrites it. The machine narrows the work; the human owns the meaning.

# Regression Prevention After Fixes

A fix that is not protected by a test will regress. Once a remediation PR merges, the same violation can reappear the next time someone refactors the component — and a scanner that only runs on changed files may miss it. Regression Prevention After Fixes covers locking in the corrected state so a fix stays fixed.

The most durable technique is snapshotting the accessibility tree — the computed name, role, and state of each node — so that any change which alters the exposed semantics breaks a test loudly. The walkthrough on snapshot testing accessibility trees to prevent regressions shows how to serialize that tree and assert against it in CI.

This closes the remediation loop: detect, fix, and then guard. Pair these snapshots with the trend tracking in Reporting, Dashboards & Violation Tracking so a regression shows up as both a failed test and a visible uptick on the dashboard.

# Design-System Accessibility Defaults

The cheapest violation to remediate is the one a component cannot produce. When a Button, Input, or Image component refuses to render without an accessible name, an entire class of WCAG failures disappears at the source instead of being scanned and patched downstream. Design-System Accessibility Defaults covers building those guarantees into shared components.

This is remediation moved leftmost: instead of fixing thousands of call sites, you fix the library once and let type checks and lint rules enforce correctness at every usage. The guidance on enforcing accessible component defaults in a design system shows how to make required props, sensible ARIA defaults, and focus management non-optional.

Design-system defaults have the highest upfront cost and the lowest ongoing one. Once an Image component requires an alt prop at the type level, the alt-text codemod becomes a one-time migration rather than a recurring chore.

# Minimal remediation pipeline skeleton

The following GitHub Actions workflow wires the full loop — detect, auto-fix, re-scan, open PR — for mechanical violations. It never pushes to the default branch; it opens a branch and a PR for review.

name: a11y-auto-remediation
on:
  workflow_dispatch:        # run on demand, or schedule nightly
  schedule:
    - cron: "0 3 * * 1"     # weekly remediation sweep, Monday 03:00 UTC
permissions:
  contents: write           # needed to push the remediation branch
  pull-requests: write      # needed to open the PR
jobs:
  remediate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      # 1. DETECT — scan built output, write machine-readable findings
      - name: Detect violations
        run: |
          npm run build
          npx serve dist -l 3000 &        # serve built output for the scanner
          npx wait-on http://localhost:3000
          npx axe http://localhost:3000 \
            --tags wcag2a,wcag2aa \
            --save axe-report.json \
            --exit || true                 # capture findings without failing the job
      # 2. AUTO-FIX — run deterministic codemods over the source tree
      - name: Apply codemods
        run: |
          npx jscodeshift -t codemods/add-missing-alt.js src/ \
            --parser=tsx                    # match TS/JSX syntax
          npx jscodeshift -t codemods/associate-labels.js src/ \
            --parser=tsx
      # 3. RE-SCAN — rebuild and confirm the codemods cleared the findings
      - name: Verify fixes
        run: |
          npm run build
          npx serve dist -l 3000 &
          npx wait-on http://localhost:3000
          npx axe http://localhost:3000 \
            --tags wcag2a,wcag2aa \
            --save axe-after.json \
            --exit || true                 # remaining findings are expected (TODOs)
      # 4. OPEN PR — only if the codemods produced a diff
      - name: Open remediation PR
        uses: peter-evans/create-pull-request@v6
        with:
          branch: a11y/auto-remediation
          commit-message: "fix(a11y): apply automated remediation codemods"
          title: "Automated accessibility remediation"
          body: |
            Codemods applied. See axe-before/axe-after artifacts.
            Placeholder alt/labels need human review before merge.
          labels: accessibility, needs-review

The || true after each scan is deliberate: the detect and verify steps are diagnostic, not gating. The actual gate is the PR review plus the standard pull-request check defined in your GitHub Actions a11y Pipeline Setup, which runs against the proposed branch like any other contribution.

# Compliance mapping: WCAG 2.2 SC → remediation technique

# Common Pitfalls

• Auto-merging machine fixes. The pipeline must open a PR; pushing unreviewed edits to the default branch defeats the safety model entirely.
• Skipping the re-scan. A codemod that runs but does not clear the original finding has introduced churn without value — always verify before proposing.
• Letting AI write production strings unsupervised. Treat every generated alt or aria-label as a draft in the PR body, never a committed value, until a human accepts it.
• Fixing without guarding. A remediated component with no accessibility-tree snapshot or lint rule will regress on the next refactor.
• Running codemods without a dry-run. A misfiring transform across a monorepo can produce hundreds of wrong edits that all look plausible in review.

# FAQ

Can automated remediation merge fixes without human review? No, and it should not. Every strategy in this section ends at an open pull request, not a push to the default branch. Codemod diffs are deterministic but still need a reviewer to confirm intent; AI suggestions need a human to verify the text is correct. The automation narrows and proposes the work — humans own the merge.

How is remediation different from the detection in the CI/CD section? Detection answers “is there a violation?” and gates merges, which is the focus of CI/CD Integration & Automated Quality Gating. Remediation answers “here is the proposed fix” and produces a reviewable diff. They chain together: detection output feeds the remediation classifier.

What share of WCAG violations can be auto-fixed? Scanners detect roughly 30–40% of WCAG failures, and only a subset of those — chiefly mechanical SC 1.1.1, 1.3.1, and 4.1.2 issues — are safely machine-fixable. Intent-heavy criteria such as reading order, focus order, and cognitive accessibility still require human remediation.

# Related

• Codemod-Driven Accessibility Fixes — AST transforms that bulk-fix mechanical violations.
• AI-Assisted Accessibility Remediation — generating and verifying human-readable fixes safely.
• Regression Prevention After Fixes — locking in a fix so it stays fixed.
• CI/CD Integration & Automated Quality Gating — the detection and gating layer that feeds remediation.
• axe-core Configuration & Setup — the scanner whose output drives the remediation loop.