Deprecated ARIA roles must not be used

Elements must not use deprecated ARIA roles or abstract roles

Do not assign deprecated or abstract WAI-ARIA roles to any element.

Deprecated roles and abstract roles are not exposed correctly to assistive technologies, which leads to missing or misleading semantics for screen reader users.

This often appears in custom widgets or templates copied from outdated examples and impacts users who rely on accurate role announcements.

Why It Matters

Assistive technologies map roles to the accessibility tree. If a role is deprecated or abstract, it may be ignored or misinterpreted. Users can miss structure, landmarks, or widget type.

Incorrect roles disrupt expected keyboard patterns and screen reader output, increasing cognitive load and navigation errors.

This relates to WCAG 2.2 success criteria such as 4.1.2 (Name, Role, Value) because the intended role is not reliably conveyed.

Common Causes

• Using outdated snippets that include deprecated roles (for example, directory).
• Typing a role that looks plausible but is abstract (e.g., command, composite, input, widget).
• Adding roles where native HTML already provides the correct semantics.
• Copying roles from design systems without checking current ARIA specifications.
• Typos or non-standard role names that are silently ignored by user agents.

How to Fix

1. Audit all role attributes
   • Search the codebase for role="".
   • List each unique value used.
2. Verify against current specifications
   • Check each role against the latest WAI-ARIA spec (1.2 or later) or MDN.
   • Confirm the role is valid and not deprecated or abstract.
3. Prefer native HTML
   • Remove the role if a native element already communicates the correct semantics (e.g., use button, nav, header, footer, ul/li).
4. Replace deprecated roles
   • Example: If role="directory" is used, replace it with appropriate semantics such as section plus a list, or a tree if it’s hierarchical.
   • If no direct replacement exists, restructure with native elements and complementary roles.
5. Avoid abstract roles
   • Never use abstract roles (e.g., roletype, command, composite, input, landmark, range, section, sectionhead, select, structure, widget, window) in markup; they are only for defining role taxonomy.
6. Complete role patterns correctly
   • When you must use ARIA roles, ensure required states/properties and proper child roles per the ARIA spec and the ARIA Authoring Practices.
7. Enforce with tooling
   • Add linters and automated tests (e.g., axe, eslint plugins) and include role validation in CI.

Recommendation: When uncertain, remove the incorrect role and rely on semantic HTML until the correct role pattern is confirmed.

How to Test

Keyboard check

• Navigate components that previously relied on ARIA roles.
• Ensure focus order, keyboard interaction, and visible focus remain intact after changes.

Screen reader check

• With NVDA/JAWS/VoiceOver, navigate to the component and listen for the announced role.
• Confirm the role matches the intended widget or landmark and that required states/properties are conveyed.

DevTools accessibility tree

• Inspect the element in browser DevTools.
• Verify the computed role is valid and not “generic” or missing due to an invalid/abstract role.

Mobile/touch check

• With VoiceOver (iOS) or TalkBack (Android), explore the component.
• Confirm the control is announced with the correct role and is operable via touch gestures.

Simple checklist

• No element uses a deprecated role.
• No element uses an abstract role.
• Native semantics are used whenever possible.
• Custom widgets use valid roles with required states/properties.
• The accessibility tree shows the intended roles across browsers/AT.

Good Example

<section aria-labelledby="contacts-title">
  <h2 id="contacts-title">Team Contacts</h2>
  <ul>
    <li>Alex Rivera — Support</li>
    <li>Casey Lin — Sales</li>
    <li>Mina Patel — Engineering</li>
  </ul>
</section>

Bad Example

<div role="directory">
  <div>Alex Rivera — Support</div>
  <div>Casey Lin — Sales</div>
  <div>Mina Patel — Engineering</div>
</div>

<!-- Abstract role misuse -->
<button role="command">Save</button>

Quick Checklist

• No deprecated roles (e.g., directory) appear in code.
• No abstract roles are used in markup.
• Prefer semantic HTML over ARIA where possible.
• If ARIA is required, use current, valid roles only.
• Supply required states/properties and child roles for each used role.
• Verify roles via the accessibility tree in multiple browsers.
• Confirm correct announcements with at least one desktop and one mobile screen reader.