Skip to content
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

Jump to bottom

Add definition for implicit/explicit ARIA attributes #2154

Open
wants to merge 13 commits into
base: develop
Choose a base branch
from
Open

Add definition for implicit/explicit ARIA attributes #2154

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
593ab3d
Add definition of ARIA attribute set
Jym77 Jan 11, 2024
07a1a6e
Use new definition in required states
Jym77 Jan 11, 2024
6fe0f13
Use new definition in allowed states
Jym77 Jan 11, 2024
41324e8
Clean up links
Jym77 Jan 11, 2024
0571507
Merge branch 'develop' into implicit-explicit-states
Jan 25, 2024
b3e4099
Merge branch 'develop' into implicit-explicit-states
Jym77 Feb 1, 2024
0cf36b4
Clarify definition
Jym77 Feb 1, 2024
a18afec
Typos
Jym77 Feb 1, 2024
1e1fa47
Merge branch 'develop' into implicit-explicit-states
Jym77 Feb 29, 2024
a44c668
Fix incorrect numbering
Jym77 Feb 29, 2024
4f135b6
Streamline text
Jym77 Feb 29, 2024
1e54b3e
Merge branch 'develop' into implicit-explicit-states
Jym77 Apr 18, 2024
bb7e66b
Fix code
Jym77 Apr 18, 2024
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
14 changes: 13 additions & 1 deletion _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 @@ -36,7 +36,7 @@ acknowledgments:

## Applicability

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][].
This rule applies to any [WAI-ARIA state or property][] that is [explicitly set][aria set explicit] on an [HTML or SVG element][namespaced element] that is [included in the accessibility tree][].

## Expectation 1

Expand Down Expand Up @@ -64,6 +64,8 @@ The presence of prohibited ARIA attributes is often the result of a developer us

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).

This rule only applies to [explicitly set][aria set explicit] attributes since these have been provided by authors and using the wrong one is therefore an author issue. If an [implicitly set][aria set implicit] attribute is incorrect, this is not necessarily an author error, e.g., it can be the result of re-purposing an existing element.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would this not still be a responsibility of the author to ensure the attributes are correct? It could still lead to violations, does the ARIA state or property has valid value check for this? If so, I think we should just call that out directly.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If only it was so simple 😞

<input type="checkbox" role="button" aria-pressed="false" /> is allowed by ARIA (as far as I can tell), but has an implicit aria-checked set by checked (automagically set on <input type="checkbox" />), which is not allowed on a role of button…


Assessing the value of the attribute is out of scope for this rule.

### Related rules
Expand Down Expand Up @@ -173,6 +175,14 @@ This `input` element does not have an [explicit role][] of `textbox`, but the `a
<label>Password<input type="password" aria-required="true"/></label>
```

#### Passed Example 12
Jym77 marked this conversation as resolved.
Show resolved Hide resolved

This `button` has an [implicitly set][aria set implicit] `aria-checked` state since it uses an `input` element with a `type` [attribute value][] of `checkbox`.

```html
<input type="checkbox" role="button" />
```

### Failed

#### Failed Example 1
Expand Down Expand Up @@ -217,6 +227,8 @@ This `div` element is not [included in the accessibility tree][], hence its [WAI
<div role="button" aria-sort="" style="display:none;"></div>
```

[aria set explicit]: #aria-attribute-set:explicit 'Definition of ARIA Attribute Set Explicitly'
[aria set implicit]: #aria-attribute-set:implicit 'Definition of ARIA Attribute Set Implicitly'
[attribute value]: #attribute-value 'Definition of attribute value'
[explicit role]: #explicit-role 'Definition of Explicit Role'
[focusable]: #focusable 'Definition of focusable'
Expand Down
45 changes: 32 additions & 13 deletions _rules/role-required-states-and-properties-4e8ab6.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,13 @@ acknowledgments:

## Applicability

This rule applies to any [HTML or SVG element][] that is [included in the accessibility tree][] and has an [explicit semantic role][], except if the element has an [implicit semantic role][] that is identical to the [explicit semantic role][].
This rule applies to any [HTML or SVG element][] that is [included in the accessibility tree][].

## Expectation

For each test target, the [WAI-ARIA required states and properties][] for the role are set and not empty (`""`), unless the state or property has a default value listed under [WAI-ARIA implicit value for role][].
For each test target, the [WAI-ARIA required states and properties][] for the role are [set][aria set] and not empty (`""`).

The attributes may be [explicitly set][aria set explicit], [implicitly set][aria set implicit], or [set by default][aria set default].

## Assumptions

Expand All @@ -51,7 +53,7 @@ This rule relies on browsers and assistive technologies to support leaving out [

Omitting [WAI-ARIA required states and properties][] is often the result of a developer error. When required properties are missing and a default value is not specified by [WAI-ARIA Specifications][], the behavior is not defined. For [WAI-ARIA 1.2][], the only [explicit semantic roles][explicit semantic role] with a required property with a default value are the `option` and `tabs roles` for the `aria-selected` property.

This rule is testing author built components that specify [explicit semantic roles][explicit semantic role] and not components that keep their [implicit semantic role][]. For components that keep their [implicit semantic role][], all native HTML and SVG elements have native attributes that are mapped to all of the [WAI-ARIA required states and properties](https://www.w3.org/TR/wai-aria/#requiredState). Most of these mappings are defined in the [HTML Accessibility API Mappings, Attribute State and Property Mappings][html aam].
The way the attribute is [set][aria set] doesn't matter for this rule. As long as authors can rely on User Agents or Assistive Technologies to set the attribute, this won't create problems for users. As per the [First Rule of ARIA use][], authors should rely on [implicitly set][aria set implicit] attributes when possible.

### Bibliography

Expand Down Expand Up @@ -126,6 +128,28 @@ This `combobox` has the required properties `aria-controls` and `aria-expanded`.
</ul>
```

#### Passed Example 7
Jym77 marked this conversation as resolved.
Show resolved Hide resolved

This `checkbox` has its required `aria-checked` property [implicitly set][aria set implicit].

```html
<label>
<input type="checkbox" />
Check me
</label>
```

#### Passed Example 8

This `menuitemcheckbox` has its required `aria-checked` property [implicitly set][aria set implicit].

```html
<label>
<input type="checkbox" role="menuitemcheckbox" />
Check me
</label>
```

### Failed

#### Failed Example 1
Expand Down Expand Up @@ -205,23 +229,18 @@ This `div` does not have a [semantic role](#semantic-role).

Jym77 marked this conversation as resolved.
Show resolved Hide resolved
#### Inapplicable Example 2

This `checkbox` has an [implicit semantic role](#implicit-role) that is identical to the [explicit semantic role](#explicit-role). This allows native HTML `checked` attribute to apply.

```html
<input type="checkbox" role="checkbox" />
```

#### Inapplicable Example 3

This `combobox` is not [included in the accessibility tree][] due to its styling, hiding it from everybody.

```html
<div role="combobox" style="display:none;"></div>
```

[aria set]: #aria-attribute-set 'Definition of ARIA Attribute Set'
[aria set default]: #aria-attribute-set:default 'Definition of ARIA Attribute Set by Default'
[aria set explicit]: #aria-attribute-set:explicit 'Definition of ARIA Attribute Set Explicitly'
[aria set implicit]: #aria-attribute-set:implicit 'Definition of ARIA Attribute Set Implicitly'
[explicit semantic role]: #explicit-role 'Definition of explicit semantic role'
[html aam]: https://www.w3.org/TR/html-aam-1.0/#html-attribute-state-and-property-mappings 'Specification of HTML attributes value mapping to ARIA states and properties'
[implicit semantic role]: #implicit-role 'Definition of implicit semantic role'
[first rule of aria use]: https://www.w3.org/TR/using-aria/#rule1 'First Rule of ARIA Use'
[included in the accessibility tree]: #included-in-the-accessibility-tree 'Definition of Included in The Accessibility Tree'
[wai-aria required states and properties]: https://www.w3.org/TR/wai-aria-1.2/#requiredState
[wai-aria specifications]: #wai-aria-specifications 'Definition of WAI-ARIA Specifications'
Expand Down
30 changes: 30 additions & 0 deletions pages/glossary/aria-attribute-set.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
---
title: ARIA state or property is set
key: aria-attribute-set
unambiguous: true
objective: true
input_aspects:
- Accessibility tree
- CSS styling
- DOM tree
---

An ARIA [state][aria state] or [property][aria property] is <dfn>set</dfn> on an [HTML element][namespaced element] when it has a value. This may happen in three ways:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The term "value" brings to mind the explicit value of an attribute. What if we replace it with "when the accessibility tree exposes its value."

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This proved tricky, especially in combination of #2154 (comment) 😅

TLDR: DOM/HTML define the "value" of an attribute as the stuff written in the HTML code, which differs from our "attribute value", making everything hard to write. Here, we want to refer to the "value as written" since, presumably, the incorrect values could be dropped by parsing/validation and thus not make it to the "attribute value". Plus, as @carlosapaduarte stated, we do want rules to validate the "value as written" and thus not really bake it into this definition

Anyway, I tried to improve the situation…


- It is <dfn id="aria-attribute-set:explicit">explicitly set</dfn> if there is a corresponding `aria-*` HTML attribute on the element, whose value is valid for this ARIA [state][aria state] or [property][aria property].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"whose value is valid for this ARIA state or property"
Shouldn't this be checked by ARIA state or property has valid value?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See #2154 (comment)


For example, `aria-label` is explicitly set on `<button aria-label="Next page">Next</button>`.

- It is <dfn id="aria-attribute-set:implicit">implicitly set</dfn> if there is no corresponding `aria-*` HTML attribute on the element, but the element has an [implicit semantic role][implicit role] that has a value for this ARIA [state][aria state] or [property][aria property] defined in [HTML Attribute State and Property Mappings][aria attribute mapping].

For example, `aria-checked` is implicitly set on `<input type="checkbox" checked />`.

- It is <dfn id="aria-attribute-set:default">set by default</dfn> if there is no corresponding `aria-*` HTML attribute on the element, and the element has an [implicit semantic role][implicit role] that has a default value for this ARIA [state][aria state] or [property][aria property].
Jym77 marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is really hard to differentiate between implicitly set and set by default according to these definitions (the later is a subset of the former). Do we really need two definitions? Can we just have explicitly and implicitly set in the "Element with role attribute has required states and properties" rule?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed, definition was a bit weak. I do believe these are still different and it might be valuable to be able to speak about one or the other (maybe not immediately, though…)
I improved the definition to make the difference more obvious. It is still a bit of a weak difference (depends which specs is setting it, essentially…) 🤷


For example, `aria-expanded` is set by default on `<details><summary>Details</summary></details>`.

[aria attribute mapping]: https://www.w3.org/TR/html-aam-1.0/#html-attribute-state-and-property-mappings 'HTML Attribute State and Property Mappings'
[aria property]: https://www.w3.org/TR/wai-aria-1.2/#dfn-property 'Definition of ARIA Property'
[aria state]: https://www.w3.org/TR/wai-aria-1.2/#dfn-state 'Definition of ARIA State'
[implicit role]: #implicit-role 'Definition of Implicit Semantic Role'
[namespaced element]: #namespaced-element 'Definition of Namespaced Element'