Use aria-roledescription only when an explicit role exists and semantics remain intact
Content available in English only.
Accessibility isn’t just about avoiding violations — it’s about ensuring that everyone can use your product with confidence. This guide explains each rule’s intent, highlights common issues, and shows how to fix them according to WCAG and the European Accessibility Act (EAA).
These guidelines do not replace the official WCAG standards. They’re concise, developer-focused notes to help you identify and fix issues effectively.
`aria-roledescription` is for clarification, never to replace a role.
Why this matters and how to fix it
Why this matters
`aria-roledescription` customizes how an element's role is announced, but does not replace underlying semantics. Using it without a valid role or with misleading descriptions can confuse users and make controls unpredictable.
How to fix this issue
Use `aria-roledescription` only on elements with a valid semantic role. Provide descriptions that clarify meaning without obscuring function. Do not invent roles or replace standard control names. For semantics changes, use the correct role or native element.
Developer guidance
`aria-roledescription` support is inconsistent across screen readers. Limit its use to justified cases with domain-specific terminology. Test with NVDA + Firefox and VoiceOver + Safari to ensure correct spoken output.
Code examples
Incorrect Implementation
<div aria-roledescription="button"></div>Correct Implementation
<div role="button" aria-roledescription="custom button"></div>Real-World Examples
Before
<span aria-roledescription="switch"></span> <!-- No role; screen reader may misannounce or ignore -->After
<span role="switch" aria-roledescription="toggle switch"></span> <!-- Screen reader announces role and custom description clearly -->Manual testing
- 1. Inspect elements using `aria-roledescription`.
- 2. Confirm the element has a valid base role.
- 3. Verify the description clarifies meaning without hiding the role.
- 4. Test with NVDA + Firefox and VoiceOver + Safari to ensure proper announcements.
- 5. Remove or correct `aria-roledescription` if it misrepresents the element's function.
Trusted by organizations across Europe working toward WCAG and EAA conformance