Agent skill

accessibility-auditor

Audit websites for accessibility issues and WCAG compliance. Use when checking accessibility, fixing a11y issues, or ensuring WCAG compliance.

View SKILL.md on GitHub Repository
Stars 75
Forks 9

Install this agent skill to your Project

npx add-skill https://github.com/OneWave-AI/claude-skills/tree/main/accessibility-auditor

SKILL.md

Accessibility Auditor

Instructions

When auditing accessibility:

  1. Run automated checks (axe, Lighthouse)
  2. Manual keyboard testing
  3. Screen reader testing
  4. Check WCAG criteria
  5. Provide fixes

Automated Testing

bash
# Lighthouse accessibility audit
npx lighthouse https://yoursite.com --only-categories=accessibility --view

# axe-core CLI
npx @axe-core/cli https://yoursite.com

# Pa11y
npx pa11y https://yoursite.com

React Testing Library + jest-axe

typescript
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('Button has no accessibility violations', async () => {
  const { container } = render(<Button>Click me</Button>);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Playwright Accessibility Testing

typescript
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('page has no accessibility violations', async ({ page }) => {
  await page.goto('/');

  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});

WCAG Checklist

Level A (Minimum)

Perceivable

  • 1.1.1 Non-text content has alt text
  • 1.3.1 Info and relationships are programmatically determined
  • 1.3.2 Meaningful reading sequence
  • 1.4.1 Color is not the only way to convey info

Operable

  • 2.1.1 All functionality available via keyboard
  • 2.1.2 No keyboard traps
  • 2.4.1 Skip navigation link provided
  • 2.4.2 Pages have descriptive titles
  • 2.4.3 Focus order is logical
  • 2.4.4 Link purpose is clear

Understandable

  • 3.1.1 Page language is specified
  • 3.2.1 Focus doesn't cause unexpected changes
  • 3.3.1 Errors are identified and described
  • 3.3.2 Labels or instructions provided

Robust

  • 4.1.1 Valid HTML (no duplicate IDs, proper nesting)
  • 4.1.2 Name, role, value for all UI components

Level AA (Standard Target)

  • 1.4.3 Contrast ratio 4.5:1 for text
  • 1.4.4 Text resizable to 200%
  • 1.4.10 Content reflows at 320px width
  • 2.4.6 Headings and labels are descriptive
  • 2.4.7 Focus indicator is visible
  • 3.2.3 Navigation is consistent
  • 3.2.4 Components identified consistently

Common Issues & Fixes

1. Missing Alt Text

tsx
// Bad
<img src="/hero.jpg" />

// Good - Informative image
<img src="/hero.jpg" alt="Team collaborating in modern office" />

// Good - Decorative image
<img src="/decoration.jpg" alt="" role="presentation" />

// Good - Icon button
<button aria-label="Close dialog">
  <XIcon aria-hidden="true" />
</button>

2. Missing Form Labels

tsx
// Bad
<input type="email" placeholder="Email" />

// Good - Visible label
<div>
  <label htmlFor="email">Email</label>
  <input id="email" type="email" />
</div>

// Good - Visually hidden label
<div>
  <label htmlFor="search" className="sr-only">Search</label>
  <input id="search" type="search" placeholder="Search..." />
</div>

3. Poor Color Contrast

tsx
// Bad - 2.5:1 ratio
<p className="text-gray-400 bg-white">Low contrast text</p>

// Good - 4.5:1+ ratio
<p className="text-gray-700 bg-white">Accessible text</p>

// Check contrast: https://webaim.org/resources/contrastchecker/

4. Missing Focus Styles

css
/* Bad - Removes focus */
*:focus { outline: none; }

/* Good - Custom focus style */
*:focus-visible {
  outline: 2px solid #3b82f6;
  outline-offset: 2px;
}

/* Tailwind */
.btn {
  @apply focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2;
}

5. Non-semantic HTML

tsx
// Bad
<div onClick={handleClick}>Click me</div>

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

// Bad
<div className="header">...</div>

// Good
<header>...</header>

6. Missing ARIA for Dynamic Content

tsx
// Loading state
<button disabled aria-busy="true">
  <span className="sr-only">Loading</span>
  <Spinner aria-hidden="true" />
</button>

// Live region for updates
<div aria-live="polite" aria-atomic="true">
  {message && <p>{message}</p>}
</div>

// Modal
<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="modal-title"
>
  <h2 id="modal-title">Dialog Title</h2>
</div>

7. Skip Link

tsx
// Add as first focusable element
<a
  href="#main-content"
  className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-white"
>
  Skip to main content
</a>

<main id="main-content">
  ...
</main>

Screen Reader Only Class

css
/* Visually hidden but accessible */
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border: 0;
}

/* Show on focus (for skip links) */
.sr-only-focusable:focus {
  position: static;
  width: auto;
  height: auto;
  padding: inherit;
  margin: inherit;
  overflow: visible;
  clip: auto;
  white-space: normal;
}

Keyboard Testing Checklist

  1. Tab through page - Logical order?
  2. Enter/Space on buttons - Activates?
  3. Arrow keys in menus - Navigates?
  4. Escape - Closes modals/dropdowns?
  5. Focus visible - Always visible?
  6. No traps - Can tab out of all components?

Common ARIA Patterns

tsx
// Tabs
<div role="tablist">
  <button role="tab" aria-selected="true" aria-controls="panel-1">Tab 1</button>
  <button role="tab" aria-selected="false" aria-controls="panel-2">Tab 2</button>
</div>
<div role="tabpanel" id="panel-1">Content 1</div>
<div role="tabpanel" id="panel-2" hidden>Content 2</div>

// Accordion
<button aria-expanded="true" aria-controls="content-1">Section 1</button>
<div id="content-1">Content</div>

// Menu
<button aria-haspopup="menu" aria-expanded="false">Options</button>
<ul role="menu" hidden>
  <li role="menuitem">Option 1</li>
  <li role="menuitem">Option 2</li>
</ul>

// Alert
<div role="alert">Error: Please fix the form</div>

// Progress
<div role="progressbar" aria-valuenow="50" aria-valuemin="0" aria-valuemax="100">
  50%
</div>

Tools

  • axe DevTools - Browser extension
  • WAVE - Browser extension
  • Lighthouse - Built into Chrome
  • NVDA - Free Windows screen reader
  • VoiceOver - Built into macOS (Cmd+F5)
  • Color Contrast Analyzer - Desktop app

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

OneWave-AI/claude-skills

webinar-to-content-multiplier

Convert webinar recordings into blog posts, social snippets, email series. Extract key quotes, statistics, and soundbites.

75 9
Explore
OneWave-AI/claude-skills

champion-identifier

Analyze LinkedIn profiles in target accounts to identify potential internal champions. Evaluates role, career path, mutual connections, interests, and suggests personalization approach. Use when you need to find who will champion your solution internally.

75 9
Explore
OneWave-AI/claude-skills

skill-navigator

The 100th skill! Your intelligent guide to all 99 other skills. Recommends the perfect skill for any task, creates skill combinations, and helps you discover capabilities you didn't know you had.

75 9
Explore
OneWave-AI/claude-skills

presentation-design-enhancer

Transform text-heavy slides into visual storytelling. Suggest layout improvements, icon usage, and data visualization.

75 9
Explore
OneWave-AI/claude-skills

quiz-maker

Create multiple choice, true/false, fill-in-blank, matching quizzes. Auto-generate plausible distractors. Instant grading with explanations.

75 9
Explore
OneWave-AI/claude-skills

error-boundary-creator

Create error boundaries, error handling, and fallback UIs for React applications. Use when implementing error handling, creating fallback components, or setting up error reporting.

75 9
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results