A11Y Aria Patterns

ARIA Patterns

Apply ARIA roles, states, and properties correctly to enhance assistive technology support for custom widgets

When to Use

• Building custom interactive widgets that have no native HTML equivalent
• Adding accessible names or descriptions to elements
• Announcing dynamic content changes to screen readers
• Indicating expanded/collapsed, selected, or error states
• When native HTML semantics are insufficient (and only then)

Instructions

1. Follow the first rule of ARIA: do not use ARIA if native HTML works. A <button> is better than <div role="button">. A <nav> is better than <div role="navigation">. ARIA overrides semantics; native HTML provides them for free.

2. Use aria-label and aria-labelledby to provide accessible names. Every interactive element needs an accessible name — screen readers announce it.

// aria-label — inline text label (when no visible label exists)
<button aria-label="Close dialog">
  <XIcon />
</button>

// aria-labelledby — reference a visible label element
<h2 id="dialog-title">Confirm Deletion</h2>
<div role="dialog" aria-labelledby="dialog-title">

• Prefer aria-labelledby over aria-label when a visible text element exists — it avoids translation gaps.
• aria-label replaces the element's visible text for screen readers. If the button says "X", aria-label="Close" makes screen readers say "Close button."

3. Use aria-describedby for supplementary information. Unlike aria-labelledby (which names the element), aria-describedby provides additional context read after the name.

<input
  type="password"
  aria-label="Password"
  aria-describedby="password-help"
/>
<p id="password-help">Must be at least 8 characters with one number.</p>

4. Use aria-live regions to announce dynamic content. When content updates without a page reload (toast notifications, form validation, live scores), use aria-live to announce the change.

// polite — waits for the screen reader to finish current speech
<div aria-live="polite" role="status">
  {statusMessage}
</div>

// assertive — interrupts current speech (use sparingly)
<div aria-live="assertive" role="alert">
  {errorMessage}
</div>

• Render the live region in the DOM before populating it — screen readers only track changes to existing live regions.
• Use role="status" for informational updates and role="alert" for urgent errors.

5. Use state attributes to reflect widget state. Keep ARIA states synchronized with visual state.

// Expandable section
<button
  aria-expanded={isOpen}
  aria-controls="panel-1"
  => setIsOpen(!isOpen)}
>
  Settings
</button>
<div id="panel-1" hidden={!isOpen}>
  {/* panel content */}
</div>

// Toggle button
<button aria-pressed={isMuted}
  Mute
</button>

// Disabled state
<button aria-disabled={isSubmitting} ? undefined : handleSubmit}>
  Submit
</button>

6. Use aria-hidden="true" to hide decorative or redundant content from screen readers. Icons next to text labels, decorative images, and duplicate content should be hidden.

<button>
  <SearchIcon aria-hidden="true" />
  <span>Search</span>
</button>

Do not use aria-hidden="true" on focusable elements — it creates a confusing state where the element receives focus but is invisible to assistive technology.

7. Use roles for custom widgets that have no native equivalent. Common role patterns:

// Tab interface
<div role="tablist">
  <button role="tab" aria-selected={activeTab === 0} aria-controls="panel-0">Tab 1</button>
  <button role="tab" aria-selected={activeTab === 1} aria-controls="panel-1">Tab 2</button>
</div>
<div role="tabpanel" id="panel-0" aria-labelledby="tab-0">Content 1</div>

// Combobox (autocomplete)
<input role="combobox" aria-expanded={isOpen} aria-controls="listbox-1" aria-activedescendant={activeOptionId} />
<ul role="listbox" id="listbox-1">
  <li role="option" id="opt-1" aria-selected={selected === 'opt-1'}>Option 1</li>
</ul>

// Alert dialog
<div role="alertdialog" aria-labelledby="alert-title" aria-describedby="alert-desc">
  <h2 id="alert-title">Delete Account?</h2>
  <p id="alert-desc">This action cannot be undone.</p>
  <button>Cancel</button>
  <button>Delete</button>
</div>

8. Use aria-invalid and aria-errormessage for form validation errors.

<input
  aria-invalid={!!errors.email}
  aria-errormessage={errors.email ? 'email-error' : undefined}
/>;
{
  errors.email && (
    <span id="email-error" role="alert">
      {errors.email}
    </span>
  );
}

Details

ARIA categories:

• Roles: Define what an element is (e.g., tab, dialog, alert, progressbar). Set once; do not change dynamically.
• States: Dynamic boolean/tristate values that change with user interaction (e.g., aria-expanded, aria-selected, aria-pressed).
• Properties: Relatively static attributes that describe relationships or characteristics (e.g., aria-label, aria-describedby, aria-controls).

The five rules of ARIA:

1. Do not use ARIA if native HTML works.
2. Do not change native semantics (do not put role="button" on an <a>).
3. All interactive ARIA elements must be keyboard-operable.
4. Do not use role="presentation" or aria-hidden="true" on focusable elements.
5. All interactive elements must have an accessible name.

Common mistakes:

• Adding role="button" without keyboard support (Enter and Space activation)
• Using aria-label on non-interactive elements where it has no effect
• Setting aria-expanded without updating it when state changes
• Overusing aria-live="assertive" (interrupts users constantly)
• Using aria-hidden="true" on a parent containing focusable children

Testing: Use the accessibility tree in browser DevTools to verify that ARIA attributes produce the expected accessible name, role, and state.

Source

https://www.w3.org/TR/wai-aria-1.2/

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document consumed as context, but two of its assertions are also load-bearing: they are enforced mechanically by harness-accessibility via the AriaScanner in @harness-engineering/core.
  • A11Y-014 — aria-hidden="true" on a focusable element (rule #4 of ARIA: do not hide a focusable control from assistive technology).
  • A11Y-042 — positive tabindex, which disrupts the natural tab order. These fire only on statically-decidable values (a dynamic aria-hidden={expr} or a tabIndex={0}/tabIndex={-1} is never flagged), keeping false positives near zero.
• What remains advisory (not mechanized): accessible-name presence (aria-label/aria-labelledby), role-appropriate keyboard operability, live-region and state-attribute correctness. These require resolving relationships across elements or runtime state and cannot be enforced at a low false-positive rate by pattern matching, so they stay prose guidance here.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.