ARIA Rule

aria-roledescription must only be used on elements with a role aria-roledescription

aria-roledescription lets you swap the word a screen reader uses for a role: say slide instead of group, or page instead of tab panel. It only works on an element that has a role, either from the role attribute or from the element itself. On a bare div it is ignored. Use it sparingly, with plain words a person would recognise, because it also hides the standard role that people have learnt.

WCAG 2.2 A 4.1.2 Name, Role, Value

Websight does not run this check. axe-core marks the aria-roledescription rule as deprecated, and rules with that tag are skipped when scanning by WCAG level. Other tools may still report it as aria-roledescription must be on elements with a semantic role. Test it by hand using the steps below.

Who it affects

Someone using a screen reader arrows into a carousel and hears the text of each slide with nothing to say it is a slide, or where one slide ends and the next begins.

Someone using a screen reader in another language hears your custom word in English even on a translated page, because aria-roledescription is not translated by the screen reader.

Someone who has learnt what group and region mean loses that known word if you replace it with jargon like tile or card-item.

Broken versus fixed

Both examples are live and rendered in a sandboxed frame. The broken one is deliberately broken.

Broken

Looks like a slide. A screen reader reads it as plain text: Free delivery over forty pounds, heading, On every order this month. Neither slide nor 1 of 3 is spoken, because a div with no role has no role to describe or name.

Fixed

Announced: 1 of 3, slide, then the content. role="group" gives the element a role, and aria-roledescription swaps the word group for slide.

Show the markup behind both examples
Broken
<style>body{font-family:system-ui;padding:16px;margin:0}.slide{width:260px;padding:14px;border:1px solid #cbd5e0;border-radius:8px;background:#f7fafc}.slide h3{margin:0 0 6px;font-size:16px}.dots{margin-top:8px;color:#a0aec0;font-size:12px}</style>
<div class="slide" aria-roledescription="slide" aria-label="1 of 3">
  <h3>Free delivery over &pound;40</h3>
  <p>On every order this month.</p>
</div>
<div class="dots">&#9679; &#9675; &#9675;</div>
Fixed
<style>body{font-family:system-ui;padding:16px;margin:0}.slide{width:260px;padding:14px;border:1px solid #cbd5e0;border-radius:8px;background:#f7fafc}.slide h3{margin:0 0 6px;font-size:16px}.dots{margin-top:8px;color:#a0aec0;font-size:12px}</style>
<div class="slide" role="group" aria-roledescription="slide" aria-label="1 of 3">
  <h3>Free delivery over &pound;40</h3>
  <p>On every order this month.</p>
</div>
<div class="dots">&#9679; &#9675; &#9675;</div>

Test it by hand in two minutes

  1. Search the page source for aria-roledescription. Check each element that has it also has a role attribute, or is an element with a built-in role such as button, nav or section with a name.
  2. Read the value aloud. If it is not a word an ordinary person would understand (slide, yes; cmp-tile, no), change it or remove it.
  3. Turn on VoiceOver (Cmd+F5) or NVDA and move to the element. You should hear your word in place of the role, and the element's name alongside it.
  4. If the site is translated, check the roledescription is translated with the rest of the page. Screen readers will not translate it for you.

The fix

Before
<div aria-roledescription="slide" aria-label="1 of 3">...</div>
After
<div role="group" aria-roledescription="slide" aria-label="1 of 3">...</div>

Add a sensible role (group is the usual one for a slide or a card) and keep the description short. If you cannot think of a role that fits, the description probably is not needed either.

Custom word on a plain button

Before
<button aria-roledescription="action chip">Filter: in stock</button>
After
<button>Filter: in stock</button>

A button has a role, so this is allowed, but the custom word hides the word button that everyone knows. Remove it unless it genuinely helps.

Common mistakes

  • Using aria-roledescription instead of a role, as if it created one.
  • Writing internal component names (hero-card, mat-chip) that mean nothing to a listener.
  • Describing a role as something interactive, like button, on an element that cannot be pressed.
  • Adding it to every element in a design system by default.
  • Leaving the English word in place on pages in other languages.

WCAG criteria this rule maps to

axe-core tags this rule as WCAG 2.2 level A. It is a check (not run by Websight) for:

The scanner can see aria-roledescription on an element that has no explicit or implicit role. It cannot judge whether the word you chose is useful, and recent versions of axe have retired this check as a default rule, so it may not appear in every scan. Automated tools find only part of the accessibility problems on a page; a pass on this rule is not a pass on the criterion.

A aria-braillelabel must have a matching text label aria-braille-equivalent aria-braillelabel and aria-brailleroledescription let you give a braille display a shorter or contracted version of a control's name or role. A ARIA roles must be valid aria-roles The role attribute only accepts names from the ARIA list: dialog, button, tab, listbox and so on. A ARIA attributes must be allowed for the element's role aria-allowed-attr Every ARIA role comes with a short list of attributes it understands.

Scan your own page for the 64 checks Websight does run

Open any page in Chrome, click Websight, and get a score out of 100 with every issue explained and a draft fix snippet per element.

Add Websight to Chrome

Free scans, no account, nothing leaves your computer. Automated tools find only part of the problems; the extension says so on every report.