add help text (and links) to a11y audits (#1589)

* add help text (and links) to a11y audits * update a11y help texts per feedback
GoogleChrome · Feb 1, 2017 · 0a14015 · 0a14015
1 parent 5bbab8d
commit 0a14015
Show file tree

Hide file tree

Showing 8 changed files with 22 additions and 0 deletions.
diff --git a/lighthouse-core/audits/accessibility/aria-allowed-attr.js b/lighthouse-core/audits/accessibility/aria-allowed-attr.js
@@ -33,6 +33,9 @@ class ARIAAllowedAttr extends AxeAudit {
       category: 'Accessibility',
       name: 'aria-allowed-attr',
       description: 'Element aria-* attributes are allowed for this role',
+      helpText: 'Each ARIA `role` supports a specific subset of `aria-*` attributes. ' +
+          'Mismatching these invalidates the `aria-*` attributes. [Learn ' +
+          'more](https://developers.google.com/web/tools/lighthouse/audits/aria-allowed-attributes).',
       requiredArtifacts: ['Accessibility']
     };
   }

diff --git a/lighthouse-core/audits/accessibility/aria-required-attr.js b/lighthouse-core/audits/accessibility/aria-required-attr.js
@@ -33,6 +33,8 @@ class ARIARequiredAttr extends AxeAudit {
       category: 'Accessibility',
       name: 'aria-required-attr',
       description: 'Elements with ARIA roles have the required aria-* attributes',
+      helpText: 'Some ARIA roles have required attributes that describe the state ' +
+          'of the element to screen readers. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/required-aria-attributes).',
       requiredArtifacts: ['Accessibility']
     };
   }

diff --git a/lighthouse-core/audits/accessibility/aria-valid-attr-value.js b/lighthouse-core/audits/accessibility/aria-valid-attr-value.js
@@ -33,6 +33,9 @@ class ARIAValidAttr extends AxeAudit {
       category: 'Accessibility',
       name: 'aria-valid-attr-value',
       description: 'Element aria-* attributes have valid values',
+      helpText: 'Assistive technologies, like screen readers, can\'t interpret ARIA ' +
+          'attributes with invalid values. [Learn ' +
+          'more](https://developers.google.com/web/tools/lighthouse/audits/valid-aria-values).',
       requiredArtifacts: ['Accessibility']
     };
   }

diff --git a/lighthouse-core/audits/accessibility/aria-valid-attr.js b/lighthouse-core/audits/accessibility/aria-valid-attr.js
@@ -33,6 +33,9 @@ class ARIAValidAttr extends AxeAudit {
       category: 'Accessibility',
       name: 'aria-valid-attr',
       description: 'Element aria-* attributes are valid and not misspelled or non-existent.',
+      helpText: 'Assistive technologies, like screen readers, can\'t interpret ARIA ' +
+          'attributes with invalid names. [Learn ' +
+          'more](https://developers.google.com/web/tools/lighthouse/audits/valid-aria-attributes).',
       requiredArtifacts: ['Accessibility']
     };
   }

diff --git a/lighthouse-core/audits/accessibility/color-contrast.js b/lighthouse-core/audits/accessibility/color-contrast.js
@@ -34,6 +34,8 @@ class ColorContrast extends AxeAudit {
       category: 'Accessibility',
       name: 'color-contrast',
       description: 'Background and foreground colors have a sufficient contrast ratio',
+      helpText: 'Low-contrast text is difficult or impossible for many users to read. ' +
+          '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/contrast-ratio).',
       requiredArtifacts: ['Accessibility']
     };
   }

diff --git a/lighthouse-core/audits/accessibility/image-alt.js b/lighthouse-core/audits/accessibility/image-alt.js
@@ -33,6 +33,9 @@ class ImageAlt extends AxeAudit {
       category: 'Accessibility',
       name: 'image-alt',
       description: 'Every image element has an alt attribute',
+      helpText: 'Screen reader users rely on `alt` text to provide descriptions of ' +
+          'images. It\'s also used as fallback content when an image fails to load. ' +
+          '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/alt-attribute).',
       requiredArtifacts: ['Accessibility']
     };
   }

diff --git a/lighthouse-core/audits/accessibility/label.js b/lighthouse-core/audits/accessibility/label.js
@@ -33,6 +33,9 @@ class Label extends AxeAudit {
       category: 'Accessibility',
       name: 'label',
       description: 'Every form element has a label',
+      helpText: 'Labels ensure that form controls are announced properly by assistive ' +
+          'technologies, like screen readers. [Learn ' +
+          'more](https://developers.google.com/web/tools/lighthouse/audits/form-labels).',
       requiredArtifacts: ['Accessibility']
     };
   }

diff --git a/lighthouse-core/audits/accessibility/tabindex.js b/lighthouse-core/audits/accessibility/tabindex.js
@@ -33,6 +33,9 @@ class TabIndex extends AxeAudit {
       category: 'Accessibility',
       name: 'tabindex',
       description: 'No element has a `tabindex` attribute greater than 0',
+      helpText: 'A value greater than 0 implies an explicit navigation ordering. ' +
+          'Although technically valid, this often creates frustrating experiences ' +
+          'for users who rely on assistive technologies. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/tabindex).',
       requiredArtifacts: ['Accessibility']
     };
   }