Skip to content

Split ARIA props not prohibited from ARIA props permitted #2342

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 3 commits into
base: develop
Choose a base branch
from
Draft

Split ARIA props not prohibited from ARIA props permitted #2342

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0917f78
Split ARIA props not prohibited from ARIA props permitted
WilcoFiers Jul 31, 2025
3bae854
update examples
WilcoFiers Jul 31, 2025
431b7cf
cleanup
WilcoFiers Aug 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 173 additions & 0 deletions _rules/aria-global-property-not-prohibited-kb1m8s.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
---
id: kb1m8s
name: ARIA global properties not used where prohibited
rules_format: 1.1
rule_type: atomic
description: |
This rule checks that global WAI-ARIA properties are not on elements whose role prohibits them.
accessibility_requirements:
aria12:prohibitedattributes:
title: ARIA 1.2, 5.2.5 Prohibited States and Properties
forConformance: true
failed: not satisfied
passed: satisfied
inapplicable: satisfied
wcag-technique:ARIA5: # Using WAI-ARIA state and property attributes to expose the state of a user interface component
forConformance: false
failed: not satisfied
passed: further testing needed
inapplicable: further testing needed
wcag20:1.3.1: # Info and Relationships (A)
secondary: This success criterion is **less strict** than this rule. This is because the rule does not ignore irrelevant ARIA properties. Some of the failed examples satisfy this success criterion.
wcag20:4.1.2: # Name, Role, Value (A)
secondary: This success criterion is **less strict** than this rule. This is because the rule does not ignore irrelevant ARIA properties. Some of the failed examples satisfy this success criterion.
input_aspects:
- Accessibility Tree
- CSS styling
- DOM Tree
acknowledgments:
authors:
- Wilco Fiers
previous_authors:
- Anne Thyme Nørregaard
- Jean-Yves Moyen
assets:
- JFK's "We Choose the Moon" speech excerpt is courtesy of NASA.
---

## Applicability

This rule applies to any [WAI-ARIA global state or property][global] that is specified on an [HTML or SVG element][namespaced element] that is [included in the accessibility tree][].

## Expectation

No test target is [prohibited][] on the [semantic role][] of the element on which it is specified.

## Background

The presence of prohibited ARIA attributes is often the result of a developer using an incorrect role, or a misunderstanding of the attribute. These attributes are ignored by browsers and other assistive technologies. This often means that a state or property which should exist is missing.

In HTML, there are language features that do not have corresponding implicit WAI-ARIA semantics. As per [ARIA in HTML](https://www.w3.org/TR/html-aria/), those elements can have [global states or properties][global]. Some of those elements can also have [inherited][], [supported][], or [required][] [states][state] or [properties][property] that correspond to a [WAI-ARIA role](https://www.w3.org/TR/wai-aria-1.2/#introroles). For example, the `audio` element has no corresponding ARIA semantics but it can have [inherited][], [supported][], or [required][] [states][state] or [properties][property] of the [`application` role](https://www.w3.org/TR/wai-aria-1.2/#application).

### Assumptions

There are no assumptions.

### Accessibility Support

Implementation of [Presentational Roles Conflict Resolution][] varies from one browser or assistive technology to another. Depending on this, some elements can have a [semantic role][] of `none` and their attributes fail this rule with some technologies but users of other technology would not experience any accessibility issue.

### Related rules

- [ARIA state or property is permitted](https://www.w3.org/WAI/standards-guidelines/act/rules/5c01ea/)
- [ARIA state or property has valid value](https://www.w3.org/WAI/standards-guidelines/act/rules/6a7281/)

### Bibliography

- [Understanding Success Criterion 1.3.1: Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html)
- [Understanding Success Criterion 4.1.2: Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html)
- [WAI-ARIA 1.2, Prohibited States and Properties](https://www.w3.org/TR/wai-aria/#prohibitedattributes)
- [WAI-ARIA 1.2, Global States and Properties](https://www.w3.org/TR/wai-aria-1.2/#global_states)
- [ARIA5: Using WAI-ARIA state and property attributes to expose the state of a user interface component](https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA5)

## Test Cases

### Passed

#### Passed Example 1

This generic `div` element is allowed the global `aria-live` property.

```html
<div aria-live="polite">I like Bananas</div>
```

#### Passed Example 2

This `button` element allowed the `aria-label` property.

```html
<button aria-label="I like bananas">
🧑 ❤️ 🍌🍌
</button>
```

#### Passed Example 3

This `div` element allowed the `aria-braillelabel` property because its [explicit role][] of `heading` does not prohibit this.

```html
<div role="heading" aria-braillelabel="I like bananas">
I ❤️ Bananas
</div>
```

### Failed

#### Failed Example 1

The `aria-label` property is [prohibited][] for an element with a `generic` role.

```html
<div aria-label="Bananas">🍌</div>
```

#### Failed Example 2

The `aria-labelledby` property is [prohibited][] for an element with a `paragraph` role.

```html
<h1 id="bananas">I like bananas</h1>
<p aria-labelledby="Bananas">🧑 ❤️ 🍌🍌</p>
```

#### Failed Example 3

The `aria-braillelabel` property is [prohibited][] for an element with a `paragraph` role.

```html
<p aria-braillelabel="I love Bananas">I ❤️ Bananas</p>
```

#### Failed Example 4

The `aria-roledescription` property is [prohibited][] for an element with a `generic` role.

```html
<div aria-roledescription="Banana text">I like bananas</div>
```

#### Failed Example 5

The `aria-brailleroledescription` property is [prohibited][] for an element with a `none` role.

```html
<h1 role="none" aria-brailleroledescription="Banana text">I like bananas</h1>
```

### Inapplicable

#### Inapplicable Example 1

The generic `div` element is hidden.

```html
<div aria-label="Bananas" hidden></div>
```

[attribute value]: #attribute-value 'Definition of attribute value'
[explicit role]: #explicit-role 'Definition of Explicit Role'
[focusable]: #focusable 'Definition of focusable'
[global]: https://www.w3.org/TR/wai-aria-1.2/#global_states 'Definition of Global ARIA States and Properties'
[implicit role]: #implicit-role 'Definition of Implicit Role'
[included in the accessibility tree]: #included-in-the-accessibility-tree 'Definition of Included in the Accessibility Tree'
[inherited]: https://www.w3.org/TR/wai-aria-1.2/#inheritedattributes 'Definition of Inherited ARIA States and Properties'
[presentational roles conflict resolution]: https://www.w3.org/TR/wai-aria-1.2/#conflict_resolution_presentation_none 'Presentational Roles Conflict Resolution'
[property]: https://www.w3.org/TR/wai-aria-1.2/#dfn-property 'Definition of ARIA Property'
[required]: https://www.w3.org/TR/wai-aria-1.2/#requiredState 'Definition of Required ARIA States and Properties'
[semantic role]: #semantic-role 'Definition of Semantic Role'
[state]: https://www.w3.org/TR/wai-aria-1.2/#dfn-state 'Definition of ARIA State'
[supported]: https://www.w3.org/TR/wai-aria-1.2/#supportedState 'Definition of Supported ARIA States and Properties'
[wai-aria state or property]: https://www.w3.org/TR/wai-aria-1.2/#state_prop_def 'Definition of ARIA States and Properties'
[namespaced element]: #namespaced-element
[prohibited]: https://www.w3.org/TR/wai-aria-1.2/#prohibitedattributes 'WAI-ARIA 1.2 Definition of Prohibited States and Properties'
33 changes: 9 additions & 24 deletions _rules/aria-state-or-property-permitted-5c01ea.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,18 +39,14 @@ acknowledgments:

This rule applies to any [WAI-ARIA state or property][] that is specified on an [HTML or SVG element][namespaced element] that is [included in the accessibility tree][].

## Expectation 1
## Expectation

For each test target, one of the following is true:

- **global**: the test target is a [global state or property][global]; or
- **semantic role**: the test target is an [inherited][], [supported][], or [required][] [state][] or [property][] of the [semantic role][] of the element on which the test target is specified; or
- **language feature**: the test target is specified on an [HTML element][namespaced element] and is allowed on that element. Which ARIA states or properties may be used on which element is described in [ARIA in HTML](https://w3c.github.io/html-aria/).

## Expectation 2

No test target is [prohibited][] on the [semantic role][] of the element on which it is specified.

## Background

The presence of prohibited ARIA attributes is often the result of a developer using an incorrect role, or a misunderstanding of the attribute. These attributes are ignored by browsers and other assistive technologies. This often means that a state or property which should exist is missing.
Expand All @@ -69,6 +65,7 @@ Implementation of [Presentational Roles Conflict Resolution][] varies from one b

### Related rules

- [ARIA global properties not used where prohibited](https://www.w3.org/WAI/standards-guidelines/act/rules/kb1m8s/)
- [ARIA state or property has valid value](https://www.w3.org/WAI/standards-guidelines/act/rules/6a7281/)

### Bibliography
Expand Down Expand Up @@ -181,8 +178,13 @@ This `div` element has an [explicit role][] of `switch`; the `aria-required` [pr
```html
<div role="switch" aria-checked="false" tabindex="0" aria-required="true">
<span class="label">Notifications</span>
<span class="switch" style="position: relative; display: inline-block; top: 6px; border: 2px solid black; border-radius: 12px; height: 20px; width: 40px;">
<span style="position: absolute; top: 2px; left: 2px; display: inline-block; border: 2px solid black; border-radius: 8px; height: 12px; width: 12px; background: black;"></span>
<span
class="switch"
style="position: relative; display: inline-block; top: 6px; border: 2px solid black; border-radius: 12px; height: 20px; width: 40px;"
>
<span
style="position: absolute; top: 2px; left: 2px; display: inline-block; border: 2px solid black; border-radius: 8px; height: 12px; width: 12px; background: black;"
></span>
</span>
<span class="on" aria-hidden="true" style="display: none;">On</span>
<span class="off" aria-hidden="true">Off</span>
Expand Down Expand Up @@ -215,22 +217,6 @@ The `aria-orientation` property may not be used on `audio` element, nor can it b
<audio src="/test-assets/moon-audio/moon-speech.mp3" controls aria-orientation="horizontal"></audio>
```

#### Failed Example 3

The `aria-label` property is [prohibited][] for an element with a `generic` role.

```html
<div aria-label="Bananas"></div>
```

#### Failed Example 4

The `aria-label` property is [prohibited][] for an element with a `paragraph` role.

```html
<div role="paragraph" aria-label="Bananas"></div>
```

### Inapplicable

#### Inapplicable Example 1
Expand Down Expand Up @@ -264,4 +250,3 @@ This `div` element is not [included in the accessibility tree][], hence its [WAI
[supported]: https://www.w3.org/TR/wai-aria-1.2/#supportedState 'Definition of Supported ARIA States and Properties'
[wai-aria state or property]: https://www.w3.org/TR/wai-aria-1.2/#state_prop_def 'Definition of ARIA States and Properties'
[namespaced element]: #namespaced-element
[prohibited]: https://www.w3.org/TR/wai-aria-1.2/#prohibitedattributes 'WAI-ARIA 1.2 Definition of Prohibited States and Properties'
Loading