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:
- Scans your codebase for every WCAG 2.2 Level A and AA violation, categorized by severity (Critical, Major, Minor)
- Fixes each violation with framework-specific before/after code patterns
- Verifies that fixes resolve the original violations and introduces no regressions
- Reports findings in a structured format suitable for developers, PMs, and compliance stakeholders
- 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 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 => 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 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 |
WCAG 2.2 Level A & AA criteria quick reference |
| wcag-22-new-criteria.md |
New WCAG 2.2 success criteria (Focus Appearance, Target Size, etc.) |
| aria-patterns.md |
ARIA patterns, keyboard interaction, and live regions |
| framework-a11y-patterns.md |
Framework-specific fix patterns (React, Vue, Angular, Svelte, HTML) |
| color-contrast-guide.md |
Color contrast checker details, Tailwind palette mapping, sr-only class |
| ci-cd-integration.md |
GitHub Actions, GitLab CI, Azure DevOps, pre-commit hook configs |
| audit-report-template.md |
Stakeholder-ready audit report template |
| testing-checklist.md |
Manual testing checklist (keyboard, screen reader, visual, forms) |
| examples-by-framework.md |
Full audit examples for Vue, Angular, Next.js, and Svelte |
Resources
1---2name: "a11y-audit"3description: "Use for any accessibility audit or a11y fix (WCAG 2.2 A/AA, color contrast, compliance report, CI check) in React, Next.js, Vue, Angular, Svelte or HTML. Scans with a11y_scanner.py and checks contrast with contrast_checker.py, then fixes and re-verifies."4metadata:5 source: https://skillmd.com/skills/alirezarezvani/a11y-audit6---78# Accessibility Audit910WCAG 2.2 Accessibility Audit and Remediation Skill1112## Description1314The 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.1516For 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).1718**What this skill does:**19201. **Scans** your codebase for every WCAG 2.2 Level A and AA violation, categorized by severity (Critical, Major, Minor)212. **Fixes** each violation with framework-specific before/after code patterns223. **Verifies** that fixes resolve the original violations and introduces no regressions234. **Reports** findings in a structured format suitable for developers, PMs, and compliance stakeholders245. **Integrates** into CI/CD pipelines to prevent accessibility regressions2526## Features2728| Feature | Description |29|---------|-------------|30| **Full WCAG 2.2 Scan** | Checks all Level A and AA success criteria across your codebase |31| **Framework Detection** | Auto-detects React, Next.js, Vue, Angular, Svelte, or plain HTML |32| **Severity Classification** | Categorizes each violation as Critical, Major, or Minor |33| **Fix Code Generation** | Produces before/after code diffs for every issue |34| **Color Contrast Checker** | Validates foreground/background pairs against AA and AAA ratios |35| **Compliance Reporting** | Generates stakeholder reports with pass/fail summaries |36| **CI/CD Integration** | GitHub Actions, GitLab CI, Azure DevOps pipeline configs |37| **Keyboard Navigation Audit** | Detects missing focus management and tab order issues |38| **ARIA Validation** | Checks for incorrect, redundant, or missing ARIA attributes |3940### Severity Definitions4142| Severity | Definition | Example | SLA |43|----------|-----------|---------|-----|44| **Critical** | Blocks access for entire user groups | Missing alt text, no keyboard access to navigation | Fix before release |45| **Major** | Significant barrier that degrades experience | Insufficient color contrast, missing form labels | Fix within current sprint |46| **Minor** | Usability issue that causes friction | Redundant ARIA roles, suboptimal heading hierarchy | Fix within next 2 sprints |4748## Usage4950### Quick Start5152```bash53# Scan entire project54python scripts/a11y_scanner.py /path/to/project5556# Scan with JSON output for tooling57python scripts/a11y_scanner.py /path/to/project --json5859# Check color contrast for specific values60python scripts/contrast_checker.py --fg "#777777" --bg "#ffffff"6162# Check contrast across a CSS/Tailwind file63python scripts/contrast_checker.py --file /path/to/styles.css64```6566### Slash Command6768```69/a11y-audit # Audit current project70/a11y-audit --scope src/ # Audit specific directory71/a11y-audit --fix # Audit and auto-apply fixes72/a11y-audit --report # Generate stakeholder report73/a11y-audit --ci # Output CI-compatible results74```7576### Three-Phase Workflow7778**Phase 1: Scan** -- Walk the source tree, detect framework, apply rule set.7980```bash81python scripts/a11y_scanner.py /path/to/project --format table82```8384**Phase 2: Fix** -- Apply framework-specific fixes for each violation.8586> See [references/framework-a11y-patterns.md](references/framework-a11y-patterns.md) for the complete fix patterns catalog.8788**Phase 3: Verify** -- Re-run the scanner to confirm fixes and check for regressions.8990```bash91python scripts/a11y_scanner.py /path/to/project --baseline audit-baseline.json92```9394## Example: React Component Audit9596```tsx97// BEFORE: src/components/ProductCard.tsx98function ProductCard({ product }) {99 return (100 <div onClick={() => navigate(`/product/${product.id}`)}>101 <img src={product.image} />102 <div style={{ color: '#aaa', fontSize: '12px' }}>{product.name}</div>103 <span style={{ color: '#999' }}>${product.price}</span>104 </div>105 );106}107```108109| # | WCAG | Severity | Issue |110|---|------|----------|-------|111| 1 | 1.1.1 | Critical | `<img>` missing `alt` attribute |112| 2 | 2.1.1 | Critical | `<div onClick>` not keyboard accessible |113| 3 | 1.4.3 | Major | Color `#aaa` on white fails contrast (2.32:1, needs 4.5:1) |114| 4 | 1.4.3 | Major | Color `#999` on white fails contrast (2.85:1, needs 4.5:1) |115| 5 | 4.1.2 | Major | Interactive element missing role and accessible name |116117```tsx118// AFTER: src/components/ProductCard.tsx119function ProductCard({ product }) {120 return (121 <a href={`/product/${product.id}`} className="product-card"122 aria-label={`View ${product.name} - $${product.price}`}>123 <img src={product.image} alt={product.imageAlt || product.name} />124 <div style={{ color: '#595959', fontSize: '12px' }}>{product.name}</div>125 <span style={{ color: '#767676' }}>${product.price}</span>126 </a>127 );128}129```130131> See [references/examples-by-framework.md](references/examples-by-framework.md) for Vue, Angular, Next.js, and Svelte examples.132133## Tools Reference134135### a11y_scanner.py136137```138Usage: python scripts/a11y_scanner.py <path> [options]139140Options:141 --json Output results as JSON142 --format {table,csv} Output format (default: table)143 --severity {critical,major,minor} Filter by minimum severity144 --framework {react,vue,angular,svelte,html,auto} Force framework (default: auto)145 --baseline FILE Compare against previous scan results146 --report Generate stakeholder report147 --output FILE Write results to file148 --quiet Suppress output, exit code only149 --ci CI mode: non-zero exit on critical issues150```151152### contrast_checker.py153154```155Usage: python scripts/contrast_checker.py [options]156157Options:158 --fg COLOR Foreground color (hex)159 --bg COLOR Background color (hex)160 --file FILE Scan CSS file for color pairs161 --tailwind DIR Scan directory for Tailwind color classes162 --json Output results as JSON163 --suggest Suggest accessible alternatives for failures164 --level {aa,aaa} Target conformance level (default: aa)165```166167## Common Pitfalls168169| Pitfall | Correct Approach |170|---------|------------------|171| `role="button"` on a `<div>` | Use native `<button>` -- includes keyboard handling for free |172| `tabindex="0"` on everything | Only interactive elements need focus; use native elements |173| `aria-label` on non-interactive elements | Use `aria-labelledby` pointing to visible text |174| `display: none` for screen reader hiding | Use `.sr-only` class instead |175| Color alone to convey meaning | Add icons, text labels, or patterns alongside color |176| Placeholder as only label | Always provide a visible `<label>` |177| `outline: none` without replacement | Always provide a visible focus indicator via `focus-visible` |178| Empty `alt=""` on informational images | Informational images need descriptive alt text |179| Skipping heading levels (h1 -> h3) | Heading levels must be sequential |180| `onClick` without `onKeyDown` | Add keyboard support or prefer native elements |181| Ignoring `prefers-reduced-motion` | Wrap animations in `@media (prefers-reduced-motion: no-preference)` |182183## Related Skills184185| Skill | Relationship |186|-------|-------------|187| **senior-frontend** | Frontend patterns used in a11y fixes |188| **code-reviewer** | Include a11y checks in code review workflows |189| **senior-qa** | Integration of a11y testing into QA processes |190| **playwright-pro** | Automated browser testing with accessibility assertions |191| **epic-design** | WCAG 2.1 AA compliant animations and scroll storytelling |192| **tdd-guide** | Test-driven development patterns for a11y test cases |193194## Reference Documentation195196| Reference | Description |197|-----------|-------------|198| [wcag-quick-ref.md](references/wcag-quick-ref.md) | WCAG 2.2 Level A & AA criteria quick reference |199| [wcag-22-new-criteria.md](references/wcag-22-new-criteria.md) | New WCAG 2.2 success criteria (Focus Appearance, Target Size, etc.) |200| [aria-patterns.md](references/aria-patterns.md) | ARIA patterns, keyboard interaction, and live regions |201| [framework-a11y-patterns.md](references/framework-a11y-patterns.md) | Framework-specific fix patterns (React, Vue, Angular, Svelte, HTML) |202| [color-contrast-guide.md](references/color-contrast-guide.md) | Color contrast checker details, Tailwind palette mapping, sr-only class |203| [ci-cd-integration.md](references/ci-cd-integration.md) | GitHub Actions, GitLab CI, Azure DevOps, pre-commit hook configs |204| [audit-report-template.md](references/audit-report-template.md) | Stakeholder-ready audit report template |205| [testing-checklist.md](references/testing-checklist.md) | Manual testing checklist (keyboard, screen reader, visual, forms) |206| [examples-by-framework.md](references/examples-by-framework.md) | Full audit examples for Vue, Angular, Next.js, and Svelte |207208## Resources209210- [WCAG 2.2 Specification](https://www.w3.org/TR/WCAG22/)211- [WAI-ARIA Authoring Practices 1.2](https://www.w3.org/WAI/ARIA/apg/)212- [Deque axe-core Rules](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md)213- [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)