Skip to content

Commit 0561ed5

Browse files
alirezarezvaniclaude
alirezarezvani
and
claude
committed
feat(engineering-team): add a11y-audit skill — WCAG 2.2 accessibility audit & fix
Built from scratch (replaces reverted PR #375 contribution). Skill package: - SKILL.md: 1132 lines, 3-phase workflow (scan → fix → verify), per-framework fix patterns (React, Next.js, Vue, Angular, Svelte, HTML), CI/CD integration guide, 20+ issue type coverage - scripts/a11y_scanner.py: static scanner detecting 20+ violation types across HTML/JSX/TSX/Vue/Svelte/CSS — severity-ranked, CI-friendly exit codes - scripts/contrast_checker.py: WCAG contrast calculator with AA/AAA checks, --suggest mode, --batch CSS scanning, named color support - references/wcag-quick-ref.md: WCAG 2.2 Level A/AA criteria table - references/aria-patterns.md: ARIA roles, live regions, keyboard interaction - references/framework-a11y-patterns.md: React, Vue, Angular, Svelte fix patterns - assets/sample-component.tsx: sample file with intentional violations - expected_outputs/: scan report, contrast output, JSON output samples - /a11y-audit slash command, settings.json, plugin.json, README.md Validation: 97.6/100 (EXCELLENT), quality 73.9/100 (B-), scripts 2/2 PASS Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 85eb7de commit 0561ed5

14 files changed

Lines changed: 3558 additions & 0 deletions

File tree

‎commands/a11y-audit.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
name: a11y-audit
3+
description: Scan a frontend project for WCAG 2.2 accessibility violations and fix them. Usage: /a11y-audit [path]
4+
---
5+
6+
# /a11y-audit
7+
8+
Scan a frontend project for WCAG 2.2 accessibility issues, show fixes, and optionally check color contrast.
9+
10+
## Usage
11+
12+
```bash
13+
/a11y-audit # Scan current project
14+
/a11y-audit ./src # Scan specific directory
15+
/a11y-audit ./src --fix # Scan and auto-fix what's possible
16+
```
17+
18+
## What It Does
19+
20+
### Step 1: Scan
21+
22+
Run the a11y scanner on the target directory:
23+
24+
```bash
25+
python3 {skill_path}/scripts/a11y_scanner.py {path} --json
26+
```
27+
28+
Parse the JSON output. Group findings by severity (critical → serious → moderate → minor).
29+
30+
Display a summary:
31+
```
32+
A11y Audit: ./src
33+
Critical: 3 | Serious: 7 | Moderate: 12 | Minor: 5
34+
Files scanned: 42 | Files with issues: 15
35+
```
36+
37+
### Step 2: Fix
38+
39+
For each finding (starting with critical):
40+
41+
1. Read the affected file
42+
2. Show the violation with context (before)
43+
3. Apply the fix from `references/framework-a11y-patterns.md`
44+
4. Show the result (after)
45+
46+
**Auto-fixable issues** (apply without asking):
47+
- Missing `alt=""` on decorative images
48+
- Missing `lang` attribute on `<html>`
49+
- `tabindex` values > 0 → set to 0
50+
- Missing `type="button"` on non-submit buttons
51+
- Outline removal without replacement → add `:focus-visible` styles
52+
53+
**Issues requiring user input** (show fix, ask to apply):
54+
- Missing alt text (need description from user)
55+
- Missing form labels (need label text)
56+
- Heading restructuring (may affect layout)
57+
- ARIA role changes (may affect functionality)
58+
59+
### Step 3: Contrast Check
60+
61+
If CSS files are present, run the contrast checker:
62+
63+
```bash
64+
python3 {skill_path}/scripts/contrast_checker.py --batch {path}
65+
```
66+
67+
For each failing color pair, suggest accessible alternatives.
68+
69+
### Step 4: Report
70+
71+
Generate a markdown report at `a11y-report.md`:
72+
- Executive summary (pass/fail, issue counts)
73+
- Per-file findings with before/after diffs
74+
- Remaining manual review items
75+
- WCAG criteria coverage
76+
77+
## Skill Reference
78+
79+
- `engineering-team/a11y-audit/SKILL.md`
80+
- `engineering-team/a11y-audit/scripts/a11y_scanner.py`
81+
- `engineering-team/a11y-audit/scripts/contrast_checker.py`
82+
- `engineering-team/a11y-audit/references/wcag-quick-ref.md`
83+
- `engineering-team/a11y-audit/references/aria-patterns.md`
84+
- `engineering-team/a11y-audit/references/framework-a11y-patterns.md`

‎engineering-team/a11y-audit/.claude-plugin/plugin.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"name": "a11y-audit",
3+
"description": "WCAG 2.2 accessibility audit and fix skill for React, Next.js, Vue, Angular, Svelte, and HTML. Static scanner detecting 20+ violation types, contrast checker with suggest mode, framework-specific fix patterns, CI-friendly exit codes.",
4+
"version": "2.1.2",
5+
"author": "Alireza Rezvani",
6+
"homepage": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering-team/a11y-audit",
7+
"repository": "https://github.com/alirezarezvani/claude-skills",
8+
"license": "MIT",
9+
"skills": "./"
10+
}

‎engineering-team/a11y-audit/README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# A11y Audit — WCAG 2.2 Accessibility Audit & Fix
2+
3+
Audit and fix WCAG 2.2 accessibility issues in any frontend project. Covers React, Next.js, Vue, Angular, Svelte, and plain HTML.
4+
5+
## Quick Start
6+
7+
```bash
8+
# Scan a project
9+
/a11y-audit ./src
10+
11+
# Or use the scripts directly
12+
python3 scripts/a11y_scanner.py ./src
13+
python3 scripts/contrast_checker.py "#1a1a2e" "#ffffff"
14+
```
15+
16+
## Scripts
17+
18+
| Script | Purpose |
19+
|--------|---------|
20+
| `a11y_scanner.py` | Scan HTML/JSX/TSX/Vue/Svelte/CSS for 20+ a11y violations |
21+
| `contrast_checker.py` | WCAG contrast ratio calculator with AA/AAA checks and `--suggest` mode |
22+
23+
Both are stdlib-only — no pip install needed. CI-friendly exit codes (0 = pass, 1 = blocking issues).
24+
25+
## What It Covers
26+
27+
- **Images**: missing alt, empty alt on informative images
28+
- **Forms**: missing labels, orphan labels, missing fieldset/legend
29+
- **Headings**: skipped levels, missing h1, multiple h1s
30+
- **Landmarks**: missing main/nav/skip link
31+
- **Keyboard**: tabindex > 0, click without keyboard handler
32+
- **ARIA**: invalid attributes, aria-hidden on focusable, missing aria-live
33+
- **Color**: contrast ratios below AA thresholds
34+
- **Links**: empty links, "click here" text
35+
- **Tables**: missing headers, missing caption
36+
- **Media**: missing captions, autoplay without controls
37+
38+
## References
39+
40+
- `references/wcag-quick-ref.md` — WCAG 2.2 Level A/AA criteria table
41+
- `references/aria-patterns.md` — ARIA roles, live regions, keyboard patterns
42+
- `references/framework-a11y-patterns.md` — React, Vue, Angular, Svelte fix patterns
43+
44+
## License
45+
46+
MIT

0 commit comments

Comments
 (0)