| name | accessibility-design |
| description | WCAG 2.1 AA compliance patterns, screen reader compatibility, keyboard navigation, and ARIA best practices. Use when implementing accessible interfaces, reviewing UI components, or auditing accessibility compliance. Covers semantic HTML, focus management, color contrast, and assistive technology testing. |
Accessibility Standards
Overview
This skill provides comprehensive guidance for implementing WCAG 2.1 AA compliance across digital products. It establishes patterns for semantic markup, assistive technology compatibility, and inclusive interaction design.
Core Principles
1. POUR Framework
All accessibility work follows the four POUR principles:
Perceivable - Information must be presentable in ways users can perceive
- Provide text alternatives for non-text content
- Create content adaptable to different presentations
- Make content distinguishable (color, contrast, audio control)
Operable - Interface components must be operable by all users
- Make all functionality keyboard accessible
- Provide sufficient time to read and use content
- Avoid content that causes seizures or physical reactions
- Help users navigate, find content, and determine location
Understandable - Information and operation must be understandable
- Make text readable and understandable
- Make pages appear and operate predictably
- Help users avoid and correct mistakes
Robust - Content must be robust enough for diverse user agents
- Maximize compatibility with current and future assistive technologies
- Use valid, semantic markup
- Ensure programmatic access to all functionality
2. Semantic HTML First
Semantic HTML is the foundation of accessibility. ARIA should enhance, never replace, proper markup.
Correct approach:
<button type="submit">Submit Form</button>
Incorrect approach:
<div role="button" tabindex="0" onclick="submit()">Submit Form</div>
Use native HTML elements whenever possible:
<button> for actions<a href> for navigation<input>, <select>, <textarea> for form controls<nav>, <main>, <aside>, <header>, <footer> for landmarks<h1> through <h6> for heading hierarchy
3. Progressive Enhancement
Build accessibility in layers:
- Semantic HTML provides baseline accessibility
- CSS enhances presentation without breaking structure
- JavaScript adds interactivity while maintaining keyboard access
- ARIA fills gaps for complex widgets not covered by HTML
Implementation Patterns
Document Structure
Every page requires proper document structure:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Descriptive Page Title - Site Name</title>
</head>
<body>
<a href="#main-content" class="skip-link">Skip to main content</a>
<header role="banner">
<nav aria-label="Main navigation">
</nav>
</header>
<main id="main-content" role="main">
<h1>Page Heading</h1>
</main>
<footer role="contentinfo">
</footer>
</body>
</html>
Heading Hierarchy
Maintain logical heading order without skipping levels:
<h1>Main Page Title</h1>
<h2>Section Title</h2>
<h3>Subsection Title</h3>
<h3>Another Subsection</h3>
<h2>Another Section</h2>
<h3>Subsection</h3>
<h4>Sub-subsection</h4>
Skip Links
Provide skip links for keyboard users to bypass repetitive content:
.skip-link {
position: absolute;
top: -40px;
left: 0;
padding: 8px 16px;
background: #000;
color: #fff;
z-index: 100;
}
.skip-link:focus {
top: 0;
}
Focus Management
Visible Focus Indicators
Focus indicators must be visible and meet contrast requirements:
:focus {
outline: 2px solid #005fcc;
outline-offset: 2px;
}
:focus-visible {
outline: 3px solid #005fcc;
outline-offset: 3px;
box-shadow: 0 0 0 6px rgba(0, 95, 204, 0.25);
}
:focus:not(:focus-visible) {
outline: 2px solid transparent;
box-shadow: 0 0 0 2px #005fcc;
}
Focus Trapping for Modals
function trapFocus(element) {
const focusableElements = element.querySelectorAll(
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
);
const firstFocusable = focusableElements[0];
const lastFocusable = focusableElements[focusableElements.length - 1];
element.addEventListener('keydown', (e) => {
if (e.key !== 'Tab') return;
if (e.shiftKey) {
if (document.activeElement === firstFocusable) {
lastFocusable.focus();
e.preventDefault();
}
} else {
if (document.activeElement === lastFocusable) {
firstFocusable.focus();
e.preventDefault();
}
}
});
}
Keyboard Navigation
Standard Keyboard Patterns
| Key | Action |
|---|
| Tab | Move focus to next focusable element |
| Shift+Tab | Move focus to previous focusable element |
| Enter/Space | Activate buttons and links |
| Arrow keys | Navigate within components (menus, tabs, radio groups) |
| Escape | Close modals, menus, dropdowns |
| Home/End | Move to first/last item in lists |
Tab Order
Ensure logical tab order follows visual order:
<form>
<label for="name">Name</label>
<input id="name" type="text">
<label for="email">Email</label>
<input id="email" type="email">
<button type="submit">Submit</button>
</form>
Never use positive tabindex values. Only use:
tabindex="0" to make non-interactive elements focusabletabindex="-1" to make elements programmatically focusable but not in tab order
ARIA Patterns
When to Use ARIA
Use ARIA only when native HTML cannot achieve the required accessibility:
- Custom widgets - Tabs, accordions, carousels, tree views
- Dynamic content - Live regions for updates
- Relationships - Connecting labels to complex controls
- States - Expanded/collapsed, selected, pressed
ARIA Roles
Common roles for custom widgets:
<div role="tablist" aria-label="Settings tabs">
<button role="tab" aria-selected="true" aria-controls="panel1" id="tab1">
General
</button>
<button role="tab" aria-selected="false" aria-controls="panel2" id="tab2">
Security
</button>
</div>
<div role="tabpanel" id="panel1" aria-labelledby="tab1">
</div>
<div role="tabpanel" id="panel2" aria-labelledby="tab2" hidden>
</div>
ARIA States and Properties
| Attribute | Purpose | Example |
|---|
aria-expanded | Indicates expandable element state | aria-expanded="false" |
aria-selected | Indicates selection state | aria-selected="true" |
aria-pressed | Indicates toggle button state | aria-pressed="mixed" |
aria-hidden | Hides content from assistive tech | aria-hidden="true" |
aria-live | Announces dynamic content | aria-live="polite" |
aria-describedby | References descriptive content | aria-describedby="hint" |
aria-labelledby | References labeling content | aria-labelledby="heading" |
Live Regions
Announce dynamic content changes:
<div aria-live="polite" aria-atomic="true">
Form saved successfully
</div>
<div aria-live="assertive" role="alert">
Error: Please correct the highlighted fields
</div>
<div role="status">
Loading... 50% complete
</div>
Form Accessibility
Labels and Instructions
Every form control requires a label:
<label for="username">Username</label>
<input type="text" id="username" name="username"
aria-describedby="username-hint">
<span id="username-hint">Must be 3-20 characters</span>
<fieldset>
<legend>Shipping Address</legend>
<label for="street">Street</label>
<input type="text" id="street">
</fieldset>
Error Handling
Provide clear, actionable error messages:
<label for="email">Email</label>
<input type="email" id="email"
aria-invalid="true"
aria-describedby="email-error">
<span id="email-error" role="alert">
Please enter a valid email address (example: user@domain.com)
</span>
Error message requirements:
- Identify the field in error
- Describe what went wrong
- Provide guidance for correction
- Use
aria-invalid on the field
- Announce errors via live region or
role="alert"
Required Fields
<label for="name">
Name <span aria-hidden="true">*</span>
<span class="sr-only">(required)</span>
</label>
<input type="text" id="name" required aria-required="true">
Images and Media
Alternative Text
Provide meaningful alt text for informative images:
<img src="chart.png" alt="Q3 revenue increased 15% compared to Q2">
<img src="divider.png" alt="" role="presentation">
<figure>
<img src="flowchart.png" alt="User registration process"
aria-describedby="flowchart-desc">
<figcaption id="flowchart-desc">
The registration process begins with email verification,
followed by profile creation, and ends with account activation.
</figcaption>
</figure>
Video and Audio
<video controls>
<source src="video.mp4" type="video/mp4">
<track kind="captions" src="captions.vtt" srclang="en" label="English">
<track kind="descriptions" src="descriptions.vtt" srclang="en"
label="Audio descriptions">
</video>
Color and Contrast
Minimum Contrast Ratios
| Content Type | Minimum Ratio (AA) | Enhanced Ratio (AAA) |
|---|
| Normal text (< 18pt) | 4.5:1 | 7:1 |
| Large text (>= 18pt or 14pt bold) | 3:1 | 4.5:1 |
| UI components and graphics | 3:1 | N/A |
Never Rely on Color Alone
<input style="border-color: red">
<input aria-invalid="true" aria-describedby="error">
<span id="error">
<svg aria-hidden="true"></svg>
Invalid email format
</span>
Motion and Animation
Respect User Preferences
@media (prefers-reduced-motion: reduce) {
*,
*::before,
*::after {
animation-duration: 0.01ms !important;
animation-iteration-count: 1 !important;
transition-duration: 0.01ms !important;
}
}
Auto-playing Content
- Avoid auto-playing video or audio
- Provide controls to pause, stop, or hide moving content
- Limit animations to under 5 seconds or provide stop mechanism
Testing Methodology
Automated Testing
Run automated tools to catch common issues:
- axe DevTools - Browser extension for page analysis
- WAVE - Web accessibility evaluation tool
- Lighthouse - Chrome DevTools accessibility audit
- pa11y - Command-line accessibility testing
Automated testing catches approximately 30-40% of issues.
Manual Testing
Keyboard Testing
- Disconnect or disable mouse
- Navigate entire page using Tab/Shift+Tab
- Verify all interactive elements are reachable
- Verify focus indicators are visible
- Test all keyboard shortcuts
- Escape from all modals and menus
Screen Reader Testing
Test with multiple screen readers:
| Platform | Screen Reader | Browser |
|---|
| Windows | NVDA (free) | Firefox, Chrome |
| Windows | JAWS | Chrome, Edge |
| macOS | VoiceOver | Safari |
| iOS | VoiceOver | Safari |
| Android | TalkBack | Chrome |
Screen reader testing checklist:
Visual Testing
- Zoom to 200% and verify no horizontal scrolling
- Test with high contrast mode enabled
- Disable images and verify content is still understandable
- Test with browser text size increased
WCAG Audit
Perform manual audit against WCAG 2.1 AA success criteria. See checklists/wcag-checklist.md for the complete checklist.
Common Patterns
Modal Dialog
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
<h2 id="dialog-title">Confirm Action</h2>
<p>Are you sure you want to proceed?</p>
<button type="button">Cancel</button>
<button type="button">Confirm</button>
</div>
Requirements:
- Focus moves to dialog when opened
- Focus is trapped within dialog
- Escape key closes dialog
- Focus returns to trigger element on close
Accordion
<div class="accordion">
<h3>
<button aria-expanded="true" aria-controls="section1">
Section 1
</button>
</h3>
<div id="section1" role="region" aria-labelledby="section1-heading">
</div>
</div>
Navigation Menu
<nav aria-label="Main">
<ul>
<li><a href="/" aria-current="page">Home</a></li>
<li>
<button aria-expanded="false" aria-haspopup="true">
Products
</button>
<ul>
<li><a href="/products/a">Product A</a></li>
<li><a href="/products/b">Product B</a></li>
</ul>
</li>
</ul>
</nav>
Data Table
<table>
<caption>Q3 Sales by Region</caption>
<thead>
<tr>
<th scope="col">Region</th>
<th scope="col">Units Sold</th>
<th scope="col">Revenue</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">North</th>
<td>1,234</td>
<td>$45,678</td>
</tr>
</tbody>
</table>
Resources
