Use aria-roledescription only when an explicit role exists
Accessibility isn’t only about avoiding violations — it’s about ensuring your product can be used confidently by everyone. This guide explains the principle of this rule, shows what goes wrong in real-world code, and provides a verified fix that meets WCAG and the European Accessibility Act (EAA).
Why this matters and how to fix it
Why this matters
aria-roledescription allows developers to customize how a role is announced, but applying it without a base role removes semantic clarity. Screen readers may skip or misinterpret the element, reducing both accessibility and predictability for users.
How to fix this issue
Ensure any element using aria-roledescription also defines a valid role attribute. Keep custom descriptions short and clear—use them only to provide meaningful alternative phrasing for established roles, not to invent new semantics.
Developer guidance
Developers often misuse aria-roledescription when trying to simplify announcements. Enforce internal guidelines limiting its use to components with well-defined base roles. Add review steps to confirm that every aria-roledescription is paired with a recognized role and tested across assistive technologies.
Code examples
Incorrect Implementation
<div aria-roledescription="button"></div>Correct Implementation
<div role="button" aria-roledescription="custom button"></div>
Trusted by organizations across Europe working toward WCAG and EAA conformance