a11y-aria-patterns

ARIA Patterns and Authoring Practices

Skill type: Reference. This is teaching/pattern content — it explains the WAI-ARIA APG keyboard contracts and ARIA state rules for custom widgets. It is not a scanner. For static review of existing ARIA usage, use /a11y-review. For runtime verification of ARIA validity against resolved roles, use the a11y-testing skill to set up real axe.

ARIA (Accessible Rich Internet Applications) extends HTML semantics for custom, dynamic UI components. It supplements — never replaces — native HTML.

The ARIA First Principles:

1. No ARIA is better than bad ARIA. Incorrect ARIA is worse than no ARIA.
2. Native HTML first. Use a <button> before role="button". Use <select> before a custom combobox.
3. You own the keyboard. Using an ARIA widget role means you are fully responsible for its keyboard behavior per the APG spec.
4. Keep states synchronized. Every ARIA state attribute must reflect the current UI state — never hardcode them.

---

ARIA Fundamentals

How ARIA Works

ARIA adds three things to elements in the accessibility tree:

• Roles — what the element is (role="dialog", role="tab")
• Properties — static characteristics (aria-label, aria-required)
• States — dynamic, changing values (aria-expanded, aria-checked, aria-invalid)

Accessible Names (WCAG 4.1.2)

Every interactive element needs an accessible name. The browser computes it in this priority order:

1. aria-labelledby (references another element's text — highest priority)
2. aria-label (inline text string)
3. Native label element (<label for="id">)
4. Element's own text content (for buttons and links)
5. title attribute (last resort — inconsistent screen reader support)

<!-- Priority 1: aria-labelledby -->
<h2 id="section-title">Billing Address</h2>
<section aria-labelledby="section-title">...</section>

<!-- Priority 2: aria-label (when no visible text exists) -->
<button aria-label="Close dialog">
  <svg aria-hidden="true">...</svg>
</button>

<!-- Priority 3: Associated label -->
<label for="card-number">Card Number</label>
<input id="card-number" type="text">

<!-- Priority 4: Button text -->
<button>Submit Order</button>