Roles need to fit the element they are on

Rule: axe/aria-allowed-role
Checks: ARIA role should be appropriate for the element
WCAG: none; a best practice, not a WCAG success criterion
Fix class: mechanical: A fix needs no authored text or visual decision.

Who it affects

People who use a screen reader or a braille display, most of them blind.

How to fix it

An element with its own meaning acts as a control, such as `<h2 role="button">`

Nest a native control inside the element instead of overriding its role, so both meanings survive: the heading stays in the page outline and the button works with the keyboard.

<h2>
  <button type="button" aria-expanded="false" aria-controls="shipping-details">Shipping details</button>
</h2>
<div id="shipping-details" hidden>
  <p>Orders ship within two working days.</p>
</div>

A list or other structural element takes a landmark role, such as `<ul role="navigation">`

Wrap the element in the element that carries the role you want, such as <nav> around the <ul>, and leave the original element its own meaning.

<nav aria-label="Main">
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/shop">Shop</a></li>
  </ul>
</nav>

An image with alt text has `role="presentation"` or `role="none"`

Decide what the image is. If it is decorative, give it alt="" and no role. If it carries meaning, keep the alt and remove the role.

The element is hidden, so axe asks for review

The role is still not allowed; axe only cannot tell whether people will see the element. Fix the role as above, since it fails as soon as the element is shown.

Fixes that fail

Rebuilding the element as a `<div>` with the same role, such as `<div role="button">` in place of a heading

axe passes it, but the heading leaves the page outline and the <div> lacks the keyboard support a <button> brings.

Removing the role from an element that acts as a control

The rule passes, but the element is then announced by its native role, such as a heading or list item, and people cannot tell it does anything.

More on the rule

axe-core’s documentation of the rule

CORA’s fix guidance adapts content from accessibility-agents, under the MIT License: see its notice.