agents-inc/web-accessibility-web-accessibility

Accessibility

Quick Guide: All interactive elements keyboard accessible. Use headless component libraries for ARIA patterns. WCAG AA minimum (4.5:1 text contrast). Proper form labels and error handling. Combine automated axe-core checks with manual keyboard and screen reader testing.

Detailed Resources:

• examples/core.md - Skip links, semantic HTML, landmarks, button vs link
• examples/forms.md - Form validation, error handling, accessible select
• examples/focus.md - Modal dialogs, focus indicators
• examples/color.md - Contrast, color-independent indicators, tokens
• examples/tables.md - Sortable data tables
• examples/touch-targets.md - Touch target sizing
• examples/screen-reader.md - sr-only, hiding decorative content
• examples/testing.md - Accessibility testing with axe-core
• reference.md - Decision frameworks, anti-patterns, WCAG quick reference

---

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST ensure all interactive elements are keyboard accessible with visible focus indicators)

(You MUST use headless component libraries for complex ARIA patterns instead of manual implementation)

(You MUST maintain WCAG AA minimum contrast ratios - 4.5:1 for text, 3:1 for UI components)

(You MUST never use color alone to convey information - always add icons, text, or patterns)

</critical_requirements>

---

Auto-detection: Accessibility (a11y), WCAG compliance, ARIA patterns, keyboard navigation, screen reader support, focus management, aria-label, aria-live, role attribute, skip link

When to use:

• Implementing keyboard navigation and focus management
• Ensuring WCAG AA color contrast (4.5:1 text, 3:1 UI components)
• Building interactive components (buttons, forms, modals, tables) with proper ARIA
• Adding dynamic content updates (live regions, status messages)
• Implementing skip links, landmarks, and semantic HTML structure
• Handling motion preferences with prefers-reduced-motion

When NOT to use:

• Working on backend/API code with no UI
• Writing build scripts or configuration files
• Creating documentation or non-rendered content
• Working with CLI tools (different accessibility considerations)

Target: WCAG 2.2 Level AA compliance (minimum), AAA where feasible

---

<philosophy>

Philosophy

Accessibility ensures digital products are usable by everyone, including users with disabilities. Accessibility is a requirement, not a feature - it should be built in from the start, not retrofitted.

Key philosophy:

• Semantic HTML first - Use native elements for built-in accessibility
• Headless components for complex patterns - Leverage tested, accessible component primitives from your component library
• Progressive enhancement - Start with keyboard, add mouse interactions on top
• WCAG as baseline - Meet AA minimum, aim for AAA where feasible

</philosophy>

---

<patterns>

Core Patterns

Keyboard Navigation Standards

CRITICAL: All interactive elements must be keyboard accessible

Tab Order

• Logical flow - Tab order must follow visual reading order (left-to-right, top-to-bottom)
• No keyboard traps - Users can always tab away from any element
• Skip repetitive content - Provide skip links to main content
• tabindex rules:
  • tabindex="0" - Adds element to natural tab order (use sparingly)
  • tabindex="-1" - Programmatic focus only (modal content, headings)
  • Never use tabindex > 0 (creates unpredictable tab order)

Focus Management

• Visible focus indicators - Always show clear focus state (never outline: none without replacement)
• Focus on open - When opening modals/dialogs, move focus to first interactive element or close button
• Focus on close - Restore focus to trigger element when closing modals/dialogs
• Focus trapping - Trap focus inside modals using your headless component library or manual implementation
• Programmatic focus - Use element.focus() for dynamic content (search results, error messages)

Keyboard Shortcuts

• Standard patterns:
  • Escape - Close modals, cancel actions, clear selections
  • Enter/Space - Activate buttons and links
  • Arrow keys - Navigate lists, tabs, menus, sliders
  • Home/End - Jump to first/last item
  • Tab/Shift+Tab - Navigate between interactive elements

Skip Links

MANDATORY for pages with navigation - place as first focusable element, visually hidden until focused.

// components/skip-link.tsx
export function SkipLink({ className }: { className?: string }) {
  return (
    <a href="#main-content" className={className}>
      Skip to main content
    </a>
  );
}

See examples/core.md for full skip link implementation with styling.

---

ARIA Patterns

Use headless component libraries - they handle ARIA automatically for complex patterns like dialogs, selects, tabs, tooltips, and popovers.

Component-Specific ARIA

Buttons:

• aria-label - For icon-only buttons
• aria-pressed - For toggle buttons
• aria-expanded - For expandable sections
• aria-disabled - Use with disabled attribute

Forms:

• aria-required - Required fields (use with required)
• aria-invalid - Invalid fields
• aria-describedby - Link to error messages, helper text
• aria-errormessage - Explicit error message reference

Navigation:

• aria-current="page" - Current page in navigation
• aria-label - Describe navigation purpose ("Main navigation", "Footer navigation")

Modals/Dialogs:

• role="dialog" or role="alertdialog"
• aria-modal="true"
• aria-labelledby - Points to dialog title
• aria-describedby - Points to dialog description

Tables:

• scope="col" and scope="row" for headers
• <caption> for table description
• aria-sort for sortable columns

Live Regions

Use for dynamic content updates:

• aria-live="polite" - Announce when user is idle (status messages, non-critical updates)
• aria-live="assertive" - Announce immediately (errors, critical alerts)
• aria-atomic="true" - Announce entire region content
• role="status" - For status messages (implies aria-live="polite")
• role="alert" - For error messages (implies aria-live="assertive")

Best practices:

• Keep messages concise and meaningful
• Clear old messages before new ones
• Don't spam with rapid updates (debounce)

---

Color Contrast & Visual Design

Text contrast (AA):

• Normal text (< 18px): 4.5:1 minimum
• Large text (>= 18px or >= 14px bold): 3:1 minimum
• AAA (recommended): 7:1 for normal, 4.5:1 for large

Non-text contrast:

• UI components (buttons, form inputs): 3:1 minimum
• Focus indicators: 3:1 against background
• Icons (functional): 3:1 minimum

Color Independence:

• Add icons to color-coded states (check for success, X for error)
• Use text labels with status colors
• Provide patterns/textures in charts
• Underline links in body text

See examples/color.md for contrast examples and design tokens.

---

Semantic HTML

Always use semantic HTML:

• <button> for actions (not <div onclick>)
• <a> for navigation (not <div onclick>)
• <nav> for navigation sections
• <main> for primary content (one per page)
• <header> and <footer> for page sections
• <ul>/<ol> for lists
• <table> for tabular data (not divs with grid CSS)
• <form> with proper <label> associations

Never:

• Use <div> or <span> for interactive elements
• Use click handlers on non-interactive elements without proper role
• Use tables for layout
• Use placeholder as label replacement

---

Form Accessibility

Label Associations:

• Always use proper <label> with htmlFor attribute
• Or wrap input inside label element

Error Handling:

• aria-invalid="true" on invalid fields
• aria-describedby linking to error message
• role="alert" on error messages for screen reader announcement
• Visual error indicators (icons, border color)
• Error summary at top of form for multiple errors

See examples/forms.md for complete form validation and error handling patterns.

---

Focus Indicators

Minimum requirements:

• 3:1 contrast ratio against background
• 2px minimum thickness
• Clear visual difference from unfocused state
• Consistent across all interactive elements

Use :focus-visible for better UX:

/* Shows only for keyboard navigation, not mouse clicks */
button:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

See examples/focus.md for full focus indicator patterns.

---

Touch Target Sizes

WCAG 2.2 Target Size Requirements:

• Level AA (2.5.8): 24x24 CSS pixels minimum, or adequate spacing (24px between targets)
• Level AAA (2.5.5): 44x44 CSS pixels (recommended for best UX)
• Exceptions: inline text links, user agent controls, essential designs

See examples/touch-targets.md for sizing and spacing examples.

---

Screen Reader Support

• Use .sr-only class for screen reader only text
• Use aria-label for icon-only buttons
• Use empty alt="" for decorative images
• Use aria-hidden="true" for decorative content (but never on focusable elements)

See examples/screen-reader.md for sr-only and hiding patterns.

---

Motion and Animation Accessibility

WCAG 2.3.3 Animation from Interactions (AAA):

Motion can cause nausea, dizziness, or vestibular disorders (affects 70+ million people). Use prefers-reduced-motion to respect user preferences:

/* Only animate when user has no motion preference */
@media (prefers-reduced-motion: no-preference) {
  .animated-element {
    animation: slide-in 300ms ease-out;
  }
}

Key principles:

• reduce means minimize, not eliminate all motion - essential animations can remain
• Replace motion effects (scale, rotate, slide) with non-motion effects (fade, dissolve, color change)
• Provide pause/stop controls for auto-playing content longer than 5 seconds
• Avoid parallax scrolling effects or provide alternatives

---

WCAG 2.2 New Success Criteria

WCAG 2.2 (W3C Recommendation October 2023, ISO/IEC 40500:2025 as of October 2025) added 9 new success criteria. Key ones for developers:

Level A:

• 3.2.6 Consistent Help - Help mechanisms (contact, chat) must appear in same relative order across pages
• 3.3.7 Redundant Entry - Previously entered info must be auto-populated or available for selection

Level AA:

• 2.4.11 Focus Not Obscured (Minimum) - Focused element must not be entirely hidden by other content (sticky headers, modals)
• 2.5.7 Dragging Movements - Provide single-pointer alternative to drag operations
• 2.5.8 Target Size (Minimum) - 24x24px minimum or adequate spacing
• 3.3.8 Accessible Authentication - No cognitive function tests (CAPTCHAs) unless alternatives exist

Level AAA:

• 2.4.12 Focus Not Obscured (Enhanced) - No part of focus indicator hidden
• 2.4.13 Focus Appearance - Focus indicator 2px perimeter, 3:1 contrast
• 3.3.9 Accessible Authentication (Enhanced) - Stricter CAPTCHA requirements

Removed from WCAG 2.2:

• 4.1.1 Parsing - Obsolete due to modern browser error correction

</patterns>

---

Testing Accessibility

Multi-layered approach required - automated tools catch ~57% of WCAG issues. Always combine with manual testing.

Automated: Use axe-core based tools in your test runner for automated WCAG checks. See examples/testing.md for axe integration patterns.

Manual keyboard checklist:

• [ ] Tab through all interactive elements in logical order
• [ ] Activate buttons with Enter/Space
• [ ] Close modals with Escape
• [ ] Navigate dropdowns with arrows
• [ ] No keyboard traps
• [ ] Focus indicators visible on all elements

Manual screen reader checklist:

• [ ] All images have alt text (or alt="" if decorative)
• [ ] Form inputs have labels
• [ ] Error messages are announced
• [ ] Headings create logical outline
• [ ] Landmarks are labeled
• [ ] Live regions announce updates

Manual visual checklist:

• [ ] Color contrast meets WCAG AA (4.5:1 text, 3:1 UI)
• [ ] Information not conveyed by color alone
• [ ] Text resizable to 200% without horizontal scroll
• [ ] Touch targets meet 24x24px minimum (AA)
• [ ] Focus indicators have 3:1 contrast
• [ ] Animations respect prefers-reduced-motion

Screen readers to test with: NVDA (Windows, free), JAWS (Windows, paid), VoiceOver (macOS/iOS, built-in), TalkBack (Android, built-in)

---

<red_flags>

RED FLAGS

High Priority Issues:

• Removing focus outlines without replacement - keyboard users can't navigate, violates WCAG 2.4.7
• Using div or span for buttons/links - no semantic meaning, no keyboard support
• Click handlers on non-interactive elements without role/keyboard support - violates WCAG 2.1.1
• Form inputs without labels - screen readers can't announce purpose, violates WCAG 1.3.1

Medium Priority Issues:

• Color-only error indicators - color-blind users can't distinguish
• Placeholder text as label replacement - disappears on input
• Auto-playing audio/video without controls - violates WCAG 1.4.2

Gotchas & Edge Cases:

• :focus vs :focus-visible - use :focus-visible to avoid focus rings on mouse clicks
• Empty alt="" is correct for decorative images - don't skip the alt attribute entirely
• aria-hidden="true" also hides from keyboard - don't use on focusable elements
• role="button" on <div> doesn't add keyboard support - still need Enter/Space handlers
• prefers-reduced-motion: reduce means minimize, not eliminate - essential animations can remain
• Live regions announce ALL content - keep messages concise to avoid spam

See reference.md for full anti-patterns with code examples.

</red_flags>

---

Resources

Official guidelines:

• WCAG 2.2 Guidelines: https://www.w3.org/WAI/WCAG22/quickref/
• What's New in WCAG 2.2: https://www.w3.org/WAI/standards-guidelines/wcag/new-in-22/
• WAI-ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/

Tools:

• axe DevTools: https://www.deque.com/axe/devtools/
• WAVE: https://wave.webaim.org/
• WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/

---

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST ensure all interactive elements are keyboard accessible with visible focus indicators)

(You MUST use headless component libraries for complex ARIA patterns instead of manual implementation)

(You MUST maintain WCAG AA minimum contrast ratios - 4.5:1 for text, 3:1 for UI components)

(You MUST never use color alone to convey information - always add icons, text, or patterns)

Failure to follow these rules will make the site unusable for keyboard users, screen reader users, and color-blind users - violating WCAG 2.2 Level AA compliance.

</critical_reminders>