# aria-roledescription must be on elements with a semantic role

> Canonical HTML version: https://rocketvalidator.com/accessibility-validation/axe/4.11/aria-roledescription
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

## 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

1. **Identify elements** flagged by the rule — they have `aria-roledescription` but no semantic role.
2. **Decide if the element truly needs `aria-roledescription`**. In many cases, the solution is simply to remove it.
3. 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.
4. 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.

```html
<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.

```html
<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

```html
<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.

```html
<!-- 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.

```html
<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.