accessibility-wcag

name	accessibility-wcag
description	WCAG 2.1 Level AA compliance patterns for semantic HTML, ARIA, keyboard navigation, and screen reader compatibility. Use for accessibility audits, ARIA reviews, and POUR principle validation.
user-invocable	true
argument-hint	[component or page to check for WCAG compliance]

Accessibility & WCAG Compliance

Provides WCAG 2.1 Level AA compliance patterns for accessible web development including semantic HTML, ARIA implementation, keyboard navigation, and screen reader compatibility.

Description

This skill teaches accessibility agents how to evaluate and implement WCAG 2.1 Level AA standards across web applications. It covers the four POUR principles (Perceivable, Operable, Understandable, Robust), ARIA attributes, keyboard navigation patterns, color contrast requirements, and assistive technology compatibility.

When to Use

• Reviewing UI components for accessibility compliance
• Implementing keyboard navigation
• Adding ARIA labels and roles
• Evaluating color contrast ratios
• Testing screen reader compatibility
• Conducting WCAG 2.1 audits

When NOT to Use

• Do not use for backend-only changes with no user-facing output.
• Do not use for internal CLI tools where accessibility standards do not apply.

Entry Points

Trigger Phrases: "accessibility review", "WCAG compliance", "screen reader", "keyboard navigation", "ARIA", "a11y audit"

Context Patterns: UI component implementations, form designs, interactive widgets, color scheme changes, content structure updates

Core Knowledge

POUR Principles

Perceivable

• Text alternatives: Alt text for images, transcripts for audio
• Time-based media: Captions for videos, audio descriptions
• Adaptable: Semantic HTML, proper heading hierarchy
• Distinguishable: Color contrast 4.5:1 (text), 3:1 (UI components)

Operable

• Keyboard accessible: All functionality via keyboard, no keyboard traps
• Enough time: Adjustable time limits, pause/stop animations
• Seizures: No flashing content >3 times per second
• Navigable: Skip links, focus indicators, meaningful link text

Understandable

• Readable: Language declared, simple language where possible
• Predictable: Consistent navigation, no unexpected context changes
• Input assistance: Error identification, labels/instructions, error suggestions

Robust

• Compatible: Valid HTML, proper ARIA usage, assistive tech support

ARIA Attributes

Attribute	Purpose	Example
role	Define element purpose	<div role="navigation">
aria-label	Accessible name	<button aria-label="Close dialog">×</button>
aria-labelledby	Reference label ID	<input aria-labelledby="username-label">
aria-describedby	Additional context	<input aria-describedby="password-hint">
aria-hidden	Hide from screen readers	<span aria-hidden="true">★</span>
aria-live	Announce dynamic changes	<div aria-live="polite">
aria-expanded	Collapsible state	<button aria-expanded="false">

Color Contrast Requirements

WCAG 2.1 Level AA:

• Normal text: 4.5:1 minimum
• Large text (18pt+ or 14pt+ bold): 3:1 minimum
• UI components and graphics: 3:1 minimum

Tools: Chrome DevTools (Inspect > Accessibility), WebAIM Contrast Checker

Keyboard Navigation Patterns

Pattern	Keys	Example
Tab order	Tab, Shift+Tab	Form inputs, buttons, links
Menu navigation	Arrow keys	Dropdown menus, tree views
Dialog	Esc (close), Tab (trap focus)	Modal dialogs
Radio group	Arrow keys (select), Tab (exit group)	Radio button sets
Combobox	Arrow keys (options), Enter (select)	Autocomplete inputs

Accessibility Review Template

## Accessibility Review: [Component]

### WCAG 2.1 Level AA Compliance

#### Perceivable
- [ ] Alt text for images (1.1.1)
- [ ] Color contrast ≥4.5:1 for text (1.4.3)
- [ ] Semantic HTML structure (1.3.1)
- [ ] Content not solely conveyed by color (1.4.1)

#### Operable
- [ ] All functionality keyboard accessible (2.1.1)
- [ ] No keyboard traps (2.1.2)
- [ ] Visible focus indicators (2.4.7)
- [ ] Skip navigation links (2.4.1)

#### Understandable
- [ ] Language declared (lang="en") (3.1.1)
- [ ] Labels for form inputs (3.3.2)
- [ ] Error identification and suggestions (3.3.1, 3.3.3)
- [ ] Consistent navigation (3.2.3)

#### Robust
- [ ] Valid HTML (4.1.1)
- [ ] ARIA attributes used correctly (4.1.2)
- [ ] Name, role, value for custom controls (4.1.2)

### Findings

#### BLOCKER: [Issue]
- **WCAG Criterion:** [Number and description]
- **Impact:** [Screen readers, keyboard users, low vision]
- **Location:** [Component:line]
- **Fix:** [Specific recommendation]

### Screen Reader Testing
- **NVDA:** [Pass/Fail with notes]
- **JAWS:** [Pass/Fail with notes]
- **VoiceOver:** [Pass/Fail with notes]

### Verdict
- [ ] APPROVED (WCAG 2.1 AA compliant)
- [ ] MINOR_ISSUES (usable, improvements recommended)
- [ ] MAJOR_ISSUES (blocks compliance, must fix)

Examples

Example: Inaccessible Form

❌ Before (Non-compliant):

<form>
  <input type="text" placeholder="Username">
  <input type="password" placeholder="Password">
  <div style="color: red;">Invalid credentials</div>
  <span onclick="submit()">Submit</span>
</form>

Issues:

1. No labels (WCAG 3.3.2)
2. Error not associated with input (WCAG 3.3.1)
3. Submit not keyboard accessible (WCAG 2.1.1)
4. No focus indicators

✅ After (Compliant):

<form>
  <div>
    <label for="username">Username</label>
    <input
      id="username"
      type="text"
      aria-describedby="username-error"
      aria-invalid="true"
    >
    <span id="username-error" role="alert">
      Invalid credentials. Please check your username and password.
    </span>
  </div>

  <div>
    <label for="password">Password</label>
    <input
      id="password"
      type="password"
      aria-describedby="password-hint"
    >
    <span id="password-hint">
      Must be at least 8 characters
    </span>
  </div>

  <button type="submit">Submit</button>

Improvements:

• Explicit <label> elements (WCAG 3.3.2) ✓
• aria-invalid and aria-describedby for errors (WCAG 3.3.1) ✓
• <button> for keyboard accessibility (WCAG 2.1.1) ✓
• Visible focus indicators (WCAG 2.4.7) ✓

References

• WCAG 2.2 Success Criteria — Key Level A/AA criteria quick reference
• ARIA Patterns — Common patterns, anti-patterns, and code examples

External references

• WCAG 2.2: https://www.w3.org/WAI/WCAG22/quickref/
• ARIA Practices: https://www.w3.org/WAI/ARIA/apg/
• Testing Tools: axe DevTools, WAVE, Pa11y