Aria Patterns

ARIA Patterns Guide

Overview

Implement accessible interactive components using correct ARIA roles, states, and properties. Provides copy-paste patterns for common widgets that work with screen readers and keyboard navigation.

When to Use

• Building custom interactive components
• Making dynamic content accessible
• Fixing screen reader issues
• Adding keyboard support to custom widgets

Quick Reference: First Rules of ARIA

1. Don't use ARIA if native HTML works - ` over `
2. Don't change native semantics - Don't put role="button" on a heading
3. All interactive ARIA elements must be keyboard accessible
4. Don't use role="presentation" or aria-hidden="true" on focusable elements
5. All interactive elements must have accessible names

The Process

1. Identify component type: What widget pattern matches?
2. Check native HTML first: Can a semantic element do this?
3. Apply ARIA pattern: Roles, states, properties
4. Add keyboard support: Expected keys for the pattern
5. Test with screen reader: Verify announcements

Component Patterns

Button

Native (preferred):

Click me

Custom (when necessary):

  Toggle

function handleKeyDown(e) {
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault();
    e.target.click();
  }
}

Toggle Button

  Enable Dark Mode

---

Modal Dialog

  Confirm Action
  Are you sure you want to proceed?

  Cancel
  Confirm

Required behavior:

• Focus moves to dialog on open
• Focus trapped within dialog
• Escape key closes dialog
• Focus returns to trigger on close

// Focus trap example
function trapFocus(dialog) {
  const focusable = dialog.querySelectorAll(
    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
  );
  const first = focusable[0];
  const last = focusable[focusable.length - 1];

  dialog.addEventListener('keydown', (e) => {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault();
        last.focus();
      } else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault();
        first.focus();
      }
    }
  });
}

---

Dropdown Menu

  
    Options
  

  
    
      Edit
    
    
      Duplicate
    
    
      Delete
    
  

Keyboard:

• Enter/Space: Open menu, activate item
• Arrow Down: Next item (or first if closed)
• Arrow Up: Previous item
• Escape: Close menu
• Home: First item
• End: Last item

---

Tabs

  
    
      Profile
    
    
      Security
    
    
      Billing
    
  

  
    Profile content...
  
  
    Security content...
  
  
    Billing content...
  

Keyboard:

• Arrow Left/Right: Move between tabs
• Home: First tab
• End: Last tab
• Tab: Move into panel content

---

Accordion

  
    
      Section 1
    
  
  
    Section 1 content...
  

  
    
      Section 2
    
  
  
    Section 2 content...
  

---

Tooltip

  Help

  Click here for more information

Note: For interactive content, use a disclosure or dialog instead.

---

Alert / Status Messages

  Error: Please enter a valid email address.

  3 items in cart

  

---

Combobox (Autocomplete)

  Search
  

  
    Option 1
    Option 2
    Option 3
  

Update aria-activedescendant to the ID of the highlighted option.

---

Progress / Loading

  75%

  
  Loading...

---

Common ARIA Attributes

| Attribute | Purpose | Example | |-----------|---------|---------| | aria-label | Accessible name | aria-label="Close" | | aria-labelledby | Name from element | aria-labelledby="heading-1" | | aria-describedby | Description | aria-describedby="hint-1" | | aria-expanded | Open/closed state | aria-expanded="true" | | aria-controls | Controlled element | aria-controls="menu-1" | | aria-hidden | Hide from AT | aria-hidden="true" | | aria-live | Announce updates | aria-live="polite" | | aria-pressed | Toggle state | aria-pressed="false" | | aria-selected | Selection state | aria-selected="true" | | aria-current | Current item | aria-current="page" |

Screen Reader Only Text

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

Testing

1. Keyboard only: Tab through, use arrows, Enter, Escape
2. Screen reader: Test with VoiceOver (Mac), NVDA (Windows), or JAWS
3. Check announcements: Are labels, states, and changes announced?
4. axe DevTools: Run automated accessibility audit

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dylantarre
• Source: dylantarre/design-system-skills
• License: MIT

Install and usage instructions live in the source repository linked above.