Ensure aria-roledescription is only used on elements with an implicit or explicit role

The aria-roledescription attribute allows authors to override or refine the accessible description of an element’s role. This rule ensures it is only used on elements that have a valid, implicit, or explicit ARIA role.

What is being tested?

The test checks if aria-roledescription is applied only to elements that already have a valid role—either explicitly set or implicitly provided by the HTML element.

Why it matters

Using aria-roledescription incorrectly (for example, on elements with no role) can confuse assistive technologies like screen readers, causing misleading or broken announcements. This can negatively impact the user experience for people relying on accessibility tools.

How to fix the problem

• Use aria-roledescription only on elements with a valid ARIA role.
• Check if the element has an implicit role (for example, <button> has role="button").
• If adding aria-roledescription to a generic element (like <div>), first assign an explicit role (like role="combobox").

Examples

✅ Passing examples

<img aria-roledescription="my img" src="foo.png" />
<button aria-roledescription="my button">button</button>
<div role="combobox" aria-roledescription="my combobox"></div>

❌ Failing examples

<p aria-roledescription="my paragraph">paragraph</p>
<div aria-roledescription="my div">div</div>

⚠️ Incomplete examples

<h1 aria-roledescription="my heading">heading</h1>
<div role="rowgroup" aria-roledescription="my row"></div>

Best practices

• Refer to the ARIA in HTML conformance requirements to know which roles and attributes are valid for each element.
• Do not use aria-roledescription as a replacement for proper ARIA roles or native HTML semantics.