Web Accessibility
Apply W3C Web Accessibility Initiative (WAI) principles when working on web interfaces to ensure usability for people with disabilities.
Anti-fabrication
This skill follows core:anti-fabrication. The claim area is the WCAG version cited and
the ARIA Authoring Practices Guide (APG) pattern attributions. Verified against W3C's
live WCAG22 quickref and the APG patterns index (claude-skills-223): the WCAG citation
was bumped from 2.1 to 2.2 (2.2 became a Recommendation 2023-10-05, and per its own text
"content that conforms to WCAG 2.2 also conforms to WCAG 2.0 and WCAG 2.1" — compatibility
runs 2.2-to-2.1, not the reverse this skill previously implied); and "skip links" was
corrected from an APG pattern to what it actually is, a WCAG bypass-blocks technique — the
APG index lists 30 named patterns and skip links is not one of them. Re-verify against
w3.org/TR/WCAG22/ before citing a WCAG version or success-criterion number this skill
doesn't cover.
Core Principles (POUR)
Web accessibility is organized around four foundational principles:
1. Perceivable
Information must be presentable to users in ways they can perceive.
Key requirements:
- Provide text alternatives for non-text content (images, icons, charts)
- Provide captions and transcripts for multimedia
- Create content that can be presented in different ways (responsive, reflow)
- Make content distinguishable (color contrast, text sizing, audio control)
Quick example:
<img src="chart.png" alt="Sales increased 40% in Q4 2024">
<button aria-label="Close dialog">
<span class="icon-close" aria-hidden="true"></span>
</button>
2. Operable
User interface components must be operable by all users.
Key requirements:
- Make all functionality keyboard accessible
- Provide sufficient time for users to complete tasks
- Avoid content that causes seizures (no rapid flashing)
- Help users navigate and find content
- Support various input modalities (touch, voice, keyboard)
Quick example:
<button>Click me</button> <!-- Already keyboard accessible -->
<!-- Custom interactive element needs keyboard support -->
<div role="button" tabindex="0"
Custom Button
</div>
3. Understandable
Information and UI operation must be understandable.
Key requirements:
- Make text readable and understandable
- Make web pages appear and operate predictably
- Help users avoid and correct mistakes
- Provide clear labels and instructions
Quick example:
<html lang="en">
<label for="email">Email address</label>
<input type="email" id="email"
aria-describedby="email-help"
required>
<div id="email-help">We'll never share your email</div>
4. Robust
Content must work reliably across user agents and assistive technologies.
Key requirements:
- Use valid, well-formed markup
- Ensure compatibility with assistive technologies
- Use ARIA correctly for custom components
- Follow semantic HTML practices
Quick example:
<!-- Use semantic HTML first -->
<nav aria-label="Main navigation">
<ul>
<li><a href="/">Home</a></li>
</ul>
</nav>
<!-- ARIA for custom components when needed -->
<div role="dialog" aria-labelledby="title" aria-modal="true">
<h2 id="title">Dialog Title</h2>
</div>
Common Tasks
Making Forms Accessible
- Associate every label with its input (
for/id or wrapping <label>)
- Identify errors in text and link the message to the failing control
- Indicate required fields in the label, not by color alone
- Pair validation with specific correction guidance
Implementing ARIA
- Use semantic HTML first; add ARIA only when no native element fits
- Keep ARIA states (
aria-expanded, aria-selected) in sync with component state
- Announce dynamic content with live regions (
aria-live, role="status")
- Follow the ARIA Authoring Practices patterns (linked under Resources) for tabs, accordions, modals, and dropdown menus. Skip links are a WCAG technique (a "skip to main content" link as the first focusable element), not an ARIA APG design pattern — the APG's pattern index has no skip-link entry
Testing for Accessibility
- Navigate the full interface with keyboard only (Tab, Shift+Tab, Enter, Space, arrows)
- Test with a screen reader (VoiceOver, NVDA, or JAWS)
- Run automated checkers (axe, Lighthouse, WAVE) as a first pass, not a substitute for manual testing
- Check color contrast against the 4.5:1 text and 3:1 UI-component minimums
Quick Reference Checklist
Every page should have:
For interactive components:
Key Principles
- Semantic HTML first: Use native HTML elements before adding ARIA
- Keyboard accessibility is fundamental: If it works with mouse, it must work with keyboard
- Test with actual users: Include people with disabilities in testing
- Color is not enough: Never use color alone to convey information
- Provide alternatives: Text for images, captions for video, transcripts for audio
- Make it predictable: Consistent navigation and behavior across pages
- Help users recover: Clear error messages with suggestions for correction
Resources
1---2name: accessibility3description: Guide for implementing web accessibility (WCAG). Use when designing UI components, reviewing interfaces for accessibility, or ensuring compliance with W3C WAI standards.4metadata:5 source: https://skillmd.com/skills/vinnie357/accessibility6---78# Web Accessibility910Apply W3C Web Accessibility Initiative (WAI) principles when working on web interfaces to ensure usability for people with disabilities.1112## Anti-fabrication1314This skill follows `core:anti-fabrication`. The claim area is the WCAG version cited and15the ARIA Authoring Practices Guide (APG) pattern attributions. Verified against W3C's16live WCAG22 quickref and the APG patterns index (claude-skills-223): the WCAG citation17was bumped from 2.1 to 2.2 (2.2 became a Recommendation 2023-10-05, and per its own text18"content that conforms to WCAG 2.2 also conforms to WCAG 2.0 and WCAG 2.1" — compatibility19runs 2.2-to-2.1, not the reverse this skill previously implied); and "skip links" was20corrected from an APG pattern to what it actually is, a WCAG bypass-blocks technique — the21APG index lists 30 named patterns and skip links is not one of them. Re-verify against22`w3.org/TR/WCAG22/` before citing a WCAG version or success-criterion number this skill23doesn't cover.2425## Core Principles (POUR)2627Web accessibility is organized around four foundational principles:2829### 1. Perceivable3031Information must be presentable to users in ways they can perceive.3233**Key requirements:**34- Provide text alternatives for non-text content (images, icons, charts)35- Provide captions and transcripts for multimedia36- Create content that can be presented in different ways (responsive, reflow)37- Make content distinguishable (color contrast, text sizing, audio control)3839**Quick example:**40```html41<img src="chart.png" alt="Sales increased 40% in Q4 2024">42<button aria-label="Close dialog">43 <span class="icon-close" aria-hidden="true"></span>44</button>45```4647### 2. Operable4849User interface components must be operable by all users.5051**Key requirements:**52- Make all functionality keyboard accessible53- Provide sufficient time for users to complete tasks54- Avoid content that causes seizures (no rapid flashing)55- Help users navigate and find content56- Support various input modalities (touch, voice, keyboard)5758**Quick example:**59```html60<button>Click me</button> <!-- Already keyboard accessible -->6162<!-- Custom interactive element needs keyboard support -->63<div role="button" tabindex="0"64 onclick="handleClick()"65 onkeydown="handleKeyDown(event)">66 Custom Button67</div>68```6970### 3. Understandable7172Information and UI operation must be understandable.7374**Key requirements:**75- Make text readable and understandable76- Make web pages appear and operate predictably77- Help users avoid and correct mistakes78- Provide clear labels and instructions7980**Quick example:**81```html82<html lang="en">83<label for="email">Email address</label>84<input type="email" id="email"85 aria-describedby="email-help"86 required>87<div id="email-help">We'll never share your email</div>88```8990<!-- vale Flavored.Superlatives = NO -->91### 4. Robust92<!-- vale Flavored.Superlatives = YES -->9394Content must work reliably across user agents and assistive technologies.9596**Key requirements:**97- Use valid, well-formed markup98- Ensure compatibility with assistive technologies99- Use ARIA correctly for custom components100- Follow semantic HTML practices101102**Quick example:**103```html104<!-- Use semantic HTML first -->105<nav aria-label="Main navigation">106 <ul>107 <li><a href="/">Home</a></li>108 </ul>109</nav>110111<!-- ARIA for custom components when needed -->112<div role="dialog" aria-labelledby="title" aria-modal="true">113 <h2 id="title">Dialog Title</h2>114</div>115```116117## Common Tasks118119### Making Forms Accessible120121- Associate every label with its input (`for`/`id` or wrapping `<label>`)122- Identify errors in text and link the message to the failing control123- Indicate required fields in the label, not by color alone124- Pair validation with specific correction guidance125126### Implementing ARIA127128- Use semantic HTML first; add ARIA only when no native element fits129- Keep ARIA states (`aria-expanded`, `aria-selected`) in sync with component state130- Announce dynamic content with live regions (`aria-live`, `role="status"`)131- Follow the ARIA Authoring Practices patterns (linked under Resources) for tabs, accordions, modals, and dropdown menus. Skip links are a WCAG technique (a "skip to main content" link as the first focusable element), not an ARIA APG design pattern — the APG's pattern index has no skip-link entry132133### Testing for Accessibility134135- Navigate the full interface with keyboard only (Tab, Shift+Tab, Enter, Space, arrows)136- Test with a screen reader (VoiceOver, NVDA, or JAWS)137- Run automated checkers (axe, Lighthouse, WAVE) as a first pass, not a substitute for manual testing138- Check color contrast against the 4.5:1 text and 3:1 UI-component minimums139140## Quick Reference Checklist141142**Every page should have:**143- [ ] Valid HTML structure144- [ ] Unique, descriptive page title145- [ ] Proper heading hierarchy (h1, h2, h3...)146- [ ] Language attribute on `<html>`147- [ ] Sufficient color contrast (4.5:1 minimum)148- [ ] Keyboard accessibility for all interactive elements149- [ ] Visible focus indicators150- [ ] Text alternatives for images151- [ ] Form labels associated with inputs152- [ ] Semantic landmark regions153154**For interactive components:**155- [ ] Keyboard accessible (Tab, Enter, Space, Arrow keys)156- [ ] Proper ARIA roles, states, and properties157- [ ] Focus management (modals, dynamic content)158- [ ] Descriptive labels and instructions159- [ ] Error messages linked to form controls160161## Key Principles162163- **Semantic HTML first**: Use native HTML elements before adding ARIA164- **Keyboard accessibility is fundamental**: If it works with mouse, it must work with keyboard165- **Test with actual users**: Include people with disabilities in testing166- **Color is not enough**: Never use color alone to convey information167- **Provide alternatives**: Text for images, captions for video, transcripts for audio168- **Make it predictable**: Consistent navigation and behavior across pages169- **Help users recover**: Clear error messages with suggestions for correction170171## Resources172173- **WCAG 2.2 Guidelines**: https://www.w3.org/WAI/WCAG22/quickref/ (current W3C Recommendation since 2023-10-05; backward-compatible — content conforming to 2.2 also conforms to 2.1 and 2.0)174- **ARIA Authoring Practices**: https://www.w3.org/WAI/ARIA/apg/175- **WebAIM**: https://webaim.org/176- **MDN Accessibility**: https://developer.mozilla.org/en-US/docs/Web/Accessibility