a11y-audit

Accessibility Audit

WCAG 2.2 Accessibility Audit and Remediation Skill

Description

The a11y-audit skill provides a complete accessibility audit pipeline for modern web applications. It implements a three-phase workflow -- Scan, Fix, Verify -- that identifies WCAG 2.2 Level A and AA violations, generates exact fix code per framework, and produces stakeholder-ready compliance reports.

For every violation it finds, it provides the precise before/after code fix tailored to your framework (React, Next.js, Vue, Angular, Svelte, or plain HTML).

What this skill does:

1. Scans your codebase for every WCAG 2.2 Level A and AA violation, categorized by severity (Critical, Major, Minor)
2. Fixes each violation with framework-specific before/after code patterns
3. Verifies that fixes resolve the original violations and introduces no regressions
4. Reports findings in a structured format suitable for developers, PMs, and compliance stakeholders
5. Integrates into CI/CD pipelines to prevent accessibility regressions

Features

| Feature | Description |

|---------|-------------|

| Full WCAG 2.2 Scan | Checks all Level A and AA success criteria across your codebase |

| Framework Detection | Auto-detects React, Next.js, Vue, Angular, Svelte, or plain HTML |

| Severity Classification | Categorizes each violation as Critical, Major, or Minor |

| Fix Code Generation | Produces before/after code diffs for every issue |

| Color Contrast Checker | Validates foreground/background pairs against AA and AAA ratios |

| Compliance Reporting | Generates stakeholder reports with pass/fail summaries |

| CI/CD Integration | GitHub Actions, GitLab CI, Azure DevOps pipeline configs |

| Keyboard Navigation Audit | Detects missing focus management and tab order issues |

| ARIA Validation | Checks for incorrect, redundant, or missing ARIA attributes |

Severity Definitions

| Severity | Definition | Example | SLA |

|----------|-----------|---------|-----|

| Critical | Blocks access for entire user groups | Missing alt text, no keyboard access to navigation | Fix before release |

| Major | Significant barrier that degrades experience | Insufficient color contrast, missing form labels | Fix within current sprint |

| Minor | Usability issue that causes friction | Redundant ARIA roles, suboptimal heading hierarchy | Fix within next 2 sprints |

Usage

Quick Start

# Scan entire project
python scripts/a11y_scanner.py /path/to/project

# Scan with JSON output for tooling
python scripts/a11y_scanner.py /path/to/project --json

# Check color contrast for specific values
python scripts/contrast_checker.py --fg "#777777" --bg "#ffffff"

# Check contrast across a CSS/Tailwind file
python scripts/contrast_checker.py --file /path/to/styles.css

Slash Command

/a11y-audit                    # Audit current project
/a11y-audit --scope src/       # Audit specific directory
/a11y-audit --fix              # Audit and auto-apply fixes
/a11y-audit --report           # Generate stakeholder report
/a11y-audit --ci               # Output CI-compatible results

Three-Phase Workflow

Phase 1: Scan -- Walk the source tree, detect framework, apply rule set.

python scripts/a11y_scanner.py /path/to/project --format table

Phase 2: Fix -- Apply framework-specific fixes for each violation.

> See [references/framework-a11y-patterns.md](references/framework-a11y-patterns.md) for the complete fix patterns catalog.

Phase 3: Verify -- Re-run the scanner to confirm fixes and check for regressions.

python scripts/a11y_scanner.py /path/to/project --baseline audit-baseline.json

Example: React Component Audit

// BEFORE: src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <div onClick={() => navigate(`/product/${product.id}`)}>
      <img src={product.image} />
      <div style={{ color: '#aaa', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#999' }}>${product.price}</span>
    </div>
  );
}

| # | WCAG | Severity | Issue |

|---|------|----------|-------|

| 1 | 1.1.1 | Critical | <img> missing alt attribute |

| 2 | 2.1.1 | Critical | <div onClick> not keyboard accessible |

| 3 | 1.4.3 | Major | Color #aaa on white fails contrast (2.32:1, needs 4.5:1) |

| 4 | 1.4.3 | Major | Color #999 on white fails contrast (2.85:1, needs 4.5:1) |

| 5 | 4.1.2 | Major | Interactive element missing role and accessible name |

// AFTER: src/components/ProductCard.tsx
function ProductCard({ product }) {
  return (
    <a href={`/product/${product.id}`} className="product-card"
       aria-label={`View ${product.name} - $${product.price}`}>
      <img src={product.image} alt={product.imageAlt || product.name} />
      <div style={{ color: '#595959', fontSize: '12px' }}>{product.name}</div>
      <span style={{ color: '#767676' }}>${product.price}</span>
    </a>
  );
}

> See [references/examples-by-framework.md](references/examples-by-framework.md) for Vue, Angular, Next.js, and Svelte examples.

Tools Reference

a11y_scanner.py

Usage: python scripts/a11y_scanner.py <path> [options]

Options:
  --json                  Output results as JSON
  --format {table,csv}    Output format (default: table)
  --severity {critical,major,minor}  Filter by minimum severity
  --framework {react,vue,angular,svelte,html,auto}  Force framework (default: auto)
  --baseline FILE         Compare against previous scan results
  --report                Generate stakeholder report
  --output FILE           Write results to file
  --quiet                 Suppress output, exit code only
  --ci                    CI mode: non-zero exit on critical issues

contrast_checker.py

Usage: python scripts/contrast_checker.py [options]

Options:
  --fg COLOR              Foreground color (hex)
  --bg COLOR              Background color (hex)
  --file FILE             Scan CSS file for color pairs
  --tailwind DIR          Scan directory for Tailwind color classes
  --json                  Output results as JSON
  --suggest               Suggest accessible alternatives for failures
  --level {aa,aaa}        Target conformance level (default: aa)

Common Pitfalls

| Pitfall | Correct Approach |

|---------|------------------|

| role="button" on a <div> | Use native <button> -- includes keyboard handling for free |

| tabindex="0" on everything | Only interactive elements need focus; use native elements |

| aria-label on non-interactive elements | Use aria-labelledby pointing to visible text |

| display: none for screen reader hiding | Use .sr-only class instead |

| Color alone to convey meaning | Add icons, text labels, or patterns alongside color |

| Placeholder as only label | Always provide a visible <label> |

| outline: none without replacement | Always provide a visible focus indicator via focus-visible |

| Empty alt="" on informational images | Informational images need descriptive alt text |

| Skipping heading levels (h1 -> h3) | Heading levels must be sequential |

| onClick without onKeyDown | Add keyboard support or prefer native elements |

| Ignoring prefers-reduced-motion | Wrap animations in @media (prefers-reduced-motion: no-preference) |

Related Skills

| Skill | Relationship |

|-------|-------------|

| senior-frontend | Frontend patterns used in a11y fixes |

| code-reviewer | Include a11y checks in code review workflows |

| senior-qa | Integration of a11y testing into QA processes |

| playwright-pro | Automated browser testing with accessibility assertions |

| epic-design | WCAG 2.1 AA compliant animations and scroll storytelling |

| tdd-guide | Test-driven development patterns for a11y test cases |

Reference Documentation

| Reference | Description |

|-----------|-------------|

| [wcag-quick-ref.md](references/wcag-quick-ref.md) | WCAG 2.2 Level A & AA criteria quick reference |

| [wcag-22-new-criteria.md](references/wcag-22-new-criteria.md) | New WCAG 2.2 success criteria (Focus Appearance, Target Size, etc.) |

| [aria-patterns.md](references/aria-patterns.md) | ARIA patterns, keyboard interaction, and live regions |

| [framework-a11y-patterns.md](references/framework-a11y-patterns.md) | Framework-specific fix patterns (React, Vue, Angular, Svelte, HTML) |

| [color-contrast-guide.md](references/color-contrast-guide.md) | Color contrast checker details, Tailwind palette mapping, sr-only class |

| [ci-cd-integration.md](references/ci-cd-integration.md) | GitHub Actions, GitLab CI, Azure DevOps, pre-commit hook configs |

| [audit-report-template.md](references/audit-report-template.md) | Stakeholder-ready audit report template |

| [testing-checklist.md](references/testing-checklist.md) | Manual testing checklist (keyboard, screen reader, visual, forms) |

| [examples-by-framework.md](references/examples-by-framework.md) | Full audit examples for Vue, Angular, Next.js, and Svelte |

Resources

• WCAG 2.2 Specification
• WAI-ARIA Authoring Practices 1.2
• Deque axe-core Rules
• eslint-plugin-jsx-a11y