ARIA Attributes and Roles Guide

Overview

This document outlines the ARIA (Accessible Rich Internet Applications) implementation in the Understated theme. All interactive components are designed to be accessible to users with assistive technologies.

Core Components

Forms

  • Form components use proper ARIA roles and states
  • Error messages are announced using aria-live
  • Form controls have associated labels and descriptions
  • Required fields are marked with aria-required
  • Error states use aria-invalid and aria-errormessage
<Form aria-label="Contact form">
  <FormItem>
    <FormLabel htmlFor="email">Email</FormLabel>
    <Input
      id="email"
      type="email"
      required
      aria-describedby="email-description"
      aria-errormessage="email-error"
    />
    <FormDescription id="email-description">
      We'll never share your email.
    </FormDescription>
    <FormMessage id="email-error" />
  </FormItem>
</Form>

Cards and Regions

  • Cards use the region role when containing important content
  • Regions have proper labeling via aria-labelledby or aria-label
  • Content sections use semantic HTML5 elements with ARIA roles
<Card
  role="region"
  aria-labelledby="card-title"
>
  <Heading id="card-title">Card Title</Heading>
  <p>Card content...</p>
</Card>
  • Navigation uses proper landmark roles
  • Current page is indicated with aria-current
  • Menu items use proper ARIA roles
  • Skip links are provided for keyboard users
<nav role="navigation" aria-label="Main">
  <ul role="menubar">
    <li role="none">
      <a role="menuitem" aria-current="page">
        Current Page
      </a>
    </li>
  </ul>
</nav>

Best Practices

Landmarks

  1. Use proper landmark roles:
    • banner for header
    • main for main content
    • navigation for nav
    • contentinfo for footer
    • complementary for asides
    • search for search functionality

Live Regions

  1. Use aria-live appropriately:
    • assertive for important updates
    • polite for less critical updates
    • Only use when necessary

Focus Management

  1. Visible focus indicators
  2. Logical tab order
  3. No keyboard traps
  4. Skip links for main content

Form Controls

  1. All inputs have labels
  2. Error messages are associated
  3. Required fields are marked
  4. Groups are properly labeled

Testing

  1. Use screen readers
  2. Test keyboard navigation
  3. Verify ARIA attributes
  4. Check focus management
  5. Test with assistive technologies

Resources

accessibility
aria
documentation