Web Accessibility Best Practices

---
applyTo: "**/*.html, **/*.jsx, **/*.tsx, **/*.vue, **/*.svelte"
---

# Web Accessibility Development Instructions (2025)

_Last updated: October 2025_

- Always use the fetch tool to look up WCAG guidelines: https://www.w3.org/WAI/WCAG21/quickref/
- Follow WCAG 2.1 Level AA as minimum standard
- Design for keyboard navigation from the start
- Use semantic HTML elements appropriately
- Test with screen readers (NVDA, JAWS, VoiceOver)
- Implement proper ARIA attributes when needed

**Core Principles (POUR):**

- Perceivable: Content must be presentable in different ways
- Operable: Interface must be usable via keyboard and other input methods
- Understandable: Information and operation must be clear
- Robust: Content must work with current and future technologies

**Semantic HTML:**

- Use proper heading hierarchy (h1-h6)
- Use <nav>, <main>, <article>, <aside>, <footer> landmarks
- Use <button> for actions, <a> for navigation
- Use <label> elements for all form inputs
- Use <table> only for tabular data
- Use lists (<ul>, <ol>) for list content

**Keyboard Navigation:**

- Ensure all interactive elements are keyboard accessible
- Implement logical tab order (avoid positive tabindex)
- Provide visible focus indicators
- Support skip links for main content
- Implement keyboard shortcuts for common actions
- Test navigation with Tab, Enter, Space, Arrow keys

**Screen Reader Support:**

- Provide alt text for all meaningful images
- Use empty alt="" for decorative images
- Implement ARIA labels for icon buttons
- Use aria-live regions for dynamic content
- Provide text alternatives for non-text content
- Test with actual screen readers

**Color and Contrast:**

- Maintain 4.5:1 contrast ratio for normal text
- Maintain 3:1 contrast ratio for large text (18pt+)
- Don't rely on color alone to convey information
- Support high contrast mode
- Provide alternatives to color-coded information
- Test with color blindness simulators

**ARIA Attributes:**

- Use ARIA roles appropriately (button, dialog, menu, etc.)
- Implement aria-label for elements without visible text
- Use aria-describedby for additional context
- Implement aria-expanded for expandable sections
- Use aria-hidden for decorative elements
- Use aria-live for dynamic content updates

**Forms:**

- Associate labels with inputs (for/id or wrapping)
- Provide clear error messages
- Use aria-invalid and aria-describedby for errors
- Group related inputs with fieldset/legend
- Mark required fields with aria-required
- Provide input format hints

**Focus Management:**

- Implement visible focus indicators
- Manage focus for modal dialogs
- Return focus after closing modals
- Set focus to first interactive element in modals
- Use focus trap for modal dialogs
- Skip repetitive navigation with skip links

**Images and Media:**

- Provide alt text for all images
- Use figure/figcaption for image captions
- Provide captions for videos
- Provide transcripts for audio content
- Include audio descriptions for videos
- Use autoplay sparingly (with controls)

**Dynamic Content:**

- Use aria-live regions for updates
- Announce loading states to screen readers
- Manage focus for single-page applications
- Update page titles on route changes
- Announce route changes to screen readers
- Use loading indicators with proper labels

**Interactive Components:**

- Make custom controls keyboard accessible
- Implement proper ARIA roles for custom widgets
- Provide clear labels for all controls
- Use native HTML controls when possible
- Implement proper state management (checked, selected)
- Test with keyboard only

**Tables:**

- Use <th> for header cells with scope attribute
- Use <caption> for table descriptions
- Implement proper table structure
- Use headers attribute for complex tables
- Don't use tables for layout
- Make responsive tables accessible

**Navigation:**

- Provide multiple ways to find content
- Implement breadcrumbs for complex sites
- Use clear, descriptive link text
- Indicate current page in navigation
- Provide site map and search functionality
- Use consistent navigation patterns

**Typography:**

- Use relative units (rem, em) for font sizes
- Ensure text can be resized to 200%
- Maintain readable line length (45-75 characters)
- Use sufficient line height (1.5+)
- Avoid justified text alignment
- Use clear, readable fonts

**Responsive Design:**

- Support zoom up to 200%
- Ensure touch targets are at least 44x44 pixels
- Support portrait and landscape orientation
- Test with screen magnifiers
- Implement responsive navigation
- Support mobile screen readers

**Error Prevention:**

- Provide clear instructions
- Validate inputs client-side with feedback
- Allow users to review before submission
- Provide confirmation for destructive actions
- Allow undo for reversible actions
- Save draft inputs when possible

**Testing:**

- Use automated tools (axe, Lighthouse, WAVE)
- Test with keyboard only
- Test with screen readers
- Test with browser zoom
- Use accessibility linters (eslint-plugin-jsx-a11y)
- Conduct user testing with people with disabilities

**Common Patterns:**

- Modal dialogs: focus trap, ESC to close
- Menus: arrow key navigation, ESC to close
- Tabs: arrow key navigation, proper ARIA
- Accordions: keyboard expandable, proper ARIA
- Tooltips: keyboard accessible, dismissible
- Carousels: keyboard controls, autoplay controls

**Documentation:**

- Document accessibility features
- Provide keyboard shortcuts reference
- Document screen reader behavior
- Include accessibility statement
- Provide contact for accessibility issues
- Keep documentation up to date

**Legal Compliance:**

- Follow WCAG 2.1 Level AA guidelines
- Comply with ADA requirements (US)
- Follow Section 508 standards (US government)
- Comply with EAA (European Accessibility Act)
- Comply with regional accessibility laws
- Conduct regular accessibility audits

**Best Practices:**

- Involve people with disabilities in testing
- Make accessibility part of design process
- Train team on accessibility
- Review accessibility in code reviews
- Set up accessibility CI/CD checks
- Monitor and fix accessibility issues continuously

**Summary:**

> For all accessibility work, always use the fetch tool to look up WCAG guidelines. Build inclusive experiences that work for everyone, regardless of ability.