Skip to content
Accessible Astro Documentation

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

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

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

<!-- 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

Resources

Testing tools