aria-deprecated-role
role attribute should not use a deprecated or author-discouraged ARIA role
Checks that an explicit role="" attribute does not use a role deprecated by the WAI-ARIA specification, or one reserved for user-agent-internal use (e.g. role="generic").
Applies to. Applies to any element whose role attribute's first (used) token is a valid, non-abstract ARIA role that authors should not explicitly declare, either because WAI-ARIA has deprecated it (e.g. "directory", superseded by role="list") or because it is reserved for user-agent- internal use (role="generic", which ARIA 1.2 §5.4 says authors SHOULD NOT use in content).
Expectation. The role in use is neither deprecated nor reserved. Graded by the strength of the rule ARIA states:
- CANTTELL at SHOULD NOT, which leaves the usage conforming, so the author decides whether it matters: a deprecated role ("directory") or one reserved for user agents ("generic").
- FAIL at MUST NOT. No ARIA 1.2 or 1.3 role carries an author MUST NOT outside the abstract roles, so this outcome is reserved for a later revision promoting a role to that strength.
Distinct, atomic decision from aria-roles-valid (existence/ abstractness): a role can be valid and non-abstract while still being discouraged in explicit author use.
What a finding reports.
role: the deprecated or reserved role in use.guidance: advice on what to use instead, as English text.
These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.
Examples
<ul role="list"><li>Item</li></ul>
role="list" is current, non-deprecated ARIA.
<div role="directory"><a href="/a">Item</a></div>
role="directory" is deprecated in WAI-ARIA in favor of role="list"; still valid markup, but discouraged.
How to check
When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.
ARIA_ROLE_AUTHOR_DISCOURAGED
- Inspect the element the report names and note its tag and role="generic".
- If the tag is a plain container (div, span, b, i), the role changes nothing; remove it as cleanup.
- Otherwise open the Accessibility pane in the browser's developer tools and check whether the element's native meaning (button, link, heading, list item, navigation) has been lost.
- With a screen reader, move to the element and, if it is focusable, press Tab to it and listen to what is announced.
Pass. The element was already a generic container, or its native role still shows and is announced.
Fail. role="generic" strips a native meaning, such as a link or heading no longer announced as one, which fails WCAG 4.1.2 (and 1.3.1 for structure).
ARIA_ROLE_DEPRECATED
- Inspect the element the report names and note its deprecated role (such as directory).
- Open the Accessibility pane in the browser's developer tools and check which role is exposed (directory is usually mapped to list).
- With a screen reader, move to the element and its items and listen for the structure being announced.
- Consider the suggested replacement role (list for directory) and whether it fits.
Pass. The structure is announced correctly (for example as a list with its item count), or the role is replaced with the suggested one.
Fail. The structure is not conveyed by assistive technology because it relies on the deprecated role, which can fail WCAG 4.1.2.