aria-roles-valid
role attribute must be a valid, non-abstract ARIA role
Checks that an explicit role="" attribute resolves to a real, non-abstract WAI-ARIA role.
Applies to. Applies to any element with a non-empty role="" attribute in the composed DOM.
Expectation. At least one role token names a concrete, non-abstract ARIA role. Graded by what the element falls back to when none does:
- FAIL on a roleless host (div, span, custom element) that takes focus, which is left exposed as generic: a control whose role is not programmatically determinable (SC 4.1.2, F59).
- CANTTELL on a roleless host that takes no focus. The WAI-ARIA violation is certain, but whether losing the role the author meant fails a criterion depends on the page:
<div role="heding">fails SC 1.3.1 only if it is shown as a heading. ACT 674b10 maps the rule to no WCAG requirement for conformance. - CANTTELL where the element has a native role (a <button>, <nav>, <a href>), which the accessibility tree keeps using. ACT 674b10 lists 4.1.2 as a secondary requirement only, "satisfied through the implicit role," so the bad token is worth reporting but is not itself the criterion failing.
What a finding reports.
role: the first token of the role attribute. No token in it is a known role, or the known ones are all abstract.nativeRole(the CANTTELL case): the element's native role, which assistive technology keeps using.
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
<div role="button">Click</div>
"button" is a real, concrete ARIA role.
<div role="buton" tabindex="0">Save</div>
"buton" isn't a defined ARIA role token (typo), so a control that takes focus is left with no role.
<div role="heding">Orders</div>
"heding" isn't a defined ARIA role token either, but the element takes no focus: whether losing the heading role fails WCAG depends on whether the page shows it as a heading.
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_ABSTRACT
- Inspect the element the report names and note the abstract role (such as landmark, widget, command) and its tag.
- Open the Accessibility pane in the browser's developer tools and check the role exposed instead (the native role).
- Decide whether the native role is a concrete kind of the abstract role named (a nav for landmark, a button for widget).
Pass. The native role is a concrete form of what the author named, so the element is still exposed correctly (still remove the abstract role).
Fail. The native role does not match the intent (such as a button marked landmark), so the meant role is never exposed, which fails WCAG 4.1.2 (ACT 674b10).
ARIA_ROLE_INVALID
- Inspect the element the report names and note the unknown role value and its tag.
- Work out which role was probably meant (for example "buton" for button).
- Open the Accessibility pane in the browser's developer tools and check the role that is exposed instead (the element's native role).
- Compare the exposed role with the intended one and with how the element behaves.
Pass. The exposed native role is the one that was meant, so users get the right role (still correct the typo).
Fail. The intended role differs from the exposed one, so users get the wrong role, which fails WCAG 4.1.2 (ACT 674b10).