Wcag Accessibility

WCAG 2.2 AA Accessibility

Comprehensive accessibility guidance for web applications targeting WCAG 2.2 Level AA conformance.

Architecture Overview

[Component Authoring]
    ├── Semantic HTML (landmarks, headings, lists)
    ├── ARIA attributes (roles, states, properties)
    ├── Keyboard interaction (focus, tab order, shortcuts)
    └── Visual design (contrast, spacing, motion)
              ↓
[Automated Testing]
    ├── axe-core / jest-axe (unit)
    ├── Lighthouse CI (integration)
    └── pa11y (page-level)
              ↓
[Manual Testing]
    ├── Keyboard-only navigation
    ├── Screen reader walkthrough (VoiceOver, NVDA)
    └── Zoom to 200% / reflow check
              ↓
[Continuous Compliance]
    ├── CI gate (axe failures block merge)
    ├── Design token enforcement (contrast-safe palette)
    └── Periodic audit (quarterly full review)

Quick Reference

Decision Matrix

Text Contrast Requirements (WCAG 1.4.3 / 1.4.6)

Common Tailwind Opacity Pitfalls

Opacity modifiers on semantic color tokens (e.g., text-muted-foreground/60) reduce contrast below WCAG thresholds. Common failures:

Rule of thumb: Never apply opacity below /80 to text tokens. If you need visual hierarchy below text-muted-foreground, the design system's contrast floor has been reached — use size, weight, or spacing instead.

Interactive Element Requirements

Screen Reader Essentials

// Visually hidden but screen-reader accessible
<span className="sr-only">Close dialog</span>

// Live regions for dynamic content
<div aria-live="polite" aria-atomic="true">
  {statusMessage}
</div>

// Assertive for errors
<div aria-live="assertive" role="alert">
  {errorMessage}
</div>

Core Principles

1. Perceivable — Content must be presentable in ways all users can perceive (contrast, alt text, captions)
2. Operable — UI must be operable via keyboard, with enough time, no seizure triggers
3. Understandable — Content and UI behavior must be understandable (labels, errors, consistent navigation)
4. Robust — Content must be interpreted reliably by assistive technologies (semantic HTML, valid ARIA)

Hover/Focus Content (WCAG 1.4.13)

Tooltips, popovers, and any content triggered by hover or focus must be:

// Dismissible — user can close without moving pointer (Escape key)
// Hoverable — user can move pointer over the tooltip without it disappearing
// Persistent — stays visible until user dismisses, moves focus, or info becomes invalid

// PASS — Radix UI Tooltip handles all three requirements
<Tooltip>
  <TooltipTrigger>Hover me</TooltipTrigger>
  <TooltipContent>
    This tooltip is dismissible, hoverable, and persistent
  </TooltipContent>
</Tooltip>

// FAIL — disappears when pointer moves away from trigger
<div
  => setShow(true)}
  => setShow(false)}  // Can't hover the tooltip content
>
  {show && <div className="absolute">Tooltip content</div>}
</div>

// PASS — tooltip stays visible when hovering its content
<div
  => setShow(true)}
  => setShow(false)}
>
  Trigger
  {show && (
    <div
      => setShow(true)}   // Keep open when hovering content
      => setShow(false)}
    >
      Tooltip content
    </div>
  )}
</div>

Status Messages (WCAG 4.1.3)

Dynamic status updates must be announced to screen readers without receiving focus:

// Toast notifications
<div role="status" aria-live="polite">
  {toast && <p>{toast.message}</p>}
</div>

// Search result counts
<div role="status" aria-live="polite" aria-atomic="true">
  {results.length} listings found
</div>

// Form submission success
<div role="status">Listing saved successfully</div>

// Error alerts (urgent — use assertive)
<div role="alert">Payment failed. Please try again.</div>

// Loading progress
<div role="status" aria-live="polite">
  Uploading... {progress}% complete
</div>

WCAG 2.2 Complete Success Criteria Coverage

All 50 Level A + AA success criteria are covered across the skill resources:

Principle 1: Perceivable

Principle 2: Operable

Principle 3: Understandable

Principle 4: Robust

Note: 4.1.1 Parsing was removed in WCAG 2.2 and is no longer required.

When Reviewing Code

Run this checklist on every component:

• Color contrast meets 4.5:1 for text, 3:1 for UI components
• No information conveyed by color alone (use icons, patterns, or text too)
• All interactive elements reachable and operable by keyboard
• Focus order is logical and visible
• Images have meaningful alt text (or alt="" + aria-hidden if decorative)
• Form inputs have associated <label> elements
• Error messages are programmatically associated with inputs (aria-describedby)
• Dynamic content updates announced via aria-live regions
• No content flashes more than 3 times per second
• Page works at 200% zoom without horizontal scrolling
• Content reflows at 320px width without horizontal scrolling
• Touch targets are at least 24x24 CSS pixels (44x44 preferred)
• Drag operations have single-pointer alternatives
• Tooltips/popovers are dismissible, hoverable, and persistent
• <html lang> is set correctly
• Page has unique, descriptive <title>
• DOM order matches visual reading order
• Links have descriptive text (no "click here")
• Navigation is consistent across pages
• Paste is not blocked on password/code fields
• prefers-reduced-motion is respected for all animations