Skip to content

Commit 3c49c9a

Browse files
author
Diane Ko
committedJun 27, 2020
Add WCAG guidelines to rule documentation
Adds in a section for every rule that specifies what the WCAG guidelines are (if applicable) in a new Accessibility guidelines section near the bottom of the rule documentation. Additional changes: - Move Resources/References underneath Accessibility guidelines section - Fix up heading level of Resources so that the heading order progresses sequentially - Fix up resource link text to be clearer - Fix up some broken links or old references - Update pronoun usage in `accessible-emoji` to use they instead of he/she - Add some additional examples and rule clarity to `click-events-have-key-events` - Fix up code formatting for `tabindex-no-positive` - Add additional resources to some rules without resources - Change Resources from ordered list to unordered list since the order really doesn't matter Partially addresses #30
·
v6.10.2v6.4.0
1 parent 7a34e45 commit 3c49c9a

36 files changed

+248
-129
lines changed
 

Diff for: ‎docs/rules/accessible-emoji.md

+7-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
11
# [Deprecated] accessible-emoji
22

3-
Emoji have become a common way of communicating content to the end user. To a person using a screenreader, however, he/she may not be aware that this content is there at all. By wrapping the emoji in a `<span>`, giving it the `role="img"`, and providing a useful description in `aria-label`, the screenreader will treat the emoji as an image in the accessibility tree with an accessible name for the end user.
4-
5-
#### Resources
6-
1. [Léonie Watson](http://tink.uk/accessible-emoji/)
3+
Emoji have become a common way of communicating content to the end user. To a person using a screenreader, however, they may not be aware that this content is there at all. By wrapping the emoji in a `<span>`, giving it the `role="img"`, and providing a useful description in `aria-label`, the screenreader will treat the emoji as an image in the accessibility tree with an accessible name for the end user.
74

85
## Rule details
96

@@ -21,3 +18,9 @@ This rule takes no arguments.
2118
<span>🐼</span>
2219
<i role="img" aria-label="Panda">🐼</i>
2320
```
21+
22+
## Accessibility guidelines
23+
- [WCAG 1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)
24+
25+
### Resources
26+
- [Léonie Watson, Accessible Emoji](http://tink.uk/accessible-emoji/)

Diff for: ‎docs/rules/alt-text.md

+9-6
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,6 @@
22

33
Enforce that all elements that require alternative text have meaningful information to relay back to the end user. This is a critical component of accessibility for screenreader users in order for them to understand the content's purpose on the page. By default, this rule checks for alternative text on the following elements: `<img>`, `<area>`, `<input type="image">`, and `<object>`.
44

5-
#### Resources
6-
1. [axe-core, object-alt](https://dequeuniversity.com/rules/axe/3.2/object-alt)
7-
2. [axe-core, image-alt](https://dequeuniversity.com/rules/axe/3.2/image-alt)
8-
3. [axe-core, input-image-alt](https://dequeuniversity.com/rules/axe/3.2/input-image-alt)
9-
4. [axe-core, area-alt](https://dequeuniversity.com/rules/axe/3.2/area-alt)
10-
115
## How to resolve
126
### `<img>`
137
An `<img>` must have the `alt` prop set with meaningful text or as an empty string to indicate that it is an image for decoration.
@@ -141,3 +135,12 @@ function Foo(props) {
141135

142136
<input type="image" {...props} />
143137
```
138+
139+
## Accessibility guidelines
140+
- [WCAG 1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)
141+
142+
### Resources
143+
- [axe-core, object-alt](https://dequeuniversity.com/rules/axe/3.2/object-alt)
144+
- [axe-core, image-alt](https://dequeuniversity.com/rules/axe/3.2/image-alt)
145+
- [axe-core, input-image-alt](https://dequeuniversity.com/rules/axe/3.2/input-image-alt)
146+
- [axe-core, area-alt](https://dequeuniversity.com/rules/axe/3.2/area-alt)

Diff for: ‎docs/rules/anchor-has-content.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@
22

33
Enforce that anchors have content and that the content is accessible to screen readers. Accessible means that it is not hidden using the `aria-hidden` prop. Refer to the references to learn about why this is important.
44

5-
#### References
6-
1. [axe-core, link-name](https://dequeuniversity.com/rules/axe/3.2/link-name)
7-
85
## Rule details
96

107
This rule takes one optional object argument of type object:
@@ -51,3 +48,9 @@ return (
5148
<a />
5249
<a><TextWrapper aria-hidden /></a>
5350
```
51+
## Accessibility guidelines
52+
- [WCAG 2.4.4](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context)
53+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
54+
55+
### Resources
56+
- [axe-core, link-name](https://dequeuniversity.com/rules/axe/3.2/link-name)

Diff for: ‎docs/rules/anchor-is-valid.md

+9-7
Original file line numberDiff line numberDiff line change
@@ -128,12 +128,6 @@ This button element can now also be used inline in text.
128128

129129
Once again we stress that this is an inferior implementation and some users will encounter difficulty to use your website, however, it will allow a larger group of people to interact with your website than the alternative of ignoring the rule's warning.
130130

131-
132-
### References
133-
1. [WebAIM - Introduction to Links and Hypertext](http://webaim.org/techniques/hypertext/)
134-
1. [Links vs. Buttons in Modern Web Applications](https://marcysutton.com/links-vs-buttons-in-modern-web-applications/)
135-
1. [Using ARIA - Notes on ARIA use in HTML](https://www.w3.org/TR/using-aria/#NOTES)
136-
137131
## Rule details
138132

139133
This rule takes one optional object argument of type object:
@@ -221,4 +215,12 @@ Invalid `href` attribute:
221215
<a href="javascript:void(0)" />
222216
<a href={"javascript:void(0)"} />
223217
<a href={`javascript:void(0)`} />
224-
```
218+
```
219+
220+
## Accessibility guidelines
221+
- [WCAG 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard)
222+
223+
### Resources
224+
- [WebAIM - Introduction to Links and Hypertext](http://webaim.org/techniques/hypertext/)
225+
- [Links vs. Buttons in Modern Web Applications](https://marcysutton.com/links-vs-buttons-in-modern-web-applications/)
226+
- [Using ARIA - Notes on ARIA use in HTML](https://www.w3.org/TR/using-aria/#NOTES)

Diff for: ‎docs/rules/aria-activedescendant-has-tabindex.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,6 @@ Because an element with `aria-activedescendant` must be tabbable, it must either
1414
have an inherent `tabIndex` of zero or declare a `tabIndex` of zero with the `tabIndex`
1515
attribute.
1616

17-
#### References
18-
1. [MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-activedescendant_attribute)
19-
2017
## Rule details
2118

2219
This rule takes no arguments.
@@ -44,3 +41,9 @@ This rule takes no arguments.
4441
<div aria-activedescendant={someID} tabIndex="-1" />
4542
<input aria-activedescendant={someID} tabIndex={-1} />
4643
```
44+
45+
## Accessibility guidelines
46+
General best practice (reference resources)
47+
48+
### Resources
49+
- [MDN, Using the aria-activedescendant attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-activedescendant_attribute)

Diff for: ‎docs/rules/aria-props.md

+3
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,6 @@ This rule takes no arguments.
2020
<div id="address_label">Enter your address</div>
2121
<input aria-labeledby="address_label">
2222
```
23+
24+
## Accessibility guidelines
25+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)

Diff for: ‎docs/rules/aria-proptypes.md

+6-4
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,6 @@
22

33
ARIA state and property values must be valid.
44

5-
#### References
6-
1. [Spec](https://www.w3.org/TR/wai-aria/#states_and_properties)
7-
2. [AX_ARIA_04](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_04)
8-
95
## Rule details
106

117
This rule takes no arguments.
@@ -22,3 +18,9 @@ This rule takes no arguments.
2218
<span aria-hidden="yes">foo</span>
2319
```
2420

21+
## Accessibility guidelines
22+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
23+
24+
### Resources
25+
- [ARIA Spec, States and Properties](https://www.w3.org/TR/wai-aria/#states_and_properties)
26+
- [Chrome Audit Rules, AX_ARIA_04](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_04)

Diff for: ‎docs/rules/aria-role.md

+7-3
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@
22

33
Elements with ARIA roles must use a valid, non-abstract ARIA role. A reference to role definitions can be found at [WAI-ARIA](https://www.w3.org/TR/wai-aria/#role_definitions) site.
44

5-
[AX_ARIA_01](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_01)
6-
[DPUB-ARIA roles](https://www.w3.org/TR/dpub-aria-1.0/)
7-
85
## Rule details
96

107
This rule takes one optional object argument of type object:
@@ -37,3 +34,10 @@ For the `ignoreNonDOM` option, this determines if developer created components a
3734
<div role=""></div> <!-- Bad: An empty ARIA role is not allowed -->
3835
<Foo role={role}></Foo> <!-- Bad: ignoreNonDOM is set to false or not set -->
3936
```
37+
38+
## Accessibility guidelines
39+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
40+
41+
### Resources
42+
- [Chrome Audit Rules, AX_ARIA_01](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_01)
43+
- [DPUB-ARIA roles](https://www.w3.org/TR/dpub-aria-1.0/)

Diff for: ‎docs/rules/aria-unsupported-elements.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@
22

33
Certain reserved DOM elements do not support ARIA roles, states and properties. This is often because they are not visible, for example `meta`, `html`, `script`, `style`. This rule enforces that these DOM elements do not contain the `role` and/or `aria-*` props.
44

5-
#### References
6-
1. [AX_ARIA_12](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_12)
7-
85
## Rule details
96

107
This rule takes no arguments.
@@ -21,3 +18,9 @@ This rule takes no arguments.
2118
<meta charset="UTF-8" aria-hidden="false" />
2219
```
2320

21+
## Accessibility guidelines
22+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
23+
24+
### Resources
25+
- [Chrome Audit Rules, AX_ARIA_12](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_12)
26+
- [DPUB-ARIA roles](https://www.w3.org/TR/dpub-aria-1.0/)

Diff for: ‎docs/rules/autocomplete-valid.md

+8-5
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,6 @@
22

33
Ensure the autocomplete attribute is correct and suitable for the form field it is used with.
44

5-
#### References
6-
1. [axe-core, autocomplete-valid](https://dequeuniversity.com/rules/axe/3.2/autocomplete-valid)
7-
2. [HTML 5.2, Autocomplete requirements](https://www.w3.org/TR/html52/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute)
8-
95
## Rule details
106

117
This rule takes one optional object argument of type object:
@@ -39,4 +35,11 @@ This rule takes one optional object argument of type object:
3935

4036
<!-- Bad: MyInput is listed in inputComponents -->
4137
<MyInput autocomplete="incorrect" />
42-
```
38+
```
39+
40+
## Accessibility guidelines
41+
- [WCAG 1.3.5](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose)
42+
43+
### Resources
44+
- [axe-core, autocomplete-valid](https://dequeuniversity.com/rules/axe/3.2/autocomplete-valid)
45+
- [HTML 5.2, Autocomplete requirements](https://www.w3.org/TR/html52/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute)

Diff for: ‎docs/rules/click-events-have-key-events.md

+6-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# click-events-have-key-events
22

3-
Enforce `onClick` is accompanied by at least one of the following: `onKeyUp`, `onKeyDown`, `onKeyPress`. Coding for the keyboard is important for users with physical disabilities who cannot use a mouse, AT compatibility, and screenreader users.
3+
Enforce `onClick` is accompanied by at least one of the following: `onKeyUp`, `onKeyDown`, `onKeyPress`. Coding for the keyboard is important for users with physical disabilities who cannot use a mouse, AT compatibility, and screenreader users. This does not apply for interactive or hidden elements.
44

55
## Rule details
66

@@ -11,9 +11,14 @@ This rule takes no arguments.
1111
<div onClick={() => {}} onKeyDown={this.handleKeyDown} />
1212
<div onClick={() => {}} onKeyUp={this.handleKeyUp} />
1313
<div onClick={() => {}} onKeyPress={this.handleKeyPress} />
14+
<button onClick={() => {}} />
15+
<div onClick{() => {}} aria-hidden="true" />
1416
```
1517

1618
### Fail
1719
```jsx
1820
<div onClick={() => {}} />
1921
```
22+
23+
## Accessibility guidelines
24+
- [WCAG 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard)

Diff for: ‎docs/rules/control-has-associated-label.md

+5
Original file line numberDiff line numberDiff line change
@@ -102,3 +102,8 @@ This rule takes one optional object argument of type object:
102102
```jsx
103103
<button type="button" class="icon-save" />
104104
```
105+
106+
## Accessibility guidelines
107+
- [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)
108+
- [WCAG 3.3.2](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions)
109+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)

Diff for: ‎docs/rules/heading-has-content.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@
22

33
Enforce that heading elements (`h1`, `h2`, etc.) have content and that the content is accessible to screen readers. Accessible means that it is not hidden using the `aria-hidden` prop. Refer to the references to learn about why this is important.
44

5-
#### References
6-
1. [axe-core, empty-heading](https://dequeuniversity.com/rules/axe/3.2/empty-heading)
7-
85
## Rule details
96

107
This rule takes one optional object argument of type object:
@@ -58,3 +55,9 @@ function Foo(props) {
5855
<h1 />
5956
<h1><TextWrapper aria-hidden />
6057
```
58+
59+
## Accessibility guidelines
60+
- [WCAG 2.4.6](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-descriptive.html)
61+
62+
### Resources
63+
- [axe-core, empty-heading](https://dequeuniversity.com/rules/axe/3.2/empty-heading)

Diff for: ‎docs/rules/html-has-lang.md

+7-4
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,6 @@
22

33
<html> elements must have the lang prop.
44

5-
#### References
6-
1. [axe-core, html-has-lang](https://dequeuniversity.com/rules/axe/3.2/html-has-lang)
7-
1. [axe-core, html-lang-valid](https://dequeuniversity.com/rules/axe/3.2/html-lang-valid)
8-
95
## Rule details
106

117
This rule takes no arguments.
@@ -22,3 +18,10 @@ This rule takes no arguments.
2218
```jsx
2319
<html>
2420
```
21+
22+
## Accessibility guidelines
23+
- [WCAG 3.1.1](https://www.w3.org/WAI/WCAG21/Understanding/language-of-page)
24+
25+
### Resources
26+
- [axe-core, html-has-lang](https://dequeuniversity.com/rules/axe/3.2/html-has-lang)
27+
- [axe-core, html-lang-valid](https://dequeuniversity.com/rules/axe/3.2/html-lang-valid)

Diff for: ‎docs/rules/iframe-has-title.md

+7-3
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@
22

33
`<iframe>` elements must have a unique title property to indicate its content to the user.
44

5-
#### References
6-
1. [axe-core, frame-title](https://dequeuniversity.com/rules/axe/3.2/frame-title)
7-
85
## Rule details
96

107
This rule takes no arguments.
@@ -27,3 +24,10 @@ This rule takes no arguments.
2724
<iframe title={true} />
2825
<iframe title={42} />
2926
```
27+
28+
## Accessibility guidelines
29+
- [WCAG 2.4.1](https://www.w3.org/WAI/WCAG21/Understanding/bypass-blocks)
30+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
31+
32+
### Resources
33+
- [axe-core, frame-title](https://dequeuniversity.com/rules/axe/3.2/frame-title)

Diff for: ‎docs/rules/img-redundant-alt.md

+6
Original file line numberDiff line numberDiff line change
@@ -36,3 +36,9 @@ The rule will first check if `aria-hidden` is true to determine whether to enfor
3636
<img src="bar" alt="Image of me at a bar!" />
3737
<img src="baz" alt="Picture of baz fixing a bug." />
3838
```
39+
40+
## Accessibility guidelines
41+
General best practice (reference resources)
42+
43+
### Resources
44+
- [WebAIM, Alternative Text](https://webaim.org/techniques/alttext/)

Diff for: ‎docs/rules/interactive-supports-focus.md

+9-6
Original file line numberDiff line numberDiff line change
@@ -50,12 +50,6 @@ If your element is catching bubbled click or key events from descendant elements
5050

5151
Marking an element with the role `presentation` indicates to assistive technology that this element should be ignored; it exists to support the web application and is not meant for humans to interact with directly.
5252

53-
### References
54-
1. [AX_FOCUS_02](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_focus_02)
55-
1. [Mozilla Developer Network - ARIA Techniques](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role#Keyboard_and_focus)
56-
1. [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
57-
1. [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)
58-
5953
## Rule details
6054

6155
This rule takes an options object with the key `tabbable`. The value is an array of interactive ARIA roles that should be considered tabbable, not just focusable. Any interactive role not included in this list will be flagged as needing to be focusable (tabindex of -1).
@@ -143,3 +137,12 @@ The list of possible values includes:
143137
<!-- Bad: anchor element without href is not focusable -->
144138
<a onclick="showNextPage();" role="button">Next page</a>
145139
```
140+
141+
## Accessibility guidelines
142+
- [WCAG 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard)
143+
144+
### Resources
145+
- [Chrome Audit Rules, AX_FOCUS_02](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_focus_02)
146+
- [Mozilla Developer Network - ARIA Techniques](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role#Keyboard_and_focus)
147+
- [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
148+
- [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)

Diff for: ‎docs/rules/label-has-associated-control.md

+5
Original file line numberDiff line numberDiff line change
@@ -137,3 +137,8 @@ function Foo(props) {
137137
Surname
138138
</label>
139139
```
140+
141+
## Accessibility guidelines
142+
- [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)
143+
- [WCAG 3.3.2](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions)
144+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)

Diff for: ‎docs/rules/label-has-for.md

+5
Original file line numberDiff line numberDiff line change
@@ -112,3 +112,8 @@ function Foo(props) {
112112
<input type="text" id="firstName" />
113113
<label>First Name</label>
114114
```
115+
116+
## Accessibility guidelines
117+
- [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)
118+
- [WCAG 3.3.2](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions)
119+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)

Diff for: ‎docs/rules/lang.md

+8-6
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,6 @@
22

33
The `lang` prop on the `<html>` element must be a valid IETF's BCP 47 language tag.
44

5-
#### References
6-
7-
1. [axe-core, valid-lang](https://dequeuniversity.com/rules/axe/3.2/valid-lang)
8-
2. [Language tags in HTML and XML](https://www.w3.org/International/articles/language-tags/)
9-
3. [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)
10-
115
## Rule details
126

137
This rule takes no arguments.
@@ -25,3 +19,11 @@ This rule takes no arguments.
2519
<html>
2620
<html lang="foo">
2721
```
22+
23+
## Accessibility guidelines
24+
- [WCAG 3.1.1](https://www.w3.org/WAI/WCAG21/Understanding/language-of-page)
25+
26+
### Resources
27+
- [axe-core, valid-lang](https://dequeuniversity.com/rules/axe/3.2/valid-lang)
28+
- [Language tags in HTML and XML](https://www.w3.org/International/articles/language-tags/)
29+
- [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)

Diff for: ‎docs/rules/media-has-caption.md

+8-5
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,6 @@ Providing captions for media is essential for deaf users to follow along. Captio
44

55
The captions should contain all important and relevant information to understand the corresponding media. This may mean that the captions are not a 1:1 mapping of the dialogue in the media content. However, captions are *not* necessary for video components with the `muted` attribute.
66

7-
### References
8-
9-
1. [audio](https://dequeuniversity.com/rules/axe/2.1/audio-caption)
10-
1. [video](https://dequeuniversity.com/rules/axe/2.1/video-caption)
11-
127
## Rule details
138

149
This rule takes one optional object argument of type object:
@@ -39,3 +34,11 @@ For the `audio`, `video`, and `track` options, these strings determine which JSX
3934
<audio {...props} />
4035
<video {...props} />
4136
```
37+
38+
## Accessibility guidelines
39+
- [WCAG 1.2.2](https://www.w3.org/WAI/WCAG21/Understanding/captions-prerecorded.html)
40+
- [WCAG 1.2.3](https://www.w3.org/WAI/WCAG21/Understanding/audio-description-or-media-alternative-prerecorded.html)
41+
42+
### Resources
43+
- [axe-core, audio-caption](https://dequeuniversity.com/rules/axe/2.1/audio-caption)
44+
- [axe-core, video-caption](https://dequeuniversity.com/rules/axe/2.1/video-caption)

Diff for: ‎docs/rules/mouse-events-have-key-events.md

+3
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,6 @@ In example 3 and 4 below, even if otherProps contains onBlur and/or onFocus, thi
2323
<div onMouseOver={ () => void 0 } {...otherProps} />
2424
<div onMouseOut={ () => void 0 } {...otherProps} />
2525
```
26+
27+
## Accessibility guidelines
28+
- [WCAG 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard)

Diff for: ‎docs/rules/no-access-key.md

+6
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,9 @@ This rule takes no arguments.
1818
```jsx
1919
<div accessKey="h" />
2020
```
21+
22+
## Accessibility guidelines
23+
General best practice (reference resources)
24+
25+
### Resources
26+
- [WebAIM, Keyboard Accessibility: Accesskey](http://webaim.org/techniques/keyboard/accesskey#spec)

Diff for: ‎docs/rules/no-autofocus.md

+7-3
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@
22

33
Enforce that autoFocus prop is not used on elements. Autofocusing elements can cause usability issues for sighted and non-sighted users, alike.
44

5-
#### References
6-
1. [w3c](https://w3c.github.io/html/sec-forms.html#autofocusing-a-form-control-the-autofocus-attribute)
7-
85
## Rule details
96

107
This rule takes one optional object argument of type object:
@@ -33,3 +30,10 @@ For the `ignoreNonDOM` option, this determines if developer created components a
3330
<div autoFocus="false" />
3431
<div autoFocus={undefined} />
3532
```
33+
34+
## Accessibility guidelines
35+
General best practice (reference resources)
36+
37+
### Resources
38+
- [WHATWG HTML Standard, The autofocus attribute](https://html.spec.whatwg.org/multipage/interaction.html#attr-fe-autofocus)
39+
- [The accessibility of HTML 5 autofocus](https://www.brucelawson.co.uk/2009/the-accessibility-of-html-5-autofocus/)

Diff for: ‎docs/rules/no-distracting-elements.md

+7-4
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,6 @@
22

33
Enforces that no distracting elements are used. Elements that can be visually distracting can cause accessibility issues with visually impaired users. Such elements are most likely deprecated, and should be avoided. By default, the following elements are visually distracting: `<marquee>` and `<blink>`.
44

5-
#### References
6-
1. [axe-core, marquee](https://dequeuniversity.com/rules/axe/3.2/marquee)
7-
2. [axe-core, blink](https://dequeuniversity.com/rules/axe/3.2/blink)
8-
95
## Rule details
106

117
This rule takes one optional object argument of type object:
@@ -32,3 +28,10 @@ For the `elements` option, these strings determine which JSX elements should be
3228
<marquee />
3329
<blink />
3430
```
31+
32+
## Accessibility guidelines
33+
- [WCAG 2.2.2](https://www.w3.org/WAI/WCAG21/Understanding/pause-stop-hide)
34+
35+
### Resources
36+
- [axe-core, marquee](https://dequeuniversity.com/rules/axe/3.2/marquee)
37+
- [axe-core, blink](https://dequeuniversity.com/rules/axe/3.2/blink)

Diff for: ‎docs/rules/no-interactive-element-to-noninteractive-role.md

+11-7
Original file line numberDiff line numberDiff line change
@@ -32,13 +32,6 @@ Put the content inside your interactive element.
3232
</div>
3333
```
3434

35-
### References
36-
37-
1. [WAI-ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#usage_intro)
38-
1. [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)
39-
1. [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
40-
1. [Mozilla Developer Network - ARIA Techniques](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role#Keyboard_and_focus)
41-
4235
## Rule details
4336

4437
The recommended options for this rule allow the `tr` element to be given a role of `presentation` (or its semantic equivalent `none`). Under normal circumstances, an element with an interactive role should not be semantically neutralized with `presentation` (or `none`).
@@ -61,3 +54,14 @@ Under the recommended options, the following code is valid. It would be invalid
6154
```jsx
6255
<tr role="presentation" />
6356
```
57+
58+
## Accessibility guidelines
59+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
60+
61+
### Resources
62+
- [ARIA Spec, States and Properties](https://www.w3.org/TR/wai-aria/#states_and_properties)
63+
- [Chrome Audit Rules, AX_ARIA_04](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_04)
64+
- [WAI-ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#usage_intro)
65+
- [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)
66+
- [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
67+
- [Mozilla Developer Network - ARIA Techniques](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role#Keyboard_and_focus)

Diff for: ‎docs/rules/no-noninteractive-element-interactions.md

+9-7
Original file line numberDiff line numberDiff line change
@@ -89,13 +89,6 @@ If your user interface has a table-like layout, but is filled with interactive c
8989

9090
You can also put the interactive content inside the grid cell. This maintains the semantic distinction between the cell and the interaction content, although a grid cell can be interactive.
9191

92-
### References
93-
94-
1. [WAI-ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#usage_intro)
95-
1. [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)
96-
1. [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
97-
1. [Mozilla Developer Network - ARIA Techniques](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role#Keyboard_and_focus)
98-
9992
## Rule details
10093

10194
You may configure which handler props should be taken into account when applying this rule. The recommended configuration includes the following 6 handlers.
@@ -133,3 +126,12 @@ Adjust the list of handler prop names in the handlers array to increase or decre
133126
<li onClick={() => void 0} />
134127
<div onClick={() => void 0} role="listitem" />
135128
```
129+
130+
## Accessibility guidelines
131+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
132+
133+
### Resources
134+
- [WAI-ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#usage_intro)
135+
- [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)
136+
- [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
137+
- [Mozilla Developer Network - ARIA Techniques](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role#Keyboard_and_focus)

Diff for: ‎docs/rules/no-noninteractive-element-to-interactive-role.md

+9-7
Original file line numberDiff line numberDiff line change
@@ -36,13 +36,6 @@ Or wrap the content inside your interactive element.
3636
</div>
3737
```
3838

39-
### References
40-
41-
1. [WAI-ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#usage_intro)
42-
1. [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)
43-
1. [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
44-
1. [Mozilla Developer Network - ARIA Techniques](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role#Keyboard_and_focus)
45-
4639
## Rule details
4740

4841
The recommended options for this rule allow several common interactive roles to be applied to a non-interactive element. The options are provided as an object keyed by HTML element name; the value is an array of interactive roles that are allowed on the specified element.
@@ -67,3 +60,12 @@ Under the recommended options, the following code is valid. It would be invalid
6760
```jsx
6861
<ul role="menu" />
6962
```
63+
64+
## Accessibility guidelines
65+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
66+
67+
### Resources
68+
- [WAI-ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#usage_intro)
69+
- [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)
70+
- [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
71+
- [Mozilla Developer Network - ARIA Techniques](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role#Keyboard_and_focus)

Diff for: ‎docs/rules/no-noninteractive-tabindex.md

+6-4
Original file line numberDiff line numberDiff line change
@@ -46,10 +46,6 @@ It is not necessary to put a tabindex on an `<article>`, for instance or on `<li
4646

4747
Your application might require an exception to this rule in the case of an element that captures incoming tab traversal for a composite widget. In that case, turn off this rule on a per instance basis. This is an uncommon case.
4848

49-
### References
50-
51-
1. [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
52-
5349
## Rule details
5450

5551
The recommended options for this rule allow `tabIndex` on elements with the noninteractive `tabpanel` role. Adding `tabIndex` to a tabpanel is a recommended practice in some instances.
@@ -85,3 +81,9 @@ The recommended options for this rule allow `tabIndex` on elements with the noni
8581
<article tabIndex="0" />
8682
<article tabIndex={0} />
8783
```
84+
85+
## Accessibility guidelines
86+
- [WCAG 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard)
87+
88+
### Resources
89+
- [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)

Diff for: ‎docs/rules/no-onchange.md

+7-4
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,6 @@
22

33
Enforce usage of `onBlur` over/in parallel with `onChange` on select menu elements for accessibility. `onBlur` **should** be used instead of `onChange`, unless absolutely necessary and it causes no negative consequences for keyboard only or screen reader users. `onBlur` is a more declarative action by the user: for instance in a dropdown, using the arrow keys to toggle between options will trigger the `onChange` event in some browsers. Regardless, when a change of context results from an `onBlur` event or an `onChange` event, the user should be notified of the change unless it occurs below the currently focused element.
44

5-
#### References
6-
1. [onChange Event Accessibility Issues](http://cita.disability.uiuc.edu/html-best-practices/auto/onchange.php)
7-
2. [onChange Select Menu](http://www.themaninblue.com/writing/perspective/2004/10/19/)
8-
95
## Rule details
106

117
This rule takes no arguments.
@@ -25,3 +21,10 @@ This rule takes no arguments.
2521
```jsx
2622
<select onChange={updateModel} />
2723
```
24+
25+
## Accessibility guidelines
26+
- [WCAG 3.2.2](https://www.w3.org/WAI/WCAG21/Understanding/on-input)
27+
28+
### Resources
29+
- [onChange Event Accessibility Issues](http://cita.disability.uiuc.edu/html-best-practices/auto/onchange.php)
30+
- [onChange Select Menu](http://www.themaninblue.com/writing/perspective/2004/10/19/)

Diff for: ‎docs/rules/no-redundant-roles.md

+6-3
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@
22

33
Some HTML elements have native semantics that are implemented by the browser. This includes default/implicit ARIA roles. Setting an ARIA role that matches its default/implicit role is redundant since it is already set by the browser.
44

5-
#### References
6-
1. [w3](https://www.w3.org/TR/html5/dom.html#aria-role-attribute)
7-
85
## Rule details
96

107
The default options for this rule allow an implicit role of `navigation` to be applied to a `nav` element as is [advised by w3](https://www.w3.org/WAI/GL/wiki/Using_HTML5_nav_element#Example:The_.3Cnav.3E_element). The options are provided as an object keyed by HTML element name; the value is an array of implicit ARIA roles that are allowed on the specified element.
@@ -31,3 +28,9 @@ The default options for this rule allow an implicit role of `navigation` to be a
3128
<button role="button" />
3229
<img role="img" src="foo.jpg" />
3330
```
31+
32+
## Accessibility guidelines
33+
General best practice (reference resources)
34+
35+
### Resources
36+
- [ARIA Spec, ARIA Adds Nothing to Default Semantics of Most HTML Elements](https://www.w3.org/TR/using-aria/#aria-does-nothing)

Diff for: ‎docs/rules/no-static-element-interactions.md

+9-7
Original file line numberDiff line numberDiff line change
@@ -53,13 +53,6 @@ If your element is catching bubbled click or key events from descendant elements
5353

5454
Do not use the role `presentation` on the element: it removes the element's semantics, and may also remove its children's semantics, creating big issues with assistive technology.
5555

56-
### References
57-
58-
1. [WAI-ARIA `role` attribute](https://www.w3.org/TR/wai-aria-1.1/#usage_intro)
59-
1. [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)
60-
1. [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
61-
1. [Mozilla Developer Network - ARIA Techniques](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role#Keyboard_and_focus)
62-
6356
## Rule details
6457

6558
You may configure which handler props should be taken into account when applying this rule. The recommended configuration includes the following 6 handlers.
@@ -95,3 +88,12 @@ Adjust the list of handler prop names in the handlers array to increase or decre
9588
```jsx
9689
<div onClick={() => {}} />
9790
```
91+
92+
## Accessibility guidelines
93+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
94+
95+
### Resources
96+
- [WAI-ARIA `role` attribute](https://www.w3.org/TR/wai-aria-1.1/#usage_intro)
97+
- [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)
98+
- [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
99+
- [Mozilla Developer Network - ARIA Techniques](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role#Keyboard_and_focus)

Diff for: ‎docs/rules/role-has-required-aria-props.md

+8-5
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,6 @@
22

33
Elements with ARIA roles must have all required attributes for that role.
44

5-
#### References
6-
1. [Spec](https://www.w3.org/TR/wai-aria/#roles)
7-
2. [AX_ARIA_03](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_03)
8-
95
## Rule details
106

117
This rule takes no arguments.
@@ -21,4 +17,11 @@ This rule takes no arguments.
2117
```jsx
2218
<!-- Bad: the checkbox role requires the aria-checked state -->
2319
<span role="checkbox" aria-labelledby="foo" tabindex="0"></span>
24-
```
20+
```
21+
22+
## Accessibility guidelines
23+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
24+
25+
### Resources
26+
- [ARIA Spec, Roles](https://www.w3.org/TR/wai-aria/#roles)
27+
- [Chrome Audit Rules, AX_ARIA_03](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_03)

Diff for: ‎docs/rules/role-supports-aria-props.md

+8-5
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,6 @@
22

33
Enforce that elements with explicit or implicit roles defined contain only `aria-*` properties supported by that `role`. Many ARIA attributes (states and properties) can only be used on elements with particular roles. Some elements have implicit roles, such as `<a href="#" />`, which will resolve to `role="link"`.
44

5-
#### References
6-
1. [AX_ARIA_10](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_10)
7-
2. [Supported States & Properties](https://www.w3.org/TR/wai-aria/#states_and_properties)
8-
95
## Rule details
106

117
This rule takes no arguments.
@@ -29,4 +25,11 @@ This rule takes no arguments.
2925
<li aria-required tabIndex="-1" role="radio" aria-checked="false">Brook Trout</li>
3026
<li aria-required tabIndex="0" role="radio" aria-checked="true">Lake Trout</li>
3127
</ul>
32-
```
28+
```
29+
30+
## Accessibility guidelines
31+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
32+
33+
### Resources
34+
- [ARIA Spec, States and Properties](https://www.w3.org/TR/wai-aria/#states_and_properties)
35+
- [Chrome Audit Rules, AX_ARIA_10](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_10)

Diff for: ‎docs/rules/scope.md

+7-3
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,6 @@
22

33
The `scope` scope should be used only on `<th>` elements.
44

5-
#### References
6-
1. [axe-core, scope](https://dequeuniversity.com/rules/axe/1.1/scope)
7-
85
## Rule details
96

107
This rule takes no arguments.
@@ -20,3 +17,10 @@ This rule takes no arguments.
2017
```jsx
2118
<div scope />
2219
```
20+
21+
## Accessibility guidelines
22+
- [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)
23+
- [WCAG 4.1.1](https://www.w3.org/WAI/WCAG21/Understanding/parsing)
24+
25+
### Resources
26+
- [axe-core, scope-attr-valid](https://dequeuniversity.com/rules/axe/3.5/scope-attr-valid)

Diff for: ‎docs/rules/tabindex-no-positive.md

+6-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
11
# tabindex-no-positive
22

3-
Avoid positive tabIndex property values to synchronize the flow of the page with keyboard tab order.
4-
5-
#### References
6-
1. [AX_FOCUS_03](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_focus_03)
3+
Avoid positive `tabIndex` property values to synchronize the flow of the page with keyboard tab order.
74

85
## Rule details
96

@@ -24,3 +21,8 @@ This rule takes no arguments.
2421
<span tabIndex="2">never really sure what goes after baz</span>
2522
```
2623

24+
## Accessibility guidelines
25+
- [WCAG 2.4.3](https://www.w3.org/WAI/WCAG21/Understanding/focus-order)
26+
27+
### Resources
28+
- [Chrome Audit Rules, AX_FOCUS_03](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_focus_03)

0 commit comments

Comments
 (0)
Please sign in to comment.