# Accessibility Auditing
> Audit web pages and components for accessibility issues following WCAG 2.1 guidelines. Use when checking for accessibility compliance, fixing a11y issues, ensuring screen reader compatibility, or improving keyboard navigation. Triggers on requests like "audit accessibility", "check a11y", "fix accessibility issues", "screen reader support", "keyboard navigation", or "WCAG compliance".
- Skill: `majiayu000/accessibility-auditing` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/accessibility-auditing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/accessibility-auditing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/accessibility-auditing
---
# Accessibility Auditing
Audit and improve accessibility for WCAG 2.1 AA compliance.
## Process
1. **Identify scope** - Which pages/components to audit?
2. **Automated checks** - Run linting and browser tools
3. **Manual testing** - Keyboard navigation, screen reader
4. **Document issues** - Severity, location, fix
5. **Implement fixes** - Priority order
## WCAG 2.1 Checklist
### Perceivable
**Images**
```tsx
// Required: alt text for informational images
// Decorative images: empty alt
```
**Color Contrast**
- Normal text: 4.5:1 minimum
- Large text (18px+): 3:1 minimum
- Use theme CSS variables which meet contrast requirements
**Video/Audio**
```tsx
// Captions for video content
```
### Operable
**Keyboard Navigation**
```tsx
// All interactive elements focusable
// Good: button is focusable
// Custom elements need tabindex
Click me
// Skip links for main content
Skip to main content
```
**Focus Indicators**
```tsx
// Visible focus states
className="focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2"
```
**Focus Trapping (Modals)**
```tsx
// Trap focus within modal
useEffect(() => {
const focusableElements = modal.querySelectorAll(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
const first = focusableElements[0];
const last = focusableElements[focusableElements.length - 1];
function handleTab(e: KeyboardEvent) {
if (e.key === 'Tab') {
if (e.shiftKey && document.activeElement === first) {
e.preventDefault();
last.focus();
} else if (!e.shiftKey && document.activeElement === last) {
e.preventDefault();
first.focus();
}
}
}
// ...
}, []);
```
### Understandable
**Form Labels**
```tsx
// Always associate labels with inputs
// Or use aria-label for icon-only buttons
```
**Error Messages**
```tsx
// Associate errors with inputs
{error && (
{error}
)}
```
**Language**
```tsx
// Declare page language
```
### Robust
**Semantic HTML**
```tsx
// Use appropriate elements
// Navigation
... // Main content
... // Article content
// Sidebar
... // Header
// Footer
// Use headings in order
Page Title
Section
Subsection
```
**ARIA Roles and States**
```tsx
// Live regions for dynamic content
{statusMessage}
// Loading states
// Expanded/collapsed
...
```
## Common Issues in This Project
### Admin Tables
- Ensure sortable columns are keyboard accessible
- Add scope attributes to table headers
- Announce sort changes with aria-live
### Media Library
- All images need alt text (use title field)
- Video players need keyboard controls
- Upload progress announced to screen readers
### Forms
- All fields need visible labels
- Required fields marked with aria-required
- Error states linked with aria-describedby
### Navigation
- Mobile menu needs aria-expanded
- Current page indicated with aria-current="page"
- Dropdown menus keyboard navigable
## Testing Tools
```bash
# ESLint a11y plugin (add to eslint.config.mjs)
npm install eslint-plugin-jsx-a11y --save-dev
# Playwright a11y testing
npm install @axe-core/playwright --save-dev
```
## Output
Provide accessibility audit results:
1. Issue list with severity (Critical/Serious/Moderate/Minor)
2. WCAG criterion violated
3. Location (file:line or selector)
4. Recommended fix with code example
```
**Color Contrast**
- Normal text: 4.5:1 minimum
- Large text (18px+): 3:1 minimum
- Use theme CSS variables which meet contrast requirements
**Video/Audio**
```tsx
// Captions for video content
```
### Operable
**Keyboard Navigation**
```tsx
// All interactive elements focusable
// Good: button is focusable
// Custom elements need tabindex