| name | wcag-audit-patterns |
| description | Conduct WCAG 2.2 accessibility audits with automated testing, manual verification, and remediation guidance. Use when auditing websites for accessibility, fixing WCAG violations, or implementing accessible design patterns. |
WCAG Audit Patterns
Comprehensive guide to auditing web content against WCAG 2.2 guidelines with actionable remediation strategies.
When to Use This Skill
- Conducting accessibility audits
- Fixing WCAG violations
- Implementing accessible components
- Preparing for accessibility lawsuits
- Meeting ADA/Section 508 requirements
- Achieving VPAT compliance
Core Concepts
1. WCAG Conformance Levels
| Level | Description | Required For |
|---|
| A | Minimum accessibility | Legal baseline |
| AA | Standard conformance | Most regulations |
| AAA | Enhanced accessibility | Specialized needs |
2. POUR Principles
Perceivable: Can users perceive the content?
Operable: Can users operate the interface?
Understandable: Can users understand the content?
Robust: Does it work with assistive tech?
3. Common Violations by Impact
Critical (Blockers):
├── Missing alt text for functional images
├── No keyboard access to interactive elements
├── Missing form labels
└── Auto-playing media without controls
Serious:
├── Insufficient color contrast
├── Missing skip links
├── Inaccessible custom widgets
└── Missing page titles
Moderate:
├── Missing language attribute
├── Unclear link text
├── Missing landmarks
└── Improper heading hierarchy
Audit Checklist
Perceivable (Principle 1)
## 1.1 Text Alternatives
### 1.1.1 Non-text Content (Level A)
- [ ] All images have alt text
- [ ] Decorative images have alt=""
- [ ] Complex images have long descriptions
- [ ] Icons with meaning have accessible names
- [ ] CAPTCHAs have alternatives
Check:
```html
<!-- Good -->
<img src="chart.png" alt="Sales increased 25% from Q1 to Q2">
<img src="decorative-line.png" alt="">
<!-- Bad -->
<img src="chart.png">
<img src="decorative-line.png" alt="decorative line">
1.2 Time-based Media
1.2.1 Audio-only and Video-only (Level A)
1.2.2 Captions (Level A)
1.2.3 Audio Description (Level A)
1.3 Adaptable
1.3.1 Info and Relationships (Level A)
Check:
<h1>Page Title</h1>
<h2>Section</h2>
<h3>Subsection</h3>
<h2>Another Section</h2>
<table>
<thead>
<tr><th scope="col">Name</th><th scope="col">Price</th></tr>
</thead>
</table>
1.3.2 Meaningful Sequence (Level A)
1.3.3 Sensory Characteristics (Level A)
1.4 Distinguishable
1.4.1 Use of Color (Level A)
1.4.3 Contrast (Minimum) (Level AA)
Tools: WebAIM Contrast Checker, axe DevTools
1.4.4 Resize Text (Level AA)
1.4.10 Reflow (Level AA)
1.4.11 Non-text Contrast (Level AA)
1.4.12 Text Spacing (Level AA)
### Operable (Principle 2)
```markdown
## 2.1 Keyboard Accessible
### 2.1.1 Keyboard (Level A)
- [ ] All functionality keyboard accessible
- [ ] No keyboard traps
- [ ] Tab order is logical
- [ ] Custom widgets are keyboard operable
Check:
```javascript
// Custom button must be keyboard accessible
<div role="button" tabindex="0"
onkeydown="if(event.key === 'Enter' || event.key === ' ') activate()">
2.1.2 No Keyboard Trap (Level A)
2.2 Enough Time
2.2.1 Timing Adjustable (Level A)
2.2.2 Pause, Stop, Hide (Level A)
@media (prefers-reduced-motion: reduce) {
* {
animation: none !important;
transition: none !important;
}
}
2.3 Seizures and Physical Reactions
2.3.1 Three Flashes (Level A)
2.4 Navigable
2.4.1 Bypass Blocks (Level A)
<a href="#main" class="skip-link">Skip to main content</a>
<main id="main">...</main>
2.4.2 Page Titled (Level A)
2.4.3 Focus Order (Level A)
2.4.4 Link Purpose (In Context) (Level A)
<a href="report.pdf">Click here</a>
<a href="report.pdf">Download Q4 Sales Report (PDF)</a>
2.4.6 Headings and Labels (Level AA)
2.4.7 Focus Visible (Level AA)
:focus {
outline: 3px solid #005fcc;
outline-offset: 2px;
}
2.4.11 Focus Not Obscured (Level AA) - WCAG 2.2
### Understandable (Principle 3)
```markdown
## 3.1 Readable
### 3.1.1 Language of Page (Level A)
- [ ] HTML lang attribute set
- [ ] Language correct for content
```html
<html lang="en">
3.1.2 Language of Parts (Level AA)
<p>The French word <span lang="fr">bonjour</span> means hello.</p>
3.2 Predictable
3.2.1 On Focus (Level A)
3.2.2 On Input (Level A)
3.2.3 Consistent Navigation (Level AA)
3.2.4 Consistent Identification (Level AA)
3.3 Input Assistance
3.3.1 Error Identification (Level A)
<input aria-describedby="email-error" aria-invalid="true">
<span id="email-error" role="alert">Please enter valid email</span>
3.3.2 Labels or Instructions (Level A)
3.3.3 Error Suggestion (Level AA)
3.3.4 Error Prevention (Level AA)
### Robust (Principle 4)
```markdown
## 4.1 Compatible
### 4.1.1 Parsing (Level A) - Obsolete in WCAG 2.2
- [ ] Valid HTML (good practice)
- [ ] No duplicate IDs
- [ ] Complete start/end tags
### 4.1.2 Name, Role, Value (Level A)
- [ ] Custom widgets have accessible names
- [ ] ARIA roles correct
- [ ] State changes announced
```html
<!-- Accessible custom checkbox -->
<div role="checkbox"
aria-checked="false"
tabindex="0"
aria-labelledby="label">
</div>
<span id="label">Accept terms</span>
4.1.3 Status Messages (Level AA)
<div role="status" aria-live="polite">
3 items added to cart
</div>
<div role="alert" aria-live="assertive">
Error: Form submission failed
</div>
## Automated Testing
```javascript
// axe-core integration
const axe = require('axe-core');
async function runAccessibilityAudit(page) {
await page.addScriptTag({ path: require.resolve('axe-core') });
const results = await page.evaluate(async () => {
return await axe.run(document, {
runOnly: {
type: 'tag',
values: ['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa']
}
});
});
return {
violations: results.violations,
passes: results.passes,
incomplete: results.incomplete
};
}
// Playwright test example
test('should have no accessibility violations', async ({ page }) => {
await page.goto('/');
const results = await runAccessibilityAudit(page);
expect(results.violations).toHaveLength(0);
});
npx @axe-core/cli https://example.com
npx pa11y https://example.com
lighthouse https://example.com --only-categories=accessibility
Remediation Patterns
Fix: Missing Form Labels
<input type="email" placeholder="Email">
<label for="email">Email address</label>
<input id="email" type="email">
<input type="email" aria-label="Email address">
<span id="email-label">Email</span>
<input type="email" aria-labelledby="email-label">
Fix: Insufficient Color Contrast
.text { color: #767676; }
.text { color: #595959; }
.text {
color: #767676;
background: #000;
}
Fix: Keyboard Navigation
class AccessibleDropdown extends HTMLElement {
connectedCallback() {
this.setAttribute('tabindex', '0');
this.setAttribute('role', 'combobox');
this.setAttribute('aria-expanded', 'false');
this.addEventListener('keydown', (e) => {
switch (e.key) {
case 'Enter':
case ' ':
this.toggle();
e.preventDefault();
break;
case 'Escape':
this.close();
break;
case 'ArrowDown':
this.focusNext();
e.preventDefault();
break;
case 'ArrowUp':
this.focusPrevious();
e.preventDefault();
break;
}
});
}
}
Best Practices
Do's
- Start early - Accessibility from design phase
- Test with real users - Disabled users provide best feedback
- Automate what you can - 30-50% issues detectable
- Use semantic HTML - Reduces ARIA needs
- Document patterns - Build accessible component library
Don'ts
- Don't rely only on automated testing - Manual testing required
- Don't use ARIA as first solution - Native HTML first
- Don't hide focus outlines - Keyboard users need them
- Don't disable zoom - Users need to resize
- Don't use color alone - Multiple indicators needed
Resources
