Accessibility Audit
Check web content against WCAG 2.2 AA standards with detailed fix recommendations.
Installation
- Make sure Claude is on your device and in your terminal.
Skills load from
~/.claude/skills/when Claude Code starts up β so you need it on your machine first. If you don't have it yet, install it once with the command below, then runclaudein any terminal to verify.One-time setupnpm i -g @anthropic-ai/claude-codeAlready have it? Skip ahead.
- Paste into Claude Code or into your terminal.
This copies the whole skill folder into
~/.claude/skills/accessibility-audit-me2resh/β the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Works for every skill.What this command does
- Makes a new, empty temporary folder.
- Downloads the skill's folder,
.claude/skills/accessibility-audit, fromgithub.com/me2resh/apexyard(branchmain), the GitHub repository it's listed from. You get the version that is there now, not a copy we keep. - Copies that folder to
~/.claude/skills/accessibility-audit-me2resh/. - Deletes the temporary folder.
Installing runs none of the skill's files; it only downloads and copies them. When you later use the skill, Claude follows its SKILL.md and may run scripts that come with it. Read them first.
Faster alternative (instruction-only skills)
Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates β they won't be downloaded and the skill will fail when it tries to load them.
Quick install (SKILL.md only)Sign up to copy - Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from
~/.claude/skills/). New skills are picked up on startup. - Just ask Claude.
Skills auto-activate when your request matches the skill's description β no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the βWhat this skill doesβ section above.
Prefer to read the source first? Open on GitHub.
When Claude uses it
WCAG 2.2 AA audit β perceivable, operable, understandable, robust criteria. Deep-dive for /launch-check accessibility.
What this skill does
Writing: read docs/skills/shared/writing-rule.md before you write a durable artifact.
/accessibility-audit β WCAG 2.2 AA Compliance
Deep-dive accessibility analysis against the Web Content Accessibility Guidelines 2.2 Level AA. Produces a prioritized findings list with fix instructions. Invoke when /launch-check's accessibility row shows WARN or FAIL, or proactively for any user-facing app.
WCAG Principles (POUR)
| Principle | What it means | Key checks |
|---|---|---|
| Perceivable | Content must be presentable in ways users can perceive | Alt text, captions, color contrast, text resizing |
| Operable | Interface must be navigable and usable | Keyboard access, focus management, skip links, timing |
| Understandable | Content and UI must be understandable | Language declaration, consistent navigation, error identification |
| Robust | Content must work across assistive technologies | Valid HTML, ARIA usage, semantic elements |
Process
Step 1: Scan for structural issues
Grep the codebase for common accessibility failures:
<imgwithoutaltattribute<inputwithout associated<label>oraria-labelonClickwithoutonKeyDown/onKeyPress(keyboard inaccessible)<div>or<span>used as buttons withoutrole="button"andtabIndex- Missing
<html lang="...">attribute - Heading hierarchy gaps (h1 β h3 with no h2)
- Missing
<main>,<nav>,<header>,<footer>landmarks - Color values with insufficient contrast ratios (check theme files / CSS variables)
- Missing skip-to-content link
- Auto-playing media without controls
- Forms without error identification (
aria-invalid,aria-describedby)
Step 2: Check ARIA usage
aria-labelon interactive elements without visible textaria-hidden="true"not applied to decorative elementsroleattributes used correctly (notrole="button"on a<div>that should be a<button>)- Live regions (
aria-live) for dynamic content updates aria-expanded/aria-controlson expandable sections
Step 3: Output findings
ACCESSIBILITY AUDIT β <project> @ <sha>
| # | WCAG | Criterion | Severity | Finding | Fix |
|----|------|-----------|----------|---------|-----|
| A1 | 1.1.1 | Non-text content | HIGH | 12 images missing alt text | Add descriptive alt attributes |
| A2 | 2.1.1 | Keyboard | HIGH | 3 onClick handlers without keyboard equivalent | Add onKeyDown with Enter/Space handling |
| A3 | 1.4.3 | Contrast | MEDIUM | Button text #999 on #fff = 2.8:1 (needs 4.5:1) | Darken to #767676 or darker |
| A4 | 2.4.1 | Skip nav | LOW | No skip-to-content link | Add <a href="#main" class="skip-link"> |
Summary: <N> findings (<N> high, <N> medium, <N> low)
WCAG 2.2 AA estimate: <PASS / PARTIAL / FAIL>
Persist the run + render trend
After printing the findings table, persist via the shared audit-history lib so the accessibility trend across runs becomes legible. See docs/agdr/AgDR-0019-audit-artefact-persistence.md.
Resolve project name + score + verdict
<project-name> from apexyard.projects.yaml (or basename + /handover reminder if unregistered).
Score: score = max(0, 100 - 25*critical - 10*high - 3*medium - 1*low). Verdict by worst-severity: critical/high β fail, medium β conditional, low/none β pass. Legacy "WCAG 2.2 AA estimate" three-state: FAIL β fail, PARTIAL β conditional, PASS β pass.
Persist + render
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-audit-history.sh"
# Lowercase severity in the payload β the lib expects critical/high/medium/low/info.
payload=$(mktemp); cat > "$payload" <<'EOF'
{
"schema_version": 1,
"findings": [
{"id": "A1", "severity": "high", "status": "open", "summary": "Images missing alt text (WCAG 1.1.1)"},
{"id": "A2", "severity": "high", "status": "open", "summary": "onClick handlers without keyboard equivalent (WCAG 2.1.1)"},
{"id": "A3", "severity": "medium", "status": "open", "summary": "Button text contrast 2.8:1, needs 4.5:1 (WCAG 1.4.3)"}
]
}
EOF
# Body: per templates/audits/accessibility-audit.md (POUR-grouped table)
body=$(mktemp); cat > "$body" <<'EOF'
... (filled-in body β POUR groupings + Recommended priority) ...
EOF
ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
audit_run_persist "<project-name>" "accessibility-audit" "$ts" "fail" 60 "$body" < "$payload"
rm -f "$payload" "$body"
audit_render_trend "<project-name>" "accessibility-audit" 5
Opt-in commit
touch projects/<name>/audits/accessibility-audit/.audit-history-tracked
Rules
- Cite WCAG criteria numbers (e.g. 1.1.1, 2.1.1) so findings are traceable to the spec.
- Prioritize by user impact, not by WCAG level. A missing alt on a hero image is worse than a missing skip link.
- Auto-PASS for non-UI projects. CLIs, APIs, and libraries don't need this audit.
- Give copy-pasteable fixes where possible (the exact HTML/JSX to add, not just "fix the contrast").
- Always persist via the lib. The persist step runs regardless of opt-in commit state.
- Severity vocabulary in the JSON is lowercase. The lib expects
critical/high/medium/low/info. The visible findings table can keep its conventional capitalisation.
Part of ApexYard β multi-project SDLC framework for Claude Code Β· MIT.
Related skills
Generative Code Art
anthropics
Create algorithmic art with p5.js using randomness and interactive parameters.
UI/UX Pro Max
anthropics
Build production-grade web components and interfaces with distinctive, polished design.
Artifact Theme Toolkit
anthropics
Apply professional color and font themes to slides, docs, and web pages.
Multi-Component Web Artifacts
anthropics
Build complex React artifacts with Tailwind CSS and shadcn/ui components.