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

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
Accessible Alternatives	Suggests replacement colors that meet contrast requirements
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
Live Region Detection	Identifies dynamic content lacking aria-live announcements
Form Accessibility	Validates label associations, error messaging, and input types

WCAG 2.2 Coverage Matrix

Principle	Level A Criteria	Level AA Criteria
Perceivable	1.1.1 Non-text Content, 1.2.1-1.2.3 Time-based Media, 1.3.1-1.3.3 Adaptable, 1.4.1-1.4.2 Distinguishable	1.3.4-1.3.5 Adaptable, 1.4.3-1.4.5 Contrast & Images of Text, 1.4.10-1.4.13 Reflow & Content
Operable	2.1.1-2.1.2 Keyboard, 2.2.1-2.2.2 Timing, 2.3.1 Seizures, 2.4.1-2.4.4 Navigable, 2.5.1-2.5.4 Input	2.4.5-2.4.7 Navigable, 2.4.11 Focus Appearance (NEW 2.2), 2.5.7 Dragging (NEW 2.2), 2.5.8 Target Size (NEW 2.2)
Understandable	3.1.1 Language, 3.2.1-3.2.2 Predictable, 3.3.1-3.3.2 Input Assistance	3.1.2 Language of Parts, 3.2.3-3.2.4 Predictable, 3.3.3-3.3.4 Error Handling, 3.3.7 Redundant Entry (NEW 2.2), 3.3.8 Accessible Auth (NEW 2.2)
Robust	4.1.2 Name/Role/Value	4.1.3 Status Messages

Severity Definitions

Severity	Definition	Example	SLA
Critical	Blocks access for entire user groups	Missing alt text on informational images, no keyboard access to primary navigation	Fix before release
Major	Significant barrier that degrades experience	Insufficient color contrast on body text, 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

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:

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

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:

#	WCAG	Severity	Issue
1	1.3.1	Critical	Inputs missing associated <label> elements
2	3.3.2	Major	Placeholder text used as only label (disappears on input)
3	2.1.1	Critical	<div @click> not keyboard accessible
4	4.1.3	Major	Error message not announced to screen readers

---

Content truncated.