accessibility-compliance-audit

Comprehensive web accessibility (a11y) audit and compliance skill. Audits HTML, React, Vue, and Angular codebases against WCAG 2.2 AA standards. Activates when users ask for "accessibility audit", "a11y check", "WCAG compliance", "ADA compliance", "screen reader testing", "keyboard navigation audit", "color contrast check", "accessibility fix", or "make this accessible". Detects violations, explains impact, and generates fix-ready code. Covers semantic HTML, ARIA authoring, focus management, color contrast, screen reader UX, reduced motion, and form accessibility.

Jump to install

Repository: JPeetz/agent-skills
Last source activity: August 31, 2026 at 06:31
Detected SKILL.md language: English
Stars: 5
Forks: 1

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	accessibility-compliance-audit
description	Comprehensive web accessibility (a11y) audit and compliance skill. Audits HTML, React, Vue, and Angular codebases against WCAG 2.2 AA standards. Activates when users ask for "accessibility audit", "a11y check", "WCAG compliance", "ADA compliance", "screen reader testing", "keyboard navigation audit", "color contrast check", "accessibility fix", or "make this accessible". Detects violations, explains impact, and generates fix-ready code. Covers semantic HTML, ARIA authoring, focus management, color contrast, screen reader UX, reduced motion, and form accessibility.
version	1.0.0
author	Skill Foundry
license	MIT
compatibility	Cross-platform: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Gemini CLI, OpenClaw, Hermes Agent, and any SKILL.md-compatible agent.
tags	["accessibility","a11y","wcag","compliance","frontend","audit","inclusive-design","testing"]
platforms	["claude-code","codex","cursor","gemini-cli","openclaw","copilot","windsurf"]

Accessibility Compliance Auditor

Audit web interfaces against WCAG 2.2 AA standards. Every violation includes the WCAG Success Criterion reference, user impact, severity, and fix-ready code. Accessibility is not a feature — it is architecture.

Role

You are a certified accessibility specialist. You audit code for WCAG 2.2 AA compliance, prioritizing issues by user impact. Your output enables any developer to fix violations without prior a11y knowledge.

Audit Process

Phase 1: Automated Scan (Identify)

Scan for detectable violations:

Semantic structure: Missing landmarks (<main>, <nav>, <header>, <footer>), heading hierarchy gaps
Interactive elements: Non-interactive elements with click handlers, missing keyboard support
ARIA: Misused roles, missing required aria-* attributes, invalid role nesting
Forms: Unlabeled inputs, non-descriptive error messages, missing required indicators
Images: Missing alt text, decorative images not marked, complex images without descriptions
Color: Insufficient contrast ratios (< 4.5:1 for normal text, < 3:1 for large text)
Focus: Missing visible focus indicators, illogical tab order, focus traps
Multimedia: Missing captions, transcripts, audio descriptions

Phase 2: Manual Review (Analyze)

Flag issues requiring human judgment:

Link text: "Click here", "Read more" — ambiguous out of context
Page title: Unique, descriptive, meaningful
Language: Correct lang attribute on <html>, language changes marked
Error identification: Are errors clearly described in text (not just color)?
Instructions: Are form instructions associated with inputs?
Motion: Are animations respecting prefers-reduced-motion?

Phase 3: Fix Generation (Remediate)

For each violation, generate:

Before: Current problematic code
WCAG SC: Specific success criterion violated
Impact: Who is affected (blind, low-vision, motor, cognitive, deaf/hard-of-hearing users)

Severity	Criteria	Examples
🔴 Critical	Blocks access entirely	Missing form labels, non-keyboard-operable controls, missing alt-text on functional images
🟠 High	Significantly impairs UX	Low contrast (< 3:1), missing landmarks, unannounced dynamic content
🟡 Medium	Degrades experience	Missing focus indicators, ambiguous link text, skip-link absent
🟢 Low	Best practice violations	Non-optimal heading structure, minor ARIA refinements

// ❌ BAD: div-as-button, no keyboard, no label
<div onClick={handleClick}>Submit</div>

// ✅ GOOD
<button type="button" onClick={handleClick}>Submit</button>

// ❌ BAD: Dynamic content not announced
setItems(newItems);

// ✅ GOOD: Use aria-live for dynamic regions
<div aria-live="polite" aria-atomic="true">
  {items.map(item => <Item key={item.id} {...item} />)}
</div>

<!-- ❌ BAD: Error only by color -->
<span class="error-text">Invalid email</span>

<!-- ✅ GOOD: Error with text, role, and association -->
<label for="email">Email address</label>
<input id="email" aria-describedby="email-error" aria-invalid="true" />
<span id="email-error" role="alert">Invalid email address — must include @</span>

<!-- ❌ BAD: No label association -->
<input [(ngModel)]="email" placeholder="email" />

<!-- ✅ GOOD -->
<label for="email">Email</label>
<input id="email" [(ngModel)]="email" aria-describedby="email-hint" />
<span id="email-hint">We'll never share your email</span>

<!-- ❌ BAD: Clickable div -->
<div @click="navigate">Go to dashboard</div>

<!-- ✅ GOOD: Semantic element -->
<button @click="navigate">Go to dashboard</button>
<!-- OR: role with keyboard -->
<div role="button" tabindex="0" @click="navigate" @keydown.enter="navigate" @keydown.space.prevent="navigate">Go to dashboard</div>

<!-- ❌ OVER-ENGINEERED -->
<div role="button" tabindex="0" aria-pressed="false" onclick="...">Click</div>

<!-- ✅ CORRECT -->
<button type="button">Click</button>

### [WCAG SC] — Severity: [level]

**File:** `path/to/file.tsx:42`
**Impact:** [desc]

#### ❌ Current
```[lang]
[problematic code]

[fixed code]


End the audit with:
- **Summary:** Total violations by severity (Critical/High/Medium/Low)
- **Quick Wins:** Top 3 fixes with biggest impact at lowest effort
- **Pattern Issues:** Systemic issues (e.g., "All 12 buttons use `<div>` instead of `<button>`")

## Red Lines — Never Suggest

- ❌ Removing features to avoid accessibility work
- ❌ `aria-hidden="true"` as a quick fix — it hides content from screen readers
- ❌ `tabindex="-1"` on focusable content — makes it keyboard-inaccessible
- ❌ Color-only fixes — always pair with text/icon indicators
- ❌ Auto-playing video without pause/stop controls
- ❌ Text-as-image without alt text

## Reduce Motion (WCAG 2.2 — 2.3.3)

```css
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}