a11y-audit

Accessibility Audit

Name: a11y-audit Tier: STANDARD Category: Engineering - Frontend Quality Dependencies: Python 3.8+ (Standard Library Only) Author: Alireza Rezvani Version: 2.1.2 Last Updated: 2026-03-18 License: MIT

Name

a11y-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.

This skill goes beyond detection. 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). It understands that a missing alt attribute on an <img> in React JSX requires a different fix pattern than the same issue in a Vue SFC or an Angular template.

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

Key differentiators:

• Framework-aware fix patterns (not generic HTML advice)
• Color contrast analysis with accessible alternative suggestions
• WCAG 2.2 coverage including the newest success criteria (Focus Appearance, Dragging Movements, Target Size)
• CI/CD pipeline integration with GitHub Actions, GitLab CI, and Azure DevOps
• Slash command support via /a11y-audit

Features

Core Capabilities

WCAG 2.2 Coverage Matrix

Severity Definitions

Usage

Quick Start

Activate the skill and run an audit on your project:

# 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

Use the /a11y-audit slash command for an interactive audit session:

/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

The scanner walks your source tree, detects the framework in use, and applies the appropriate rule set.

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

Sample output:

A11Y AUDIT REPORT - /path/to/project
Framework Detected: React (Next.js)
Files Scanned: 127
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CRITICAL (3 issues)
  [1.1.1] src/components/Hero.tsx:14
    Missing alt text on <img> element
  [2.1.1] src/components/Modal.tsx:8
    Focus not trapped inside modal dialog
  [1.4.3] src/styles/globals.css:42
    Contrast ratio 2.8:1 on .subtitle (requires 4.5:1)

MAJOR (7 issues)
  [2.4.11] src/components/Button.tsx:22
    Focus indicator not visible (2px outline required)
  [1.3.1] src/components/Form.tsx:31
    Input missing associated <label>
  ...

MINOR (4 issues)
  [1.3.1] src/components/Nav.tsx:5
    <nav> has redundant role="navigation"
  ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SUMMARY: 14 violations (3 Critical, 7 Major, 4 Minor)
WCAG 2.2 Level A:  8 issues
WCAG 2.2 Level AA: 6 issues

Phase 2: Fix

For each violation, apply the framework-specific fix. The skill provides exact before/after code for every issue type.

See the Fix Patterns by Framework section below for the complete fix catalog.

Phase 3: Verify

Re-run the scanner to confirm all fixes are applied and no regressions were introduced:

# Re-scan after fixes
python scripts/a11y_scanner.py /path/to/project --format table

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

Verification output:

VERIFICATION RESULTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Previous Scan:  14 violations (3 Critical, 7 Major, 4 Minor)
Current Scan:    2 violations (0 Critical, 1 Major, 1 Minor)
Resolved:       12 violations
New Issues:      0 regressions

STATUS: IMPROVED (85.7% reduction)

Examples

Example 1: React Component Audit

Given a React component with multiple accessibility issues:

// 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>
  );
}

Violations detected:

// 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>
  );
}

What changed:

• <div onClick> replaced with <a href> for native keyboard and screen reader support
• alt attribute added to <img> with meaningful fallback
• aria-label provides full context for assistive technology
• Color #aaa replaced with #595959 (7.01:1 contrast ratio -- passes AA and AAA)
• Color #999 replaced with #767676 (4.54:1 contrast ratio -- passes AA)

Example 2: Vue SFC Form Audit

<!-- BEFORE: src/components/LoginForm.vue -->
<template>
  <form @submit="handleLogin">
    <input type="text" placeholder="Email" v-model="email" />
    <input type="password" placeholder="Password" v-model="password" />
    <div v-if="error" style="color: red">{{ error }}</div>
    <div @click="handleLogin">Sign In</div>
  </form>
</template>

Violations detected:

Content truncated.