web-accessibility-audit

Q: How do I install web-accessibility-audit?

Run npx skills add https://github.com/warpdotdev/oz-skills --skill web-accessibility-audit in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/web-accessibility-audit/ (personal) or .claude/skills/web-accessibility-audit/ (project).

by warpdotdevFrontend & Design

Audit web applications for WCAG accessibility compliance. Use when asked to run accessibility checks, identify common violations, and provide remediation guidance.

Installs: 205
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/warpdotdev/oz-skills --skill web-accessibility-audit

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads web-accessibility-audit automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Accessibility Auditor

Audit web applications for WCAG 2.0/2.1/2.2 compliance by identifying common violations and providing actionable remediation steps.

When to Use

User requests accessibility audit, a11y check, or WCAG compliance review
User mentions accessibility issues, screen readers, or keyboard navigation problems
User asks to check or improve accessibility for people with disabilities

WCAG Principles: POUR

Principle	Description
Perceivable	Content can be perceived through different senses
Operable	Interface can be operated by all users
Understandable	Content and interface are understandable
Robust	Content works with assistive technologies

Conformance Levels

Level	Requirement	Target
A	Minimum accessibility	Must pass
AA	Standard compliance	Should pass (legal requirement in many jurisdictions)
AAA	Enhanced accessibility	Nice to have

12 Most Common WCAG Violations

Based on WebAIM Million (2021) research analyzing top 1M websites:

Low Color Contrast (WCAG 1.4.3) - 86.4% of sites
- Text < 4.5:1 contrast ratio
- Large text < 3:1 contrast ratio
- UI components < 3:1
Missing/Inadequate Alt Text (WCAG 1.1.1) - 60.6% of sites
- Images without alt attribute
- Alt text with "image", "picture", "photo"
- Empty alt on meaningful images
Missing Name, Role, or Value (WCAG 4.1.2)
- Interactive elements without accessible names
- Custom components without proper ARIA
- Buttons, form fields, custom widgets
Keyboard Navigation Failures (WCAG 2.1.1)
- Elements with onClick but not keyboard accessible
- Missing focus indicators
- Trapped keyboard focus
Unlabeled Form Controls (WCAG 1.3.1, 3.3.2) - 39.6% of sites
- Inputs without <label> or aria-label
- Labels not programmatically associated
Missing Language Attributes (WCAG 3.1.1) - 28.9% of sites
- No lang attribute on <html>
- Missing lang for foreign language passages
Improper Heading Structure (WCAG 1.3.1, 2.4.6)
- Skipped heading levels (h1 → h3)
- Multiple h1s or no h1
- Empty headings
Empty Links or Poor Link Text (WCAG 2.4.4)
- Links with "click here", "here", "read more"
- Empty links or links with only icons
Missing/Improper Focus Indicators (WCAG 2.4.7)
- CSS removing outline without replacement
- Insufficient focus indicator contrast
Overuse/Misuse of ARIA (WCAG 4.1.2)
- Unnecessary ARIA when native HTML works
- Invalid ARIA attributes for roles
- Required ARIA attributes missing
Inadequate Data Table Markup (WCAG 1.3.1)
- Tables without <th> elements
- Missing scope or headers attributes
Missing Media Captions (WCAG 1.2.1, 1.2.2)
- Videos without captions/subtitles
- Audio without transcripts

Audit Process

Phase 1: Automated Testing

Run ESLint (React/JSX projects):

npx eslint --ext .jsx,.tsx --no-ignore --format json . > .claude/skills/a11y-auditor/eslint-results.json 2>&1 || true

Or use helper script: .claude/skills/a11y-auditor/scripts/run-eslint.sh

Run Lighthouse (production/staging):

npx lighthouse https://example.com --only-categories=accessibility --output=json --output-path=./lighthouse-results.json

Check for axe-core integration:

grep -r "@axe-core\|axe-core" package.json

Phase 2: Manual Code Inspection

Use grep patterns from references/grep-patterns.md to search for:

Missing alt text
Keyboard navigation issues
Color values for contrast checking
ARIA issues
Form labels
Heading structure
Language attributes
Poor link text
Media elements

See references/grep-patterns.md for complete pattern list.

Phase 3: Analyze & Prioritize

Group findings by severity using WCAG impact levels:

Critical (fix immediately):

Keyboard traps
No focus indicators
Missing form labels
Missing alt text on functional images
Insufficient color contrast on interactive elements

Serious (fix before launch):

Missing page language
Improper heading structure
Non-descriptive link text
Missing skip links
Auto-playing media

Moderate (fix soon):

Missing ARIA labels on icons
Inconsistent navigation
Missing error identification
Missing landmark regions

Phase 4: Manual Testing

Follow references/screen-reader-guide.md for:

Keyboard navigation testing
Screen reader testing (VoiceOver, NVDA, JAWS)
Zoom and reflow testing
High contrast mode testing
Reduced motion testing

WCAG Pattern Examples

Perceivable

Alt Text (1.1.1)

<!-- ❌ Missing alt -->
<img src="chart.png">

<!-- ✅ Descriptive alt -->
<img src="chart.png" alt="Bar chart showing 40% increase in Q3 sales">

<!-- ✅ Decorative (empty alt) -->
<img src="decorative-border.png" alt="" role="presentation">

Color Contrast (1.4.3)

/* ❌ Low contrast (2.5:1) */
.low-contrast {
  color: #999;
  background: #fff;
}

/* ✅ Sufficient contrast (7:1) */
.high-contrast {
  color: #333;
  background: #fff;
}

Contrast requirements:

Normal text: 4.5:1 (AA), 7:1 (AAA)
Large text (18px+ or 14px+ bold): 3:1 (AA), 4.5:1 (AAA)
UI components: 3:1

Media Alternatives (1.2)

<video controls>
  <source src="video.mp4" type="video/mp4">
  <track kind="captions" src="captions.vtt" srclang="en" label="English" default>
</video>

Operable

Keyboard Navigation (2.1.1)

// ❌ Only click
element.addEventListener('click', handleAction);

// ✅ Click + keyboard
element.addEventListener('click', handleAction);
element.addEventListener('keydown', (e) => {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    handleAction();
  }
});

Focus Visible (2.4.7)

/* ❌ Never remove focus */
*:focus { outline: none; }

/* ✅ Keyboard-only focus */
:focus-visible {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

Skip Links (2.4.1)

<body>
  <a href="#main-content" class="skip-link">Skip to main content</a>
  <header><!-- navigation --></header>
  <main id="main-content" tabindex="-1">
    <!-- content -->
  </main>
</body>

.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  background: #000;
  color: #fff;
  padding: 8px 16px;
  z-index: 100;
}

.skip-link:focus {
  top: 0;
}

Reduced Motion (2.3.3)

@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;
  }
}

Understandable

Page Language (3.1.1)

<!-- ❌ No language -->
<html>

<!-- ✅ Language specified -->
<html lang="en">

<!-- ✅ Language changes -->
<p>The French word for hello is <span lang="fr">bonjour</span>.</p>

Form Labels (3.3.2)

<!-- ❌ No label -->
<input type="email" placeholder="Email">

<!-- ✅ Explicit label -->
<label for="email">Email address</label>
<input type="email" id="email" autocomplete="email">

<!-- ✅ With hint -->
<label for="password">Password</label>
<input type="password" id="password" aria-describedby="password-requirements">
<p id="password-requirements">
  Must be at least 8 characters with one number.
</p>

Error Handling (3.3.1)

<label for="email">Email</label>
<input type="email" id="email" 
       aria-invalid="true" 
       aria-describedby="email-error">
<p id="email-error" role="alert">
  Please enter a valid email address.
</p>

Robust

ARIA Usage (4.1.2)

<!-- ❌ Unnecessary ARIA -->
<button role="button">Submit</button>

<!-- ✅ Native HTML -->
<button>Submit</button>

<!-- ✅ ARIA when needed (custom tabs) -->
<div role="tablist" aria-label="Product information">
  <button role="tab" aria-selected="true" aria-controls="panel-1">
    Description
  </button>
  <button role="tab" aria-selected="false" aria-controls="panel-2" tabindex="-1">
    Reviews
  </button>
</div>
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
  <!-- content -->
</div>

Live Regions (4.1.3)

<!-- Polite (waits for pause) -->
<div aria-live="polite" aria-atomic="true">
  Status update
</div>

<!-- Assertive (interrupts) -->
<div role="alert" aria-live="assertive">
  Error: Form submission failed
</div>

Visually Hidden Text

.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

<button>
  <svg aria-hidden="true"><!-- icon --></svg>
  <span class="visually-hidden">Delete item</span>
</button>

Output Format

Generate reports structured as:

# Accessibility Audit Report

## Summary
- Total Issues: X
- Critical: X | Serious: X | Moderate: X | Minor: X
- WCAG Level: A, AA, or AAA
- Automated Coverage: ~57% (manual testing required)

## Critical Issues (Fix Immediately)

### 1. [Issue Name] - WCAG X.X.X
**Severity:** Critical  
**Impact:** [Who is affected and how]  
**Affected:** X elements

**Locations:**
- `path/to/file.tsx:123`
- `path/to/file.tsx:456`

**Problem:**
[Brief description]

**Fix:**
```tsx
// Before
<div onClick={handleClick}>Click me</div>

// After
<button onClick={handleClick}>Click me</button>

Why: [Accessibility principle]

Serious Issues

[Same format]

Moderate Issues

[Same format]

Testing Recommendations

Manual keyboard testing (Tab, Enter, Escape)
Screen reader testing (see references/screen-reader-guide.md)
Automated testing setup (@axe-core/react or Lighthouse CI)
Color contrast validation (WebAIM Contrast Checker)

Next Steps

[Prioritized action items]


---

## Tools & Resources

### Development Tools
- **eslint-plugin-jsx-a11y** - React/JSX static analysis (~37 rules)
- **axe-core DevTools** - Browser extension for runtime testing
- **Lighthouse** - Built into Chrome DevTools

### Testing Tools  
- **@axe-core/react** - Runtime accessibility testing
- **@axe-core/playwright** - E2E test integration
- **pa11y** - Automated command-line testing

### Manual Testing
- **WebAIM Contrast Checker** - https://webaim.org/resources/contrastchecker/
- **WAVE** - Browser extension for visual feedback
- **Screen readers** - NVDA (Windows), VoiceOver (macOS), JAWS

### Reference Docs
- `references/WCAG-criteria.md` - All WCAG 2.1 success criteria
- `references/ARIA-patterns.md` - Common ARIA patterns and examples
- `references/screen-reader-guide.md` - Testing commands and scenarios
- `references/grep-patterns.md` - Search patterns for code audits

### References
- [WebAIM Million](https://webaim.org/projects/million/) - Annual analysis of top 1M websites (violation statistics)
- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/) - Interactive WCAG guide
- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) - Official ARIA patterns
- [Deque axe Rules](https://dequeuniversity.com/rules/axe/) - All axe-core rules explained
- [jsx-a11y Rules](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y#supported-rules) - ESLint accessibility rules

---

## Important Notes

- Automated tools catch 30-57% of issues; manual testing required
- Pages with ARIA average 41% more errors than without
- Always test with actual assistive technology when possible
- Focus on critical issues first (keyboard, screen readers, contrast)
- Document deliberate accessibility decisions
- Test on multiple browsers and devices
- Include users with disabilities in testing when possible

## Common Pitfalls to Avoid

1. Relying solely on automated testing
2. Using ARIA when native HTML suffices
3. Removing focus indicators
4. Using positive tabindex values
5. Color as only means of conveying information
6. Keyboard traps in modals/dialogs
7. Non-descriptive link text
8. Missing or incorrect heading hierarchy
9. Unlabeled form controls
10. Missing language attributes

FAQ

What does the web-accessibility-audit skill do?

Audit web applications for WCAG accessibility compliance. Use when asked to run accessibility checks, identify common violations, and provide remediation guidance.

How do I install web-accessibility-audit?

Run npx skills add https://github.com/warpdotdev/oz-skills --skill web-accessibility-audit in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/web-accessibility-audit/ (personal) or .claude/skills/web-accessibility-audit/ (project).

Which AI agents can use web-accessibility-audit?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is web-accessibility-audit safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains web-accessibility-audit?

It is published by warpdotdev in warpdotdev/oz-skills. It has 205 recorded installs.

Popular frontend & design skills

View category →

setup-matt-pocock-skills

mattpocock/skills

Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.

Frontend & Design1.1M installs

frontend-design

anthropics/skills

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

OfficialFrontend & Design1M installs

hyperframes-animation

heygen-com/hyperframes

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Frontend & Design1M installs

prototype

mattpocock/skills

Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.

Frontend & Design999.2K installs

hyperframes-core

heygen-com/hyperframes

The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Frontend & Design930.5K installs

vercel-react-best-practices

vercel-labs/agent-skills

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

OfficialFrontend & Design843.1K installs

web-accessibility-audit

Install

Install

Describe the task

Review the result

SKILL.md

Accessibility Auditor

When to Use

WCAG Principles: POUR

Conformance Levels

12 Most Common WCAG Violations

Audit Process

Phase 1: Automated Testing

Phase 2: Manual Code Inspection

Phase 3: Analyze & Prioritize

Phase 4: Manual Testing

WCAG Pattern Examples

Perceivable

Alt Text (1.1.1)

Color Contrast (1.4.3)

Media Alternatives (1.2)

Operable

Keyboard Navigation (2.1.1)

Focus Visible (2.4.7)

Skip Links (2.4.1)

Reduced Motion (2.3.3)

Understandable

Page Language (3.1.1)

Form Labels (3.3.2)

Error Handling (3.3.1)

Robust

ARIA Usage (4.1.2)

Live Regions (4.1.3)

Visually Hidden Text

Output Format

Serious Issues

Moderate Issues

Testing Recommendations

Next Steps

FAQ

More from warpdotdev/oz-skills

Popular frontend & design skills