Element uses a deprecated ARIA role

What is this issue?

An element carries a role attribute whose value is a genuine ARIA role (one that exists in the specification and was, at some point, the correct way to express a particular semantic) but that role has since been marked deprecated, meaning newer roles or approaches have replaced it and its continued use is discouraged. role="directory" is the most common example: the specification now recommends section, list, or tree in its place, depending on what the directory content actually represents.

This is different from an invalid role. An invalid role like role="buton" never existed in the specification at all. A deprecated role like directory is a real, spec-defined role that assistive technology has historically supported; the problem is forward-looking risk, not present-tense invalidity.

Why does this matter?

Deprecation is the specification’s way of signaling that a role’s future is uncertain. Browsers and assistive technology are under no obligation to keep supporting a deprecated role indefinitely, and in practice, support for deprecated roles is already inconsistent: one screen reader might announce it correctly today while another treats it as unrecognized.

Building on a deprecated role means shipping a component whose accessibility behavior can silently degrade with a future browser or assistive technology update, with no code change on your side to explain why. A company intranet’s employee directory built with role="directory" might announce correctly in today’s most common screen reader and browser pairing while already failing in a less common one, and there’s no guarantee that gap won’t widen as vendors prioritize supporting current roles over deprecated ones.

Who is affected?

• Screen reader users: get inconsistent or unreliable announcements today, since support for a deprecated role already varies by assistive technology, with no guarantee that reliability holds in future updates either.

What users experience

Tomás uses NVDA on Windows to browse his company’s internal employee directory, a page listing every team member grouped by department, built as <ul role="directory"> years ago when that pattern was still current. NVDA in his current version announces the list correctly as a directory-style grouping, but a colleague using a different, less common screen reader on the same page reports that the entire section announces as an unstyled, ungrouped list of links with no indication it’s organized by department at all: the same markup, two different outcomes, because deprecated-role support isn’t guaranteed to be consistent across assistive technology.

How do I fix it?

Replace the deprecated role with its current, spec-recommended equivalent based on what the content structurally represents. This works because the replacement roles were specifically chosen by the specification to cover the use cases the deprecated role used to serve, so switching restores consistent, forward-compatible support across assistive technology instead of relying on a role vendors are actively phasing out.

For role="directory" specifically: use role="list" (or drop the role entirely and use a native <ul>, which already carries an implicit list role) if the content is simply a grouped collection of items; use role="tree" if the directory has genuine expandable hierarchy, like nested departments and sub-teams; or use a <section> with a heading if it’s better represented as a single labeled region of the page rather than a list at all.

Code Examples

<ul role="directory" aria-label="Team directory">
  <li><a href="/team/amy">Amy Chen, Engineering</a></li>
  <li><a href="/team/luis">Luis Ortega, Design</a></li>
</ul>

<!-- ul already carries an implicit list role - no role attribute needed -->
<ul aria-label="Team directory">
  <li><a href="/team/amy">Amy Chen, Engineering</a></li>
  <li><a href="/team/luis">Luis Ortega, Design</a></li>
</ul>

Removing role="directory" entirely, rather than replacing it with an explicit role="list", works because the <ul> element already carries an implicit list role natively, so adding an explicit role that duplicates what the element already provides is unnecessary. The aria-label stays, since it’s a valid, non-deprecated attribute on the list role either way, and it’s what actually gives the list its accessible name for screen reader users navigating by landmark or list.

Common Mistakes

Mistake: “It still works in my screen reader, so it can’t really be deprecated.” A role currently working in one screen reader doesn’t reflect the full picture: deprecated-role support is already inconsistent across assistive technology, and passing in a single manual test only confirms one specific combination happens to handle it today, not that every combination does, or will continue to.

Mistake: “I’ll wait until browsers actually drop support before I fix it.” Deprecation notices exist precisely so teams can migrate before support becomes unreliable, not after. Waiting for a visible failure means users are already experiencing the inconsistency in the meantime, on whichever assistive technology combinations already handle the deprecated role poorly.

Mistake: “Deprecated just means old-fashioned, not actually broken.” Deprecated roles aren’t a stylistic preference: the specification deprecates a role specifically because a newer role or pattern better serves the same purpose with more reliable, consistent support. Treating deprecation as cosmetic skips the actual reason the change was made.

How RedFlag Detects This

Automated: axe-core rule, runs on every scan. RedFlag calls axe-core’s aria-deprecated-role rule as part of every scan, restricted to the WCAG 2.0/2.1/2.2 A and AA rule set. The rule checks every element’s resolved role attribute value against the WAI-ARIA specification’s list of roles explicitly marked as deprecated, flagging any match regardless of what other attributes or content the element has.

False negative: the rule only flags roles the specification has formally deprecated as of the axe-core version RedFlag runs; a role deprecated in a newer spec revision than RedFlag’s bundled axe-core version won’t be caught until RedFlag updates its dependency. False positive: none typical for this check, since matching a role value against a fixed, published deprecated-roles list is a binary comparison axe-core evaluates reliably. Manual step: when replacing a deprecated role, confirm the replacement role actually matches how the content is structured and used, rather than picking the closest-sounding alternative without checking its own requirements.

Manual Testing

1. Open the page in Chrome or Firefox with NVDA or VoiceOver running.
2. Navigate to the element flagged with a deprecated role and listen to how it’s announced.
3. Compare the announcement against what the same element sounds like in a second screen reader if one is available: inconsistent announcements between the two are the clearest sign of a deprecated-role support gap.
4. Open the browser’s accessibility inspector (Chrome DevTools → Elements → Accessibility pane) and check the computed “Role” property against the WAI-ARIA specification’s current role list to confirm whether it’s still current or has been superseded.
5. After replacing the role, repeat steps 1–3 and confirm the announcement is now consistent and accurately describes the content’s structure.

Related WCAG Success Criteria

4.1.2 Name, Role, Value: Every interface component must expose a role assistive technology can reliably interpret. A deprecated role fails this criterion’s forward-looking reliability requirement even when a specific screen reader still happens to support it today, since consistent interpretation across assistive technology is the actual goal.

Related Issues

ARIA role is invalid is the more severe, adjacent failure: a role with no valid meaning at all, rather than one that’s real but phased out.

ARIA attribute is not allowed for this role and ARIA attribute is prohibited for this role commonly appear alongside a deprecated role in the same legacy component, since older ARIA patterns often combined an outdated role with attributes that don’t match its modern equivalent either.

ARIA attribute is not valid for the current role value shares the same underlying theme of a role’s requirements shifting over time as the specification has evolved.

Element role is missing required child elements is worth checking after replacing a deprecated role like directory with tree, since tree (unlike directory) has its own required child-role structure that needs to be satisfied.

References

• W3C Understanding 4.1.2: Name, Role, Value
• WAI-ARIA 1.2: Deprecated Requirements
• MDN: ARIA roles