Skip to content
Accessible Astro Documentation

Accessibility

Our approach to accessibility

Section titled “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

Section titled “Key principles”

1. Semantic HTML

Section titled “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

Section titled “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

Section titled “3. ARIA implementation”
  • Proper roles and attributes
  • Dynamic content updates
  • State management
  • Clear labeling
  • Descriptive announcements

4. Visual considerations

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Common patterns”
Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Resources”

Testing tools

Section titled “Testing tools”