Accessibility

Our approach to accessibility

Accessibility isn’t an afterthought in Accessible Astro—it’s our foundation. We follow the WAI-ARIA guidelines and WCAG 2.2 standards to ensure our components and themes work for everyone, regardless of how they interact with the web.

Key principles

1. Semantic HTML

• Using proper HTML elements (<button>, <nav>, <main>, etc.)
• Maintaining logical heading hierarchy
• Providing meaningful landmarks
• Using lists for navigation items

2. Keyboard navigation

• All interactive elements are focusable
• Focus order matches visual order
• Clear focus indicators
• Keyboard shortcuts where appropriate
• Proper tab management in modals

3. ARIA implementation

• Proper roles and attributes
• Dynamic content updates
• State management
• Clear labeling
• Descriptive announcements

4. Visual considerations

• Sufficient color contrast
• Content visible without color
• Text resizing without loss of functionality
• Responsive design that works at 400% zoom
• Support for high contrast modes

All our components meet WCAG 2.2 Level AA contrast requirements by default, with many meeting the stricter AAA level.

User preferences

We respect user preferences through:

/* Reduced motion */
@media (prefers-reduced-motion: reduce) {
  /* Motion-based animations are disabled */
}

/* Color scheme */
@media (prefers-color-scheme: dark) {
  /* Dark mode styles */
}

/* Contrast (coming soon) */
@media (prefers-contrast: more) {
  /* High contrast styles */
}

Screen reader support

Our components are tested with popular screen readers:

• NVDA on Windows
• VoiceOver on macOS
• TalkBack on Android
• VoiceOver on iOS

We recommend testing your implementation with real screen readers to ensure the best experience for your users.

Focus management

We handle focus carefully:

• Trapping focus in modals
• Returning focus after modal closes
• Skip links for main content
• Proper focus order in complex components
• Clear focus styles that work on all backgrounds

Common patterns

Buttons vs Links

<!-- Use buttons for actions -->
<button type="button" onClick={handleAction}> Perform Action </button>

<!-- Use links for navigation -->
<a href="/some-page"> Go to Page </a>

Hidden content

<!-- Visually hidden but available to screen readers -->
<span class="sr-only">Additional context</span>

<!-- Hidden from all users -->
<div hidden>Not visible or announced</div>

Dynamic content

<!-- Live regions for important updates -->
<div role="status" aria-live="polite">Status message</div>

<!-- Busy indicators -->
<button aria-busy="true"> Processing... </button>

Best practices

1. Test early and often

• Use keyboard navigation
• Test with screen readers
• Verify color contrast
• Check at different zoom levels

2. Progressive enhancement

• Ensure basic functionality without JavaScript
• Add enhanced interactions thoughtfully
• Provide fallbacks for modern features

3. Clear communication

• Use clear, concise language
• Provide helpful error messages
• Include proper form labels
• Use descriptive link text

We recommend using the eslint-plugin-jsx-a11y package to catch common accessibility issues during development. This plugin is already included in our starter themes:

npm install -D eslint-plugin-jsx-a11y

Resources

• WAI-ARIA Practices Guide
• WCAG 2.2 Guidelines
• A11y Project Checklist
• Inclusive Components

Testing tools

• axe DevTools
• WAVE Browser Extension
• Lighthouse
• Color Contrast Analyzer

While automated tools are helpful, they can’t catch all accessibility issues. Manual testing and user feedback are essential. See our accessibility testing page for more information.