WCAG Compliance
Web Content Accessibility Guidelines 2.2 AA implementation for inclusive, legally compliant web applications.
Overview
- Building accessible UI components from scratch
- Auditing applications for ADA/Section 508 compliance
- Implementing keyboard navigation and focus management
- Supporting screen readers and assistive technologies
- Fixing color contrast and visual accessibility issues
Quick Reference
Semantic HTML Structure
<main>
<article>
<header><h1>Page Title</h1></header>
<section aria-labelledby="features-heading">
<h2 id="features-heading">Features</h2>
<ul><li>Feature 1</li></ul>
</section>
<aside aria-label="Related content">...</aside>
</article>
</main>
ARIA Labels and States
// Icon-only button
<button aria-label="Save document">
<svg aria-hidden="true">...</svg>
</button>
// Form field with error
<input
id="email"
aria-required="true"
aria-invalid={!!error}
aria-describedby={error ? "email-error" : "email-hint"}
/>
{error && <p id="email-error" role="alert">{error}</p>}
Color Contrast (CSS)
:root {
--text-primary: #1a1a1a; /* 16.1:1 on white - normal text */
--text-secondary: #595959; /* 7.0:1 on white - secondary */
--focus-ring: #0052cc; /* 7.3:1 - focus indicator */
}
:focus-visible {
outline: 3px solid var(--focus-ring);
outline-offset: 2px;
}
WCAG 2.2 AA Checklist
| Criterion | Requirement | Test |
|---|---|---|
| 1.1.1 Non-text | Alt text for images | axe-core scan |
| 1.3.1 Info | Semantic HTML, headings | Manual + automated |
| 1.4.3 Contrast | 4.5:1 text, 3:1 large | WebAIM checker |
| 1.4.11 Non-text Contrast | 3:1 UI components | Manual inspection |
| 2.1.1 Keyboard | All functionality via keyboard | Tab through |
| 2.4.3 Focus Order | Logical tab sequence | Manual test |
| 2.4.7 Focus Visible | Clear focus indicator | Visual check |
| 2.4.11 Focus Not Obscured | Focus not hidden by sticky elements | scroll-margin-top |
| 2.5.7 Dragging | Single-pointer alternative | Button fallback |
| 2.5.8 Target Size | Min 24x24px interactive | CSS audit |
| 4.1.2 Name/Role/Value | Proper ARIA, labels | Screen reader test |
Key Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Conformance level | WCAG 2.2 AA | Legal standard (ADA, Section 508) |
| Contrast ratio | 4.5:1 normal, 3:1 large | AA minimum requirement |
| Target size | 24px min, 44px touch | 2.5.8 + mobile usability |
| Focus indicator | 3px solid outline | High visibility, 3:1 contrast |
| Live regions | polite default, assertive for errors | Avoids interruption |
| Decorative images | alt="" role="presentation" | Hide from AT |
| Skip link | First focusable element | Keyboard user efficiency |
Anti-Patterns (FORBIDDEN)
- Div soup: Using
<div>instead of semantic elements (<nav>,<main>,<article>) - Color-only information: Status indicated only by color without icon/text
- Missing labels: Form inputs without associated
<label>oraria-label - Keyboard traps: Focus that cannot escape without mouse
- Auto-playing media: Audio/video that plays without user action
- Removing focus outline:
outline: nonewithout replacement indicator - Positive tabindex: Using
tabindex > 0(disrupts natural order) - Empty links/buttons: Interactive elements without accessible names
- ARIA overuse: Using ARIA when semantic HTML suffices
Related Skills
a11y-testing- Automated accessibility testing with axe-core and Playwrightdesign-system-starter- Accessible component library patternsi18n-date-patterns- RTL layout and locale-aware formattingmotion-animation-patterns- Reduced motion and animation accessibility
Capability Details
semantic-html
Keywords: semantic, landmark, heading, structure, html5, main, nav, article Solves:
- Proper document structure with landmarks
- Heading hierarchy (h1-h6 in order)
- Form fieldsets and legends
- Lists for grouped content
aria-patterns
Keywords: aria, role, state, property, live-region, alert, status Solves:
- Custom widget accessibility (tabs, menus, dialogs)
- Dynamic content announcements
- Expanded/collapsed states
- Error/validation messaging
focus-management
Keywords: keyboard, focus, tab, trap, modal, skip-link, roving Solves:
- Modal focus trapping
- Skip links for navigation
- Roving tabindex for widgets
- Focus restoration after dialogs
color-contrast
Keywords: contrast, color, wcag, perceivable, vision, ratio Solves:
- Text contrast ratios (4.5:1 / 3:1)
- UI component contrast (3:1)
- Focus indicator visibility
- Non-color status indicators