Powered by
Names, roles & states
A Custom Role Name Sits on an Element Without a Role
The custom role name is put on a plain element that has no role, so screen readers may skip it and people don't learn what the thing is.
aria-roledescriptionWCAG 2.0Introduced in WCAG 2.0.Level AA — the minimum. Missing it blocks people outright.
- Status
- SeriousSerious — Significant friction, or information that is lost.Retiredaxe-core no longer runs this rule. Its card says why, and what still applies.
- Owner
- DesignDevTest
- Audit
- Automated+ManualA scanner finds it; a person confirms the fix.
Retired rule. Retired in axe-core: scanners no longer run this check. aria-roledescription still belongs only on an element with a meaningful role, so the advice on this card stands.
Why it matters
aria-roledescription swaps the spoken role, such as "region", for a custom name, such as "slide". It only works when the element already has a role, either built in or added with role.
On a plain div or span, screen readers may ignore it or handle it inconsistently. People who can't see the screen then miss what the thing is. Note: axe-core has deprecated this rule, but the problem is still real.
Who it affects
| Who | What they experience | Impact |
|---|---|---|
| Screen reader users | They hear the text but no role, so they can't tell it's a slide, card or other widget. | High impact |
| Low-vision users (magnification) | Affected only if they also use a screen reader, as many do. | Partial impact |
| Cognitive and neurodivergent users | Missing or mixed role names make a complex widget harder to understand. | Partial impact |
| Voice control users | They may not know what to call the thing to act on it. | Partial impact |
Business & product impact
| Area | Why | Impact |
|---|---|---|
| Legal | It fails WCAG 4.1.2 at Level A, which WCAG 2.2 Level AA includes. Complaints under Australia's Disability Discrimination Act point to WCAG, and EN 301 549 uses the same test. | High impact |
| Conversion | Carousels and drag-and-drop boards that don't make sense lose some users partway through. | Low impact |
| SEO | No real search benefit — don't sell it as one. | Low impact |
| Brand trust | Odd or missing announcements make a product feel unfinished to screen reader users. | Moderate impact |
| Cost to fix | Usually a small fix: use a proper element or add a role. Fix it once in the shared component. | High impact |
Fixing it in code
A slide in a carousel
Don't
<div aria-roledescription="slide" aria-label="1 of 4">…</div>A screen reader says: “Nothing about the slide, or behaviour varies by screen reader”
Do
<section aria-roledescription="slide" aria-label="1 of 4">…</section>A screen reader says: “1 of 4, slide”
A named section has the region role, so the custom name has a role to replace.
A card you can drag
Don't
<div tabindex="0" aria-roledescription="draggable card">Pay invoice</div>A screen reader says: “Pay invoice”
Do
<div role="button" tabindex="0" aria-roledescription="draggable card">Pay invoice</div>A screen reader says: “Pay invoice, draggable card”
Adding a real role gives the custom name something to describe.
Designer's handoff note
Only ask for a custom role name when the usual one, like "button" or "region", truly doesn't fit.
Write down the exact words to be spoken — for example, "1 of 4, slide" — and keep them short.
Quick test
Tool
VoiceOver (opens in a new tab) (on every Mac)
Duration
1 minChecklist
- Pass
- You hear the custom role name, like "1 of 4, slide".
- Fail
- You hear only the text, with no role at all.
Check these at the same time
- An ARIA attribute is used where it isn't allowed
aria-allowed-attr - An element has an ARIA role that doesn't suit it
aria-allowed-role - An ARIA label is on an element that can't have one
aria-prohibited-attr - An ARIA attribute has a value that isn't allowed
aria-valid-attr-value
What a green scan still misses
A scanner checks the element has a role. It can't tell whether the custom name is clear, needed, or hides a role people rely on, like "button".
Reference
- Status
- RetiredRetired in axe-core: scanners no longer run this check. aria-roledescription still belongs only on an element with a meaningful role, so the advice on this card stands.
- Rule ID
aria-roledescription- Raised by
- axe-core: “aria-roledescription must be on elements with a semantic role”
- WCAG
- 4.1.2 Name, Role, Value (opens in a new tab) · Level A · since WCAG 2.0
- Other standards
- EN 301 549 9.4.1.2
- Last reviewed
- 16 October 2026