AugmentClaude

Accessibility Audit

Check web content against WCAG 2.2 AA standards with detailed fix recommendations.

Installation

  1. 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 run claude in any terminal to verify.

    One-time setup
    npm i -g @anthropic-ai/claude-code

    Already have it? Skip ahead.

  2. 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
    1. Makes a new, empty temporary folder.
    2. Downloads the skill's folder, .claude/skills/accessibility-audit, from github.com/me2resh/apexyard (branch main), the GitHub repository it's listed from. You get the version that is there now, not a copy we keep.
    3. Copies that folder to ~/.claude/skills/accessibility-audit-me2resh/.
    4. 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.

    How we check skills, and what we don't Β· Report this skill

    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
  3. Restart Claude Code.

    Quit and reopen Claude Code (or any other agent that loads from ~/.claude/skills/). New skills are picked up on startup.

  4. 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)

PrincipleWhat it meansKey checks
PerceivableContent must be presentable in ways users can perceiveAlt text, captions, color contrast, text resizing
OperableInterface must be navigable and usableKeyboard access, focus management, skip links, timing
UnderstandableContent and UI must be understandableLanguage declaration, consistent navigation, error identification
RobustContent must work across assistive technologiesValid HTML, ARIA usage, semantic elements

Process

Step 1: Scan for structural issues

Grep the codebase for common accessibility failures:

  • <img without alt attribute
  • <input without associated <label> or aria-label
  • onClick without onKeyDown / onKeyPress (keyboard inaccessible)
  • <div> or <span> used as buttons without role="button" and tabIndex
  • 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-label on interactive elements without visible text
  • aria-hidden="true" not applied to decorative elements
  • role attributes used correctly (not role="button" on a <div> that should be a <button>)
  • Live regions (aria-live) for dynamic content updates
  • aria-expanded / aria-controls on 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

  1. Cite WCAG criteria numbers (e.g. 1.1.1, 2.1.1) so findings are traceable to the spec.
  2. Prioritize by user impact, not by WCAG level. A missing alt on a hero image is worse than a missing skip link.
  3. Auto-PASS for non-UI projects. CLIs, APIs, and libraries don't need this audit.
  4. Give copy-pasteable fixes where possible (the exact HTML/JSX to add, not just "fix the contrast").
  5. Always persist via the lib. The persist step runs regardless of opt-in commit state.
  6. 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