Web Accessibility (WCAG 2.1 AA)

Status: Production Ready ✅ Last Updated: 2026-01-14 Production Tested: Framework-agnostic patterns used across multiple production sites

---

Auto-Trigger Keywords

Claude Code automatically discovers this skill when you mention:

Primary Keywords

• accessibility
• a11y
• wcag
• screen reader
• keyboard navigation
• semantic html
• aria
• focus management

Secondary Keywords

• accessible forms
• color contrast
• alt text
• focus trap
• aria-label
• aria-live
• skip links
• focus indicators
• tab order
• heading hierarchy
• form labels
• screen reader support

Error-Based Keywords

• "focus outline missing"
• "insufficient contrast"
• "aria-label required"
• "keyboard trap"
• "screen reader not announcing"
• "can't tab to element"
• "focus not visible"
• "missing alt text"
• "form label missing"
• "heading level skipped"
• "color contrast too low"
• "not keyboard accessible"

---

What This Skill Does

Build fully accessible web interfaces that meet WCAG 2.1 Level AA standards with semantic HTML, proper ARIA implementation, and comprehensive keyboard support.

Core Capabilities

✅ Semantic HTML guidance - Choose the right element for every purpose ✅ ARIA patterns - When and how to use ARIA roles, states, properties ✅ Focus management - Focus traps, restoration, skip links, visible indicators ✅ Color contrast - 4.5:1 text, 3:1 UI component ratios with testing ✅ Form accessibility - Labels, validation, error announcements ✅ Keyboard navigation - Full keyboard support for all interactions ✅ Screen reader testing - NVDA/VoiceOver testing workflows ✅ Automated auditing - a11y-auditor agent for violation detection

---

Known Issues This Skill Prevents

---

When to Use This Skill

✅ Use When:

• Building any web interface (accessibility is not optional)
• Implementing forms with validation
• Creating dialogs, menus, tabs, accordions
• Adding dynamic content updates
• Troubleshooting keyboard navigation issues
• Fixing screen reader compatibility
• Need to meet WCAG 2.1 AA compliance
• Auditing existing pages for violations
• Choosing between semantic elements
• Implementing focus management

❌ Don't Use When:

• Building native mobile apps (different standards)
• Creating PDFs (different techniques)
• User explicitly wants to learn by experimentation
• Internal prototype with no accessibility requirements (but still recommended)

---

Quick Usage Example

# 1. Ask Claude to check accessibility
"Use the a11y-auditor agent to scan my login form"

# 2. Get semantic HTML guidance
"Should I use a button or a link for this?"

# 3. Fix specific issues
"How do I make this dialog keyboard accessible?"

# 4. Implement patterns
"Show me an accessible tabs component"

# 5. Check color contrast
"Is #999 on #fff sufficient contrast?"

Result: WCAG 2.1 AA compliant interfaces with keyboard, screen reader, and visual accessibility support.

Full instructions: See SKILL.md

---

Token Efficiency Metrics

---

WCAG 2.1 AA Coverage

Compliance Level: WCAG 2.1 Level AA (all 50 success criteria)

---

Dependencies

Prerequisites: None (framework-agnostic)

Integrates With:

• React, Vue, Svelte, vanilla JS (patterns work everywhere)
• Tailwind v4 (color contrast patterns)
• React Hook Form (accessible form patterns)
• Any UI framework

Testing Tools Required:

• axe DevTools (browser extension)
• NVDA (Windows screen reader - free)
• VoiceOver (Mac screen reader - built-in)
• Chrome/Firefox DevTools (contrast checker)
• Lighthouse (built into Chrome)

---

File Structure

accessibility/
├── SKILL.md                   # Complete documentation
├── README.md                  # This file
├── references/                # Detailed reference docs
│   ├── wcag-checklist.md      # Complete WCAG 2.1 AA requirements
│   ├── semantic-html.md       # Element selection guide
│   ├── aria-patterns.md       # ARIA roles, states, properties
│   ├── focus-management.md    # Focus patterns and techniques
│   ├── color-contrast.md      # Contrast requirements and testing
│   └── forms-validation.md    # Accessible form patterns
├── rules/                     # Correction rules
│   └── accessibility.md       # Common mistake corrections
└── agents/                    # Sub-agents
    └── a11y-auditor.md        # Automated accessibility auditor

---

Official Documentation

• WCAG 2.1 Quick Reference: https://www.w3.org/WAI/WCAG21/quickref/
• MDN Accessibility: https://developer.mozilla.org/en-US/docs/Web/Accessibility
• ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/
• WebAIM Articles: https://webaim.org/articles/
• axe DevTools: https://www.deque.com/axe/devtools/

---

Related Skills

• react-hook-form-zod - Accessible form validation patterns
• tailwind-v4-shadcn - Color contrast with semantic tokens
• cloudflare-turnstile - Accessible CAPTCHA alternative

---

Contributing

Found an issue or have a suggestion?

• Open an issue: https://github.com/jezweb/claude-skills/issues
• See SKILL.md for detailed documentation

---

License

MIT License - See main repo LICENSE file

---

Production Tested: Framework-agnostic patterns Token Savings: ~68% Error Prevention: 100% (12 documented issues prevented) Ready to use! See SKILL.md for complete setup.