Accessibility A11y

---
name: accessibility-a11y
description: Implement web accessibility (a11y) best practices following WCAG guidelines to create inclusive, accessible user interfaces.
---

# Accessibility (a11y) Best Practices

You are an expert in web accessibility and inclusive design. Apply these guidelines to ensure all users can access and interact with web applications regardless of their abilities.

## Core Accessibility Principles

- Follow WCAG (Web Content Accessibility Guidelines) standards
- Use semantic HTML to improve accessibility and screen reader compatibility
- Ensure high accessibility standards using ARIA roles and native accessibility props
- Design for all users including those with visual, auditory, motor, and cognitive disabilities
- Test with various assistive technologies

## Semantic HTML

### Structural Elements
- Use semantic elements like `<header>`, `<main>`, `<footer>`, `<nav>`, `<article>`, `<section>`, `<aside>`
- Employ `<button>` for interactive elements, not `<div>` or `<span>`
- Use proper heading hierarchy (h1-h6) without skipping levels
- Use landmarks (e.g., `<nav>`, `<main>`, `<aside>`) for screen reader navigation
- Avoid deprecated markup

### Form Accessibility
- Associate labels with form inputs using `for` and `id` attributes
- Group related form elements with `<fieldset>` and `<legend>`
- Provide clear error messages and validation feedback
- Use appropriate input types (email, tel, number, etc.)
- Include placeholder text as supplementary hints, not replacements for labels

## ARIA Implementation

### When to Use ARIA
- Use ARIA roles and attributes to enhance accessibility where semantic HTML is insufficient
- Prefer native HTML elements over ARIA when possible
- Use `aria-label` for elements without visible text labels
- Implement `aria-describedby` for additional context
- Use `aria-live` regions for dynamic content updates

### Common ARIA Patterns
- Use `role="button"` only when a non-button element must act as a button
- Implement `aria-expanded` for collapsible content
- Use `aria-hidden="true"` for decorative elements
- Apply `aria-current="page"` for navigation highlighting
- Use `aria-labelledby` to reference visible labels

## Visual Accessibility

### Color and Contrast
- Ensure sufficient color contrast for text (minimum 4.5:1 for normal text, 3:1 for large text)
- Never use color as the only means of conveying information
- Provide alternative indicators (icons, patterns, text) alongside color
- Test designs with color blindness simulators

### Focus Management
- Use focus styles to indicate focus state clearly
- Ensure visible focus indicators on all interactive elements
- Manage focus appropriately when content changes dynamically
- Avoid removing outline styles without providing alternatives
- Implement logical tab order

## Keyboard Navigation

### Navigation Requirements
- Provide keyboard navigation for all interactive elements
- Ensure all functionality is accessible via keyboard alone
- Use tabindex appropriately (0 for natural order, -1 for programmatic focus)
- Implement keyboard shortcuts for complex interactions
- Avoid keyboard traps

### Interactive Elements
- Ensure interactive elements are large enough for touch (minimum 44x44 pixels)
- Implement keyboard event handlers (`onKeyDown`, `onKeyPress`) alongside click handlers
- Support Enter and Space keys for activating buttons
- Implement arrow key navigation for complex widgets

## Content Accessibility

### Images and Media
- Ensure all images have descriptive alt text
- Use empty alt="" for decorative images
- Provide captions for videos
- Include transcripts for audio content
- Use descriptive link text (avoid "click here")

### Text and Typography
- Use relative units (rem, em) for typography
- Ensure text can be resized up to 200% without loss of functionality
- Maintain adequate line height and letter spacing
- Avoid justified text which can create uneven spacing
- Support user preferences for reduced motion

## Responsive and Adaptive Design

### Mobile-First Approach
- Design mobile-first, then scale upward
- Implement responsive layouts that work across devices
- Ensure touch targets are appropriately sized
- Support both portrait and landscape orientations

### User Preferences
- Respect `prefers-reduced-motion` for animations
- Support `prefers-color-scheme` for dark/light modes
- Consider `prefers-contrast` for high contrast needs
- Implement `prefers-reduced-transparency` when applicable

## Testing and Validation

### Automated Testing
- Use tools like Lighthouse for accessibility audits
- Integrate axe-core for automated accessibility testing
- Run accessibility checks in CI/CD pipelines
- Address all critical and serious accessibility issues

### Manual Testing
- Test with screen readers (NVDA, JAWS, VoiceOver)
- Navigate entirely by keyboard
- Test with browser zoom at 200%
- Use browser accessibility inspection tools
- Test with actual users who have disabilities when possible

## CSS Best Practices for Accessibility

- Use external stylesheets; avoid inline styles for maintainability
- Leverage Flexbox and Grid for robust layouts
- Use class selectors for styling (BEM naming methodology recommended)
- Implement responsive design with media queries
- Ensure hover states also have focus equivalents