English
Site menu

aria-prohibited-attr

ARIA naming attributes must not be used on roles that prohibit them

automaticWCAG 4.1.2 (A)confidence: highseverity: moderaterobust

Checks that aria-label/aria-labelledby are not present on WAI-ARIA roles whose specification explicitly prohibits ARIA naming (e.g. generic, emphasis, strong, paragraph).

Applies to. Applies to (a) elements whose explicit, valid role is one of the ARIA 1.2 roles with a documented "Prohibited ARIA States and Properties" list for naming attributes (pure text-semantics / non-naming structural roles: caption, code, deletion, emphasis, generic, insertion, mark, none, paragraph, presentation, strong, subscript, suggestion, superscript, time), plus a native <caption> with no valid explicit role, whose implicit role is caption, and (b) elements with no role at all: native HTML tags verified to carry no implicit role (such as <div>, <span>, <p>, <strong>, <em>, <code> and <time>), or any autonomous custom element (a hyphenated, author-defined tag per the Custom Elements spec). In both cases, only elements that also carry aria-label or aria-labelledby. A custom element whose ElementInternals give it a role (this.attachInternals().role) is judged by that role, its default role: one of the roles above puts it in (a), any other keeps it out of (b).

Expectation. Prohibited attributes must not be present on (a); for (b), the naming attribute is at best unreliable (nothing accessible-name-aware to hang it off) and at worst silently ignored by assistive technology. A roleless element whose own content already gives it a name is reported as CANTTELL, since the attribute may be a deliberate override; one with no other source for a name FAILs. The same holds for (a): an element whose own text already names it loses nothing WCAG requires for certain when the prohibited label is ignored, so the WAI-ARIA violation is reported at CANTTELL (ACT kb1m8s maps it to WAI-ARIA, with SC 1.3.1 only as a secondary requirement); without such text it FAILs. A role description on generic or on an element with no role refines no control, so it is a WAI-ARIA violation reported at CANTTELL whatever the content.

What a finding reports.

  • attr: the naming attribute found, aria-label or aria-labelledby.
  • role: the role that prohibits it; null on an element with no role.

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

pass
<div role="generic"></div>

role="generic" cannot be named, and none of the naming attributes are present.

fail
<div role="generic" aria-label="Something"></div>

aria-label is set on a role that WAI-ARIA prohibits from being named.

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_ATTR_PROHIBITED

  1. Inspect the element the report names and note the attribute, its value and the element's role.
  2. For a label, compare it with the element's visible text and check whether it says anything the text does not.
  3. If it does, check whether that information is given another way a screen reader also reads, such as a header or text next to the element.

Pass. The visible text already says everything the label says, or the attribute is a role description, which refines no control. Still remove it: WAI-ARIA prohibits it on this role.

Fail. The label carries information given nowhere else, which is lost because the role cannot be named (WCAG 4.1.2).

ARIA_ATTR_PROHIBITED_ROLELESS

  1. Inspect the element the report names, which has no role, and note its aria-roledescription or aria-brailleroledescription.
  2. Check whether the element works as a control: it takes focus or responds to clicks or keys.
  3. If it does, check whether it has a role that says what kind of control it is.

Pass. The element is not a control, so the role description describes nothing a user operates. Still remove it: WAI-ARIA prohibits it without a role.

Fail. The element works as a control but has no role, so what kind of control it is is not exposed (WCAG 4.1.2).

ARIA_ATTR_PROHIBITED_ROLELESS_NEEDS_REVIEW

  1. Inspect the element the report names and note its aria-label or aria-labelledby text and its visible text.
  2. Compare the two: check whether the label says anything the visible text does not.
  3. If it does, check whether that information is given another way that a screen reader also reads, such as a table header above the cell or text next to the element.
  4. With a screen reader, read the element in browse mode and note whether the label is announced or ignored.

Pass. The visible text, or text a screen reader reads with it such as its table header, already says everything the label says, so nothing is lost if the label is ignored.

Fail. The label carries information given nowhere else (such as "Price in euros" on "12" with no header saying so), which is lost because naming is not supported on an element with no role (WCAG 4.1.2, ACT kb1m8s).

View source