A11Y Audit

Accessibility Audit

Run automated accessibility scans, interpret results, prioritize violations, and generate actionable fix recommendations.

Important: Automated tools catch 30-50% of WCAG violations. Always recommend manual testing for complete coverage — keyboard navigation, screen reader testing, and cognitive review cannot be automated.

1. Tool Selection Guide

Pick the right tool for the situation:

Default recommendation: Start with @axe-core/cli for URL audits, eslint-plugin-jsx-a11y for codebases.

2. Quick Start — axe-core CLI

Install

npm install -g @axe-core/cli
# or per-project
npm install --save-dev @axe-core/cli

Run a Scan

# Basic scan — human-readable output
axe https://example.com

# WCAG 2.1 AA compliance check
axe https://example.com --tags wcag2a,wcag2aa,wcag21a,wcag21aa

# JSON output to stdout (for parsing)
axe https://example.com --stdout

# JSON output to file
axe https://example.com --save report.json --dir ./results

# Multiple URLs
axe https://example.com https://example.com/about https://example.com/contact

# Scan specific rules only
axe https://example.com --rules color-contrast,image-alt,label

# Disable noisy rules
axe https://example.com --disable color-contrast

Exit Codes

• 0 — No violations found
• 1 — Violations found or error

Parse JSON Results

# Count violations by impact
axe https://example.com --stdout | jq '[.[] | .violations[] | .impact] | group_by(.) | map({(.[0]): length}) | add'

# List violation IDs and counts
axe https://example.com --stdout | jq '[.[] | .violations[] | {id: .id, count: (.nodes | length)}]'

For complete CLI reference and recipes for all tools, see: references/tool-invocation-recipes.md

3. Result Interpretation

Severity / Impact Levels

axe-core uses four impact levels. Map them to action priorities:

Result Categories

Common False Positives

Not every reported violation is a real issue:

• Color contrast on gradients/images — Tool cannot compute actual contrast against complex backgrounds. Verify manually with a contrast picker.
• Hidden elements — Elements properly hidden with display: none may still be flagged. Check if the element is truly invisible.
• Third-party widgets — Ads, embeds, chat widgets generate violations outside your control. Use --exclude or .exclude() selectors.
• Dynamic content — Scan after all content loads. Use --wait (pa11y) or waitFor (Playwright) for SPAs.

incomplete Is Not a False Positive

incomplete results mean the tool cannot determine pass/fail programmatically. Common examples:

• "Is this alt text actually descriptive?" — Only a human can judge
• "Does this color contrast meet ratio?" — Background is dynamic/complex
• Review these manually; do not auto-dismiss them.

4. Top 10 Violations Quick Reference

The most commonly detected violations across the web (based on WebAIM Million 2025 data). For the full top 20 with fix patterns, see references/top-violations.md.

These six categories account for 96.4% of detected errors on the web: missing alt text, low contrast, missing labels, missing document language, empty buttons, and empty links.

5. Fix Recommendation Templates

Use these templates when reporting fixes to developers.

Missing Alt Text (image-alt)

<!-- Before -->
<img src="hero.jpg">

<!-- After: informative image -->
<img src="hero.jpg" alt="Team collaborating around a whiteboard">

<!-- After: decorative image -->
<img src="divider.png" alt="">

Missing Form Label (label)

<!-- Before -->
<input type="email" placeholder="Email">

<!-- After: visible label (preferred) -->
<label for="email">Email</label>
<input type="email" id="email">

<!-- After: hidden label (when design requires it) -->
<label for="email" class="sr-only">Email</label>
<input type="email" id="email" placeholder="Email">

Empty Button (button-name)

<!-- Before -->
<button><svg>...</svg></button>

<!-- After -->
<button aria-label="Close dialog"><svg aria-hidden="true">...</svg></button>

Color Contrast (color-contrast)

/* Before: 2.5:1 ratio — fails AA */
.text { color: #aaaaaa; background: #ffffff; }

/* After: 4.6:1 ratio — passes AA */
.text { color: #767676; background: #ffffff; }

Missing Language (html-has-lang)

<!-- Before -->
<html>

<!-- After -->
<html lang="en">

6. Limitations

Automated accessibility testing has hard limits. Be explicit about what it cannot catch.

What automated tools detect (30-50% of WCAG):

• Missing alt text, labels, headings
• Color contrast ratios (in simple cases)
• Invalid ARIA usage
• Missing document structure (lang, title, landmarks)
• Keyboard traps (some cases)

What automated tools miss (50-70% of WCAG):

• Quality of alt text (present but meaningless)
• Logical reading order
• Keyboard navigation flow and usability
• Screen reader announcement quality
• Focus management in dynamic interactions
• Cognitive load and plain language
• Touch target adequacy beyond size
• Motion/animation sensitivity
• Content reflow at different zoom levels

Always recommend:

1. Keyboard-only navigation test (Tab through entire flow)
2. Screen reader test (NVDA on Windows, VoiceOver on macOS)
3. Zoom to 200% and check content reflow
4. Review against full WCAG 2.1 AA checklist for manual criteria

ARIA caution: Pages with ARIA attributes average 34.2% more detected errors than those without (WebAIM 2025). Prefer native HTML elements. See the aria-decision-framework skill.

7. CI Integration

pa11y-ci Configuration

Create .pa11yci in project root:

{
  "defaults": {
    "timeout": 10000,
    "concurrency": 2,
    "runners": ["axe"],
    "reporters": [
      "cli",
      ["json", { "fileName": "./a11y-results.json" }]
    ]
  },
  "urls": [
    "http://localhost:3000/",
    "http://localhost:3000/about",
    "http://localhost:3000/login"
  ]
}

# Run in CI after starting dev server
pa11y-ci --config .pa11yci

# With sitemap
pa11y-ci --sitemap http://localhost:3000/sitemap.xml

# Allow threshold for gradual adoption
pa11y-ci --threshold 5

Playwright + axe-core

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('page meets WCAG 2.1 AA', async ({ page }) => {
  await page.goto('/');

  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
    .exclude('.third-party-widget')
    .analyze();

  expect(results.violations).toEqual([]);
});

For reusable fixtures, targeted scans, and result attachment patterns, see: references/playwright-integration.md

GitHub Actions Example

- name: Accessibility audit
  run: |
    npm start &
    npx wait-on http://localhost:3000
    npx pa11y-ci --config .pa11yci

Gradual Adoption Strategy

For existing projects with many violations:

1. Baseline: Run a full scan, record the count
2. Gate on critical/serious only: --tags wcag2a,wcag2aa + threshold
3. Ratchet down: Reduce threshold as violations are fixed
4. Zero tolerance for new code: Strict eslint-plugin-jsx-a11y on changed files

8. Cross-References

For fix guidance on specific patterns:

• aria-decision-framework — When to use ARIA vs native HTML
• focus-management — Focus traps, roving tabindex, skip links
• form-a11y — Form labeling, validation, error messages
• alt-text-quality — Writing effective alt text
• live-regions — Dynamic content announcements
• cognitive-a11y — Plain language, cognitive load reduction
• css-a11y — Accessible styling patterns

Reference material in this skill:

• references/tool-invocation-recipes.md — Complete CLI commands for all tools
• references/top-violations.md — Top 20 violations with detailed fix patterns
• references/playwright-integration.md — Playwright + axe patterns and fixtures
• references/sources.yaml — All cited sources with URLs