Accessibility Rule: aria-roledescription must be on elements with a semantic role

About This Accessibility Rule

Why This Matters

The aria-roledescription attribute lets authors provide a human-readable, localized description of an element’s role. For example, you might use it to describe a role="slider" as “priority picker” so a screen reader announces something more meaningful to the user. However, this attribute only works when the element already has a role that assistive technologies can identify.

When aria-roledescription is placed on an element with no semantic role — like a plain <div>, <span>, or <p> — there is no role for the description to refine. This creates a confusing situation where assistive technologies may announce a description with no context, announce nothing at all, or behave unpredictably. In some cases, this can break accessibility for entire sections of an application.

This issue primarily affects blind users, deafblind users, and users with mobility impairments who rely on screen readers or other assistive technologies to understand and navigate page content. When role information is nonsensical or missing, these users lose the ability to understand what a UI element is and how to interact with it.

Related WCAG Success Criteria

This rule relates to WCAG Success Criterion 4.1.2: Name, Role, Value (Level A), which requires that for all user interface components, the name, role, and value can be programmatically determined. When aria-roledescription is applied to an element without a semantic role, the role cannot be properly communicated, violating this criterion.

This applies across WCAG 2.0, 2.1, and 2.2 at Level A, as well as EN 301 549 guideline 9.4.1.2.

How the Rule Works

The axe rule aria-roledescription checks every element that has an aria-roledescription attribute and verifies that the element also has a semantic role. There are three possible outcomes:

Fail: The element has no role at all (e.g., <div>, <span>, <p> without an explicit role attribute). These elements have a generic or no implicit role, so aria-roledescription has nothing to describe.
Pass: The element has a well-supported implicit role (like <button>, <img>, <nav>) or an explicit role (like role="combobox").
Incomplete (needs review): The element has a role that may not be widely supported by assistive technologies (e.g., role="rowgroup"). These need manual testing to verify they work correctly.

How to Fix It

Identify elements flagged by the rule — they have aria-roledescription but no semantic role.
Decide if the element truly needs aria-roledescription. In many cases, the solution is simply to remove it.
If the description is needed, either:
- Use a semantic HTML element that carries an implicit role (e.g., replace <div> with <button>).
- Add an explicit role attribute to the element so the description has context.
Ensure the aria-roledescription value meaningfully refines the role — it should describe a more specific version of what the element is, not contradict it.

Examples

Incorrect: `aria-roledescription` on elements with no semantic role

These elements have no implicit or explicit role, so aria-roledescription has nothing to describe.

<p aria-roledescription="my paragraph">
  This is some text.
</p>

<div aria-roledescription="my container">
  Some content here.
</div>

<span aria-roledescription="my label">Name</span>

A <p> has no corresponding ARIA role, and a plain <div> or <span> maps to no role (or the generic generic role). Screen readers cannot use the description meaningfully.

Correct: `aria-roledescription` on elements with an implicit role

These HTML elements carry built-in semantic roles, so the description refines something real.

<img
  aria-roledescription="illustration"
  src="diagram.png"
  alt="System architecture overview" />

<button aria-roledescription="play control">
  Play
</button>

The <img> element has an implicit role of img, and <button> has an implicit role of button. The aria-roledescription values provide more specific descriptions of these roles.

Correct: `aria-roledescription` on elements with an explicit role

<div
  role="combobox"
  aria-roledescription="city picker"
  aria-expanded="false"
  aria-haspopup="listbox">
  Select a city
</div>

<div
  role="slider"
  aria-roledescription="priority selector"
  aria-valuenow="3"
  aria-valuemin="1"
  aria-valuemax="5"
  tabindex="0">
</div>

The explicit role attribute provides the semantic foundation, and aria-roledescription adds a more user-friendly label for what that role represents in this specific context.

Incorrect fix: Adding a mismatched role just to satisfy the rule

Don’t add a role that doesn’t match the element’s actual behavior just to pass the check.

<!-- Don't do this -->

<p role="button" aria-roledescription="my paragraph">
  This is some text.
</p>

If the element is just a paragraph of text, remove aria-roledescription entirely rather than adding an incorrect role.

Needs review: `aria-roledescription` on elements with limited role support

Some roles have inconsistent assistive technology support. These will be flagged as needing manual review.

<h1 aria-roledescription="page title">Welcome</h1>

<div role="rowgroup" aria-roledescription="data section">
<!-- row content -->

</div>

The heading role and rowgroup role may not consistently support aria-roledescription across all screen readers. Test these cases manually with actual assistive technologies to confirm the description is announced correctly.

Learn more: