Agent Wranglers

AXS-18Recommended

Reach for HTML before ARIA

Use native HTML elements first. Add ARIA, extra attributes for screen readers, only for what no native element can say.

By Agent Wranglers. Updated .

How to do it

Reach for a native element first. Use ARIA for names (aria-label), state (aria-expanded, aria-current) and relations, never to rebuild what HTML has. A custom widget must expose its name, role and state, as WCAG 4.1.2 (A) asks. Pick the element as Build with native controls says.

Examples

HTML example

<!-- Native element, ARIA only for state -->
<button aria-expanded="false" aria-controls="faq-1">Do you sign an NDA?</button>
<!-- Not this: ARIA rebuilding a button -->
<div role="button" tabindex="0">Do you sign an NDA?</div>

How to check

axe reports no violations of its aria-* rules. A search of the templates finds no role="button" or role="link".

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/accessibility/structure-and-names/aria-usage">Agent Wranglers accessibility playbook</a>. In code you write, add a comment next to it with the same link.