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 jsx-eslint#30
backwardok · Jun 27, 2020 · c1436ae · c1436ae
1 parent 7a34e45
commit c1436ae
Show file tree

Hide file tree

Showing 36 changed files with 249 additions and 127 deletions.
diff --git a/docs/rules/accessible-emoji.md b/docs/rules/accessible-emoji.md
@@ -1,9 +1,6 @@
 # [Deprecated] accessible-emoji
 
-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.
-
-#### Resources
-1. [Léonie Watson](http://tink.uk/accessible-emoji/)
+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.
 
 ## Rule details
 
@@ -21,3 +18,9 @@ This rule takes no arguments.
 <span>🐼</span>
 <i role="img" aria-label="Panda">🐼</i>
 ```
+
+## Accessibility guidelines
+- [WCAG 1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)
+
+### Resources
+- [Léonie Watson, Accessible Emoji](http://tink.uk/accessible-emoji/)
diff --git a/docs/rules/alt-text.md b/docs/rules/alt-text.md
@@ -2,12 +2,6 @@
 
 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>`.
 
-#### Resources
-1. [axe-core, object-alt](https://dequeuniversity.com/rules/axe/3.2/object-alt)
-2. [axe-core, image-alt](https://dequeuniversity.com/rules/axe/3.2/image-alt)
-3. [axe-core, input-image-alt](https://dequeuniversity.com/rules/axe/3.2/input-image-alt)
-4. [axe-core, area-alt](https://dequeuniversity.com/rules/axe/3.2/area-alt)
-
 ## How to resolve
 ### `<img>`
 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) {
 
 <input type="image" {...props} />
 ```
+
+## Accessibility guidelines
+- [WCAG 1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)
+
+### Resources
+- [axe-core, object-alt](https://dequeuniversity.com/rules/axe/3.2/object-alt)
+- [axe-core, image-alt](https://dequeuniversity.com/rules/axe/3.2/image-alt)
+- [axe-core, input-image-alt](https://dequeuniversity.com/rules/axe/3.2/input-image-alt)
+- [axe-core, area-alt](https://dequeuniversity.com/rules/axe/3.2/area-alt)
diff --git a/docs/rules/anchor-has-content.md b/docs/rules/anchor-has-content.md
@@ -2,9 +2,6 @@
 
 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.
 
-#### References
-1. [axe-core, link-name](https://dequeuniversity.com/rules/axe/3.2/link-name)
-
 ## Rule details
 
 This rule takes one optional object argument of type object:
@@ -51,3 +48,9 @@ return (
 <a />
 <a><TextWrapper aria-hidden /></a>
 ```
+## Accessibility guidelines
+- [WCAG 2.4.4](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context)
+- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
+
+### Resources
+- [axe-core, link-name](https://dequeuniversity.com/rules/axe/3.2/link-name)
diff --git a/docs/rules/anchor-is-valid.md b/docs/rules/anchor-is-valid.md
@@ -128,12 +128,6 @@ This button element can now also be used inline in text.
 
 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.
 
-
-### References
-  1. [WebAIM - Introduction to Links and Hypertext](http://webaim.org/techniques/hypertext/)
-  1. [Links vs. Buttons in Modern Web Applications](https://marcysutton.com/links-vs-buttons-in-modern-web-applications/)
-  1. [Using ARIA - Notes on ARIA use in HTML](https://www.w3.org/TR/using-aria/#NOTES)
-
 ## Rule details
 
 This rule takes one optional object argument of type object:
@@ -221,4 +215,12 @@ Invalid `href` attribute:
 <a href="javascript:void(0)" />
 <a href={"javascript:void(0)"} />
 <a href={`javascript:void(0)`} />
-```
+```
+
+## Accessibility guidelines
+- [WCAG 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard)
+
+### Resources
+- [WebAIM - Introduction to Links and Hypertext](http://webaim.org/techniques/hypertext/)
+- [Links vs. Buttons in Modern Web Applications](https://marcysutton.com/links-vs-buttons-in-modern-web-applications/)
+- [Using ARIA - Notes on ARIA use in HTML](https://www.w3.org/TR/using-aria/#NOTES)
diff --git a/docs/rules/aria-activedescendant-has-tabindex.md b/docs/rules/aria-activedescendant-has-tabindex.md
@@ -14,9 +14,6 @@ Because an element with `aria-activedescendant` must be tabbable, it must either
 have an inherent `tabIndex` of zero or declare a `tabIndex` of zero with the `tabIndex`
 attribute.
 
-#### References
-1. [MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-activedescendant_attribute)
-
 ## Rule details
 
 This rule takes no arguments.
@@ -44,3 +41,9 @@ This rule takes no arguments.
 <div aria-activedescendant={someID} tabIndex="-1" />
 <input aria-activedescendant={someID} tabIndex={-1} />
 ```
+
+## Accessibility guidelines
+General best practice (reference resources)
+
+### Resources
+- [MDN, Using the aria-activedescendant attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-activedescendant_attribute)
diff --git a/docs/rules/aria-props.md b/docs/rules/aria-props.md
@@ -20,3 +20,6 @@ This rule takes no arguments.
 <div id="address_label">Enter your address</div>
 <input aria-labeledby="address_label">
 ```
+
+## Accessibility guidelines
+- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
diff --git a/docs/rules/aria-proptypes.md b/docs/rules/aria-proptypes.md
@@ -2,10 +2,6 @@
 
 ARIA state and property values must be valid.
 
-#### References
-1. [Spec](https://www.w3.org/TR/wai-aria/#states_and_properties)
-2. [AX_ARIA_04](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_04)
-
 ## Rule details
 
 This rule takes no arguments.
@@ -22,3 +18,9 @@ This rule takes no arguments.
 <span aria-hidden="yes">foo</span>
 ```
 
+## Accessibility guidelines
+- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
+
+### Resources
+- [ARIA Spec, States and Properties](https://www.w3.org/TR/wai-aria/#states_and_properties)
+- [Chrome Audit Rules, AX_ARIA_04](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_04)
diff --git a/docs/rules/aria-role.md b/docs/rules/aria-role.md
@@ -2,9 +2,6 @@
 
 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.
 
-[AX_ARIA_01](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_01)
-[DPUB-ARIA roles](https://www.w3.org/TR/dpub-aria-1.0/)
-
 ## Rule details
 
 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
 <div role=""></div>           <!-- Bad: An empty ARIA role is not allowed -->
 <Foo role={role}></Foo>       <!-- Bad: ignoreNonDOM is set to false or not set -->
 ```
+
+## Accessibility guidelines
+- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
+
+### Resources
+- [Chrome Audit Rules, AX_ARIA_01](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_01)
+- [DPUB-ARIA roles](https://www.w3.org/TR/dpub-aria-1.0/)
diff --git a/docs/rules/aria-unsupported-elements.md b/docs/rules/aria-unsupported-elements.md
@@ -2,9 +2,6 @@
 
 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.
 
-#### References
-1. [AX_ARIA_12](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_12)
-
 ## Rule details
 
 This rule takes no arguments.
@@ -21,3 +18,9 @@ This rule takes no arguments.
 <meta charset="UTF-8" aria-hidden="false" />
 ```
 
+## Accessibility guidelines
+- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
+
+### Resources
+- [Chrome Audit Rules, AX_ARIA_12](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_aria_12)
+- [DPUB-ARIA roles](https://www.w3.org/TR/dpub-aria-1.0/)
diff --git a/docs/rules/autocomplete-valid.md b/docs/rules/autocomplete-valid.md
@@ -2,10 +2,6 @@
 
 Ensure the autocomplete attribute is correct and suitable for the form field it is used with.
 
-#### References
-1. [axe-core, autocomplete-valid](https://dequeuniversity.com/rules/axe/3.2/autocomplete-valid)
-2. [HTML 5.2, Autocomplete requirements](https://www.w3.org/TR/html52/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute)
-
 ## Rule details
 
 This rule takes one optional object argument of type object:
@@ -39,4 +35,11 @@ This rule takes one optional object argument of type object:
 
 <!-- Bad: MyInput is listed in inputComponents -->
 <MyInput autocomplete="incorrect" /> 
-```
+```
+
+## Accessibility guidelines
+- [WCAG 1.3.5](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose)
+
+### Resources
+- [axe-core, autocomplete-valid](https://dequeuniversity.com/rules/axe/3.2/autocomplete-valid)
+- [HTML 5.2, Autocomplete requirements](https://www.w3.org/TR/html52/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute)
diff --git a/docs/rules/click-events-have-key-events.md b/docs/rules/click-events-have-key-events.md
@@ -1,6 +1,6 @@
 # click-events-have-key-events
 
-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.
+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.
 
 ## Rule details
 
@@ -11,9 +11,14 @@ This rule takes no arguments.
 <div onClick={() => {}} onKeyDown={this.handleKeyDown} />
 <div onClick={() => {}} onKeyUp={this.handleKeyUp} />
 <div onClick={() => {}} onKeyPress={this.handleKeyPress} />
+<button onClick={() => {}} />
+<div onClick{() => {}} aria-hidden="true" />
 ```
 
 ### Fail
 ```jsx
 <div onClick={() => {}} />
 ```
+
+## Accessibility guidelines
+- [WCAG 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard)
diff --git a/docs/rules/control-has-associated-label.md b/docs/rules/control-has-associated-label.md
@@ -102,3 +102,8 @@ This rule takes one optional object argument of type object:
 ```jsx
 <button type="button" class="icon-save" />
 ```
+
+## Accessibility guidelines
+- [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)
+- [WCAG 3.3.2](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions)
+- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
diff --git a/docs/rules/heading-has-content.md b/docs/rules/heading-has-content.md
@@ -2,9 +2,6 @@
 
 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.
 
-#### References
-1. [axe-core, empty-heading](https://dequeuniversity.com/rules/axe/3.2/empty-heading)
-
 ## Rule details
 
 This rule takes one optional object argument of type object:
@@ -58,3 +55,9 @@ function Foo(props) {
 <h1 />
 <h1><TextWrapper aria-hidden />
 ```
+
+## Accessibility guidelines
+- [WCAG 2.4.6](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-descriptive.html)
+
+### Resources
+- [axe-core, empty-heading](https://dequeuniversity.com/rules/axe/3.2/empty-heading)
diff --git a/docs/rules/html-has-lang.md b/docs/rules/html-has-lang.md
@@ -2,10 +2,6 @@
 
 <html> elements must have the lang prop.
 
-#### References
-1. [axe-core, html-has-lang](https://dequeuniversity.com/rules/axe/3.2/html-has-lang)
-1. [axe-core, html-lang-valid](https://dequeuniversity.com/rules/axe/3.2/html-lang-valid)
-
 ## Rule details
 
 This rule takes no arguments.
@@ -22,3 +18,10 @@ This rule takes no arguments.
 ```jsx
 <html>
 ```
+
+## Accessibility guidelines
+- [WCAG 3.1.1](https://www.w3.org/WAI/WCAG21/Understanding/language-of-page)
+
+### Resources
+- [axe-core, html-has-lang](https://dequeuniversity.com/rules/axe/3.2/html-has-lang)
+- [axe-core, html-lang-valid](https://dequeuniversity.com/rules/axe/3.2/html-lang-valid)
diff --git a/docs/rules/iframe-has-title.md b/docs/rules/iframe-has-title.md
@@ -2,9 +2,6 @@
 
 `<iframe>` elements must have a unique title property to indicate its content to the user.
 
-#### References
-1. [axe-core, frame-title](https://dequeuniversity.com/rules/axe/3.2/frame-title)
-
 ## Rule details
 
 This rule takes no arguments.
@@ -27,3 +24,10 @@ This rule takes no arguments.
 <iframe title={true} />
 <iframe title={42} />
 ```
+
+## Accessibility guidelines
+- [WCAG 2.4.1](https://www.w3.org/WAI/WCAG21/Understanding/bypass-blocks)
+- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
+
+### Resources
+- [axe-core, frame-title](https://dequeuniversity.com/rules/axe/3.2/frame-title)
diff --git a/docs/rules/img-redundant-alt.md b/docs/rules/img-redundant-alt.md
@@ -36,3 +36,9 @@ The rule will first check if `aria-hidden` is true to determine whether to enfor
 <img src="bar" alt="Image of me at a bar!" />
 <img src="baz" alt="Picture of baz fixing a bug." />
 ```
+
+## Accessibility guidelines
+General best practice (reference resources)
+
+### Resources
+- [WebAIM, Alternative Text](https://webaim.org/techniques/alttext/)
diff --git a/docs/rules/interactive-supports-focus.md b/docs/rules/interactive-supports-focus.md
@@ -50,12 +50,6 @@ If your element is catching bubbled click or key events from descendant elements
 
 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.
 
-### References
-  1. [AX_FOCUS_02](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_focus_02)
-  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)
-  1. [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
-  1. [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)
-
 ## Rule details
 
 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:
 <!-- Bad: anchor element without href is not focusable -->
 <a onclick="showNextPage();" role="button">Next page</a>
 ```
+
+## Accessibility guidelines
+- [WCAG 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard)
+
+### Resources
+- [Chrome Audit Rules, AX_FOCUS_02](https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules#ax_focus_02) 
+- [Mozilla Developer Network - ARIA Techniques](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role#Keyboard_and_focus)
+- [Fundamental Keyboard Navigation Conventions](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_generalnav)
+- [WAI-ARIA Authoring Practices Guide - Design Patterns and Widgets](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_ex)
diff --git a/docs/rules/label-has-associated-control.md b/docs/rules/label-has-associated-control.md
@@ -137,3 +137,8 @@ function Foo(props) {
   Surname
 </label>
 ```
+
+## Accessibility guidelines
+- [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)
+- [WCAG 3.3.2](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions)
+- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
diff --git a/docs/rules/label-has-for.md b/docs/rules/label-has-for.md
@@ -112,3 +112,8 @@ function Foo(props) {
 <input type="text" id="firstName" />
 <label>First Name</label>
 ```
+
+## Accessibility guidelines
+- [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships)
+- [WCAG 3.3.2](https://www.w3.org/WAI/WCAG21/Understanding/labels-or-instructions)
+- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
diff --git a/docs/rules/lang.md b/docs/rules/lang.md
@@ -2,12 +2,6 @@
 
 The `lang` prop on the `<html>` element must be a valid IETF's BCP 47 language tag.
 
-#### References
-
-1. [axe-core, valid-lang](https://dequeuniversity.com/rules/axe/3.2/valid-lang)
-2. [Language tags in HTML and XML](https://www.w3.org/International/articles/language-tags/)
-3. [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)
-
 ## Rule details
 
 This rule takes no arguments.
@@ -25,3 +19,11 @@ This rule takes no arguments.
 <html>
 <html lang="foo">
 ```
+
+## Accessibility guidelines
+- [WCAG 3.1.1](https://www.w3.org/WAI/WCAG21/Understanding/language-of-page)
+
+### Resources
+- [axe-core, valid-lang](https://dequeuniversity.com/rules/axe/3.2/valid-lang)
+- [Language tags in HTML and XML](https://www.w3.org/International/articles/language-tags/)
+- [IANA Language Subtag Registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry)