New rule: role is permitted #2084
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,253 @@ | ||||||
| --- | ||||||
| id: j7zzqr | ||||||
| name: ARIA role is permitted for the element. | ||||||
| rule_type: atomic | ||||||
| description: | | ||||||
| This rule checks that explicit WAI-ARIA roles are allowed for the element they are specified on. | ||||||
| accessibility_requirements: | ||||||
| html-aria:docconformance: | ||||||
| title: ARIA in HTML, 4. Document conformance requirements for use of ARIA attributes in HTML | ||||||
| forConformance: true | ||||||
| failed: not satisfied | ||||||
| passed: satisfied | ||||||
| inapplicable: satisfied | ||||||
| input_aspects: | ||||||
| - Accessibility Tree | ||||||
| - DOM Tree | ||||||
| acknowledgments: | ||||||
| authors: | ||||||
| - Jean-Yves Moyen | ||||||
| --- | ||||||
|
|
||||||
| ## Applicability | ||||||
|
|
||||||
| This rule applies to any [HTML element][namespaced element] which has an [explicit semantic role][explicit role] and is not [programmatically hidden][]. | ||||||
|
|
||||||
| ## Expectation | ||||||
|
|
||||||
| For each test target, its [explicit semantic role][explicit role] is allowed on this element, according to the [ARIA in HTML specification][aria in html document conformance]. | ||||||
|
|
||||||
| ## Assumptions | ||||||
|
|
||||||
| There are no assumptions. | ||||||
|
|
||||||
| ## Accessibility Support | ||||||
|
|
||||||
| There are no accessibility support issues known. | ||||||
|
|
||||||
| ## Background | ||||||
|
|
||||||
| Each element also has an [implicit semantic role][implicit role] defined in the [HTML Accessibility API Mappings][html aam:roles]. Setting the [explicit role][] as the same as the [implicit role][] is not recommended but nonetheless allowed. This rule does not check that scenario. | ||||||
|
|
||||||
| This rule does not check specifically whether the [explicit role][] is deprecated, or whether it is the special `generic` role that should not be used by authors. These are not conformance requirement, or are checked by other rules. | ||||||
|
There was a problem hiding this comment.
Suggested change
are deprecated features surfaced by other rule(s)? If so, can there be a link to that? |
||||||
|
|
||||||
| This rule only checks for elements that are not [programmatically hidden][]. Elements that are [programmatically hidden][], e.g. due to a CSS `display:none`, must still have valid roles in order to conform to [ARIA in HTML][aria in html document conformance]. However, as long as the elements with the errant roles remain programmatically hidden, they are not expected to cause accessibility issues. This rule only checks a snapshot of a page in a given state; if interacting with the page programmatically exposes an element with an errant role that this rule previously ignored, the new state of the page should be reevaluated to ensure it still passes this rule, and that an accessibility issue has not been introduced to users. Examples only show [programmatically hidden][] elements with a correct role. | ||||||
|
|
||||||
| ### Related rules | ||||||
|
|
||||||
| - [Role attribute has valid value](https://www.w3.org/WAI/standards-guidelines/act/rules/674b10/proposed/) checks that the value of the `role` attribute exists in ARIA, while this rule checks that it is allowed on the element using it. | ||||||
|
|
||||||
| ### Bibliography | ||||||
|
|
||||||
| - [Document conformance requirements for use of ARIA attributes in HTML](https://www.w3.org/TR/html-aria/#docconformance) | ||||||
|
|
||||||
| ## Test Cases | ||||||
|
|
||||||
| ### Passed | ||||||
|
|
||||||
| #### Passed Example 1 | ||||||
|
|
||||||
| This `a` element with an `href` attribute has an [explicit role][] of `button`, which is allowed. | ||||||
|
There was a problem hiding this comment. I think these descriptions would read better if we flip the role and element around:
Suggested change
|
||||||
|
|
||||||
| ```html | ||||||
| <a href="https://www.w3.org/WAI/standards-guidelines/act/rules/" role="button">All ACT rules</a> | ||||||
| ``` | ||||||
|
|
||||||
| #### Passed Example 2 | ||||||
|
|
||||||
| This `h1` element has an [explicit role][] of `tab`, which is allowed. The `div` element also has an allowed role (of `tablist`). | ||||||
|
|
||||||
| ```html | ||||||
| <div role="tablist"> | ||||||
| <h1 role="tab">ACT rules</h1> | ||||||
| </div> | ||||||
| ``` | ||||||
|
|
||||||
| #### Passed Example 3 | ||||||
|
|
||||||
| These `hr` elements have an [explicit role][] of `presentation`, which is allowed. | ||||||
|
|
||||||
| ```html | ||||||
| Fruits: | ||||||
| <ul> | ||||||
| <li> | ||||||
| Apple | ||||||
| <hr role="presentation" /> | ||||||
| </li> | ||||||
| <li> | ||||||
| Banana | ||||||
| <hr role="presentation" /> | ||||||
| </li> | ||||||
| <li>Orange</li> | ||||||
| </ul> | ||||||
| ``` | ||||||
|
|
||||||
| #### Passed Example 4 | ||||||
|
|
||||||
| This `p` element has an [explicit role][] of `generic` which is allowed. Using an explicit role of `generic` for any element is globally not recommended, but not an error by itself. | ||||||
|
|
||||||
| ```html | ||||||
| <p role="generic">It was a dark and stormy night.</p> | ||||||
| ``` | ||||||
|
|
||||||
| #### Passed Example 5 | ||||||
|
|
||||||
| These `hr` elements have an [explicit role][] of `separator`, which is allowed. Using an explicit role which is the same as the [implicit role][] is not recommended, but not an error by itself. | ||||||
|
|
||||||
| ```html | ||||||
| Fruits: | ||||||
| <ul> | ||||||
| <li> | ||||||
| Apple | ||||||
| <hr role="separator" /> | ||||||
| </li> | ||||||
| <li> | ||||||
| Banana | ||||||
| <hr role="separator" /> | ||||||
| </li> | ||||||
| <li>Orange</li> | ||||||
| </ul> | ||||||
| ``` | ||||||
|
|
||||||
| #### Passed Example 6 | ||||||
|
|
||||||
| This `h1` element has an [explicit role][] of `tab`, which is allowed. The `btn` token is not a valid role and is therefore ignored. | ||||||
|
|
||||||
| ```html | ||||||
| <div role="tablist"> | ||||||
| <h1 role="btn tab">ACT rules</h1> | ||||||
| </div> | ||||||
| ``` | ||||||
|
|
||||||
| #### Passed Example 7 | ||||||
|
|
||||||
| This `dialog` element has an [explicit role][] of `alertdialog`, which is allowed. Even though the `alert` role is not allowed, the first token is a valid role and is therefore used. | ||||||
|
|
||||||
| ```html | ||||||
| <dialog role="alertdialog alert">This is not right.</dialog> | ||||||
|
There was a problem hiding this comment. I'm not 100% sure about this one. The requirement for it is this:
That to me reads that fallback roles apply here too. I don't know that I would want them too. That feels a little on the strict side, but it might be good to put something in the background section about fallback roles, and straight up invalid or abstract roles being out of scope for this rule, even if they do seem like they'd fail the requirement. |
||||||
| ``` | ||||||
|
|
||||||
| ### Failed | ||||||
Jym77 marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| #### Failed Example 1 | ||||||
|
|
||||||
| This `button` element has an [explicit role][] of `heading`, which is not allowed. | ||||||
|
|
||||||
| ```html | ||||||
| <button role="heading">ACT rules</button> | ||||||
| ``` | ||||||
|
|
||||||
| #### Failed Example 2 | ||||||
|
|
||||||
| This `aside` element has an [explicit role][] of `navigation`, which is not allowed. | ||||||
|
|
||||||
| ```html | ||||||
| <aside role="navigation"> | ||||||
| <a href="https://www.w3.org">W3C</a> <a href="https://www.w3.org/TR/WCAG21/">WCAG 2.1</a> | ||||||
| <a href="https://www.w3.org/WAI/standards-guidelines/act/rules/"> ACT rules</a> | ||||||
| </aside> | ||||||
| ``` | ||||||
|
|
||||||
| #### Failed Example 3 | ||||||
|
|
||||||
| These `h1` elements have an [explicit role][] of `listitem`, which is not allowed; the `div` element has an [explicit role][] of `list`, which is allowed. | ||||||
|
|
||||||
| ```html | ||||||
| Fruits: | ||||||
| <div role="list"> | ||||||
| <h1 role="listitem">Apple</h1> | ||||||
| <h1 role="listitem">Banana</h1> | ||||||
| <h1 role="listitem">Orange</h1> | ||||||
| </div> | ||||||
| ``` | ||||||
|
|
||||||
| #### Failed Example 4 | ||||||
|
|
||||||
| This `a` element with an `href` attribute has an [explicit role][] of `presentation`, which is not allowed. Note that since the element is focusable, the [presentational roles conflict resolution][] would trigger, and the explicit role is ignored. | ||||||
|
|
||||||
| ```html | ||||||
| <a href="https://www.w3.org/WAI/standards-guidelines/act/rules/" role="presentation">All ACT rules</a> | ||||||
| ``` | ||||||
|
|
||||||
| #### Failed Example 5 | ||||||
|
|
||||||
| The first `li` element has an [explicit role][] of `presentation`, which is not allowed when its parent has an [implicit role][] of `list`. | ||||||
|
|
||||||
| ```html | ||||||
| Fruits: | ||||||
| <ul> | ||||||
| <li role="presentation">Apple</li> | ||||||
| <li>Banana</li> | ||||||
| <li>Orange</li> | ||||||
| </ul> | ||||||
| ``` | ||||||
|
|
||||||
| #### Failed Example 6 | ||||||
|
|
||||||
| This `label` element has an [explicit role][] of `generic`, which is not allowed. | ||||||
|
|
||||||
| ```html | ||||||
| <label role="generic"> Name: <input /> </label> | ||||||
|
There was a problem hiding this comment. ARIA is a little vague on whether generic elements are supposed to be in the accessibility tree. I think the applicability as you have it now probably means this passes. My suggested update to it should solve that. There was a problem hiding this comment. 'passes' though a should not from aria. i think aria in html's rules for label are a bit too strict here. i'm going to make an issue to address this. There was a problem hiding this comment. I understood the point of this example to be that generic is a user-agent assigned role, but not one that you are allowed to explicitly specify. Now that I think about it though, that may be more appropriate for https://www.w3.org/WAI/standards-guidelines/act/rules/674b10/proposed/ |
||||||
| ``` | ||||||
|
|
||||||
| #### Failed Example 7 | ||||||
|
|
||||||
| This `dialog` element has an [explicit role][] of `alert`, which is not allowed. Even though the `alertdialog` role is allowed, the first token is a valid role and is therefore used. | ||||||
|
|
||||||
| ```html | ||||||
| <dialog role="alert alertdialog">This is not right.</dialog> | ||||||
| ``` | ||||||
|
|
||||||
| ### Inapplicable | ||||||
|
|
||||||
| #### Inapplicable Example 1 | ||||||
|
|
||||||
| There is no [HTML element][namespaced element]. | ||||||
|
|
||||||
| ```svg | ||||||
| <svg xmlns="http://www.w3.org/2000/svg"> | ||||||
| <title>This is an SVG</title> | ||||||
| </svg> | ||||||
| ``` | ||||||
|
|
||||||
| #### Inapplicable Example 2 | ||||||
|
|
||||||
| This `a` element does not have an [explicit semantic role][]:. | ||||||
|
|
||||||
| ```html | ||||||
| <a href="https://www.w3.org/WAI/standards-guidelines/act/rules/">All ACT rules</a> | ||||||
| ``` | ||||||
|
|
||||||
| #### Inapplicable Example 3 | ||||||
|
|
||||||
| This `button` element is [programmatically hidden][]. | ||||||
|
|
||||||
| ```html | ||||||
| <button role="link" style="display:none;">Click me</button> | ||||||
| ``` | ||||||
|
|
||||||
| #### Inapplicable Example 4 | ||||||
|
|
||||||
| This `h1` element is [programmatically hidden][]. | ||||||
|
|
||||||
| ```html | ||||||
| <h1 role="heading" aria-hidden="true">ACT rules</h1> | ||||||
| ``` | ||||||
|
|
||||||
| [aria in html document conformance]: https://www.w3.org/TR/html-aria/#docconformance 'ARIA in HTML, Document conformance requirements for use of ARIA attributes in HTML' | ||||||
| [explicit role]: #explicit-role 'Definition of Explicit Role' | ||||||
| [html aam:roles]: https://www.w3.org/TR/html-aam-1.0/#html-element-role-mappings 'HTML Accessibility API Mappings, Element Role Mappings' | ||||||
| [implicit role]: #implicit-role 'Definition of Implicit Role' | ||||||
| [namespaced element]: #namespaced-element 'Definition of Namespaced Element' | ||||||
| [presentational roles conflict resolution]: https://www.w3.org/TR/wai-aria-1.2/#conflict_resolution_presentation_none 'Presentational Roles Conflict Resolution in ARIA 1.2' | ||||||
| [programmatically hidden]: #programmatically-hidden 'Definition of Programmatically Hidden' | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sorry, this is going to be very nit picky.
I don't think the way you're interpreting this requirement is right. Or quite possibly, I think the requirement is written incorrectly. MAY in RFC2119 speak does not create a prohibitive statement. You can use these roles on those elements, and browsers have to support it when you do. But that's not the same as saying authors are not allowed to use other roles. It would have to be something like "if an author specifies a role it MUST be one from the third column."
I think this is a solid rule, and we should definitely have it, but I'm a little reluctant to say this is a conformance requirement for ARIA in HTML. Even if that was the intended meaning, that's not what it says. I don't really want to hold this rule up over a technicality like this, but I do think something needs to be done about this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@WilcoFiers the sentence you quote needs to be put into the context of section 1 Author requirements fo ruse of ARIA in HTML
per section 1, it's an Authors MUST NOT - where the Author MAYs specificy what it allowed.
if you think this is unclear because one has to piece together these different parts of the specification, then that's fair. The spec can be updated to restate the author requirements more overtly in tandem with the text you quoted.