ARIA Rule

Deprecated ARIA roles must not be used aria-deprecated-role

ARIA retires roles from time to time. A deprecated role is still in the specification so old pages do not break, but authors are told to stop using it and browsers may stop giving it any special meaning. The one most people meet is role="directory", once used for a table of contents. A plain list, usually inside a nav with a label, does the job better.

WCAG 2.2 A 4.1.2 Name, Role, Value

Websight reports this as Deprecated ARIA roles must not be used

Who it affects

Someone using a screen reader hears a role that newer screen readers no longer announce in any special way, so whatever meaning the author intended is silently gone.

Someone using an older screen reader may still hear the old role and get a different experience from everyone else, which makes the page harder to support.

The person maintaining the site inherits markup that reads as deliberate but is on a path to doing nothing.

Broken versus fixed

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

Broken

Looks like any table of contents. Older screen readers say directory, list, 3 items; newer ones have dropped the role and say list, 3 items. Two different experiences, neither adds anything.

Fixed

Announced: On this page, navigation, list, 3 items. The nav landmark is something a screen reader user can jump straight to, which directory never was.

Show the markup behind both examples
Broken
<style>body{font-family:system-ui;padding:16px;margin:0}h2{font-size:14px;margin:0 0 6px;color:#4a5568}ul{margin:0;padding-left:20px}li{margin:2px 0}a{color:#2b6cb0}</style>
<h2>On this page</h2>
<ul role="directory">
  <li><a href="#eligibility">Who can apply</a></li>
  <li><a href="#documents">What you need</a></li>
  <li><a href="#fees">Fees</a></li>
</ul>
Fixed
<style>body{font-family:system-ui;padding:16px;margin:0}h2{font-size:14px;margin:0 0 6px;color:#4a5568}ul{margin:0;padding-left:20px}li{margin:2px 0}a{color:#2b6cb0}</style>
<nav aria-labelledby="toc-h">
  <h2 id="toc-h">On this page</h2>
  <ul>
    <li><a href="#eligibility">Who can apply</a></li>
    <li><a href="#documents">What you need</a></li>
    <li><a href="#fees">Fees</a></li>
  </ul>
</nav>

Test it by hand in two minutes

  1. Search the page source for role="directory". That is the deprecated role you are most likely to find on a real site.
  2. Check the surrounding markup. If it is a list of links to sections, wrap it in a nav element with an aria-labelledby pointing at its heading.
  3. Turn on VoiceOver (Cmd+F5) or NVDA and open the landmark list (VoiceOver rotor, or NVDA's elements list with Insert+F7). The table of contents should appear as a named navigation landmark.
  4. Re-run the scan. The deprecated-role finding should be gone and no new ARIA findings should appear in its place.

The fix

Before
<ul role="directory">
  <li><a href="#fees">Fees</a></li>
</ul>
After
<nav aria-label="On this page">
  <ul>
    <li><a href="#fees">Fees</a></li>
  </ul>
</nav>

Remove the deprecated role and reach for the native element that says the same thing. For a contents list that is nav; for most other deprecated roles it is simply no role at all.

Directory role on a div

Before
<div role="directory">
  <a href="#a">Part A</a>
  <a href="#b">Part B</a>
</div>
After
<nav aria-label="Parts">
  <ul>
    <li><a href="#a">Part A</a></li>
    <li><a href="#b">Part B</a></li>
  </ul>
</nav>

A div with the role removed is just a div. Put the links in a real list so the count is announced.

Common mistakes

  • Swapping role="directory" for role="list" on a ul, which adds nothing a ul does not already say.
  • Leaving the deprecated role in because it does not seem to hurt; it already behaves differently across screen readers.
  • Replacing it with role="navigation" on the ul itself, which turns the list into a landmark and loses the list semantics.
  • Treating the warning as a reason to remove every role on the page.

WCAG criteria this rule maps to

axe-core tags this rule as WCAG 2.2 level A. It is one of the checks for:

The scanner checks each role attribute against the list of roles ARIA has deprecated, so this is a straightforward find. It cannot tell you what the author meant, so pick the replacement by reading the content. 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 roles must be valid aria-roles The role attribute only accepts names from the ARIA list: dialog, button, tab, listbox and so on. A Lists must only contain list items list A ul or ol tells a screen reader 'list, N items' and lets the person jump item by item. A Give people a way to skip past repeated navigation bypass Most pages start with the same header and menu.

Scan your own page for this and 63 other checks

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.