Merge pull request #453 from github/add-a11y-no-title-attribute

Create rule: a11y-no-title-attribute

Author: kendallgassner

README.md

@@ -85,6 +85,7 @@ This config will be interpreted in the following way:
 | :------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | :- | :- | :- |
 | [a11y-aria-label-is-well-formatted](docs/rules/a11y-aria-label-is-well-formatted.md)                     | [aria-label] text should be formatted as you would visual text.                                                          | ⚛️ |    |    |
 | [a11y-no-generic-link-text](docs/rules/a11y-no-generic-link-text.md)                                     | disallow generic link text                                                                                               |    |    | ❌  |
+| [a11y-no-title-attribute](docs/rules/a11y-no-title-attribute.md)                                         | Guards against developers using the title attribute                                                                      | ⚛️ |    |    |
 | [a11y-no-visually-hidden-interactive-element](docs/rules/a11y-no-visually-hidden-interactive-element.md) | Ensures that interactive elements are not visually hidden                                                                | ⚛️ |    |    |
 | [a11y-svg-has-accessible-name](docs/rules/a11y-svg-has-accessible-name.md)                               | SVGs must have an accessible name                                                                                        | ⚛️ |    |    |
 | [array-foreach](docs/rules/array-foreach.md)                                                             | enforce `for..of` loops over `Array.forEach`                                                                             | ✅  |    |    |

docs/rules/a11y-no-title-attribute.md

@@ -0,0 +1,45 @@
+# Guards against developers using the title attribute (`github/a11y-no-title-attribute`)
+
+💼 This rule is enabled in the ⚛️ `react` config.
+
+<!-- end auto-generated rule header -->
+
+The title attribute is strongly discouraged. The only exception is on an `<iframe>` element. It is hardly useful and cannot be accessed by multiple groups of users including keyboard-only users and mobile users.
+
+The `title` attribute is commonly set on links, matching the link text. This is redundant and unnecessary so it can be simply be removed.
+
+If you are considering the `title` attribute to provide supplementary description, consider whether the text in question can be persisted in the design. Alternatively, if it's important to display supplementary text that is hidden by default, consider using an accessible tooltip implementation that uses the aria-labelledby or aria-describedby semantics. Even so, proceed with caution: tooltips should only be used on interactive elements like links or buttons. See [Tooltip alternatives](https://primer.style/design/guides/accessibility/tooltip-alternatives) for more accessible alternatives.
+
+### Should I use the title attribute to provide an accessible name for an <svg>?
+
+Use a <title> element instead of the title attribute, or an aria-label.
+
+## Rule Details
+
+👎 Examples of **incorrect** code for this rule:
+
+```jsx
+<a src="https://www.github.com" title="A home for all developers">
+  GitHub
+</a>
+```
+
+```jsx
+<a href="/" title="github.com">
+  GitHub
+</a>
+```
+
+```jsx
+<span src="https://www.github.com" title="supercalifragilisticexpialidocious">
+  supercali...
+</span>
+```
+
+👍 Examples of **correct** code for this rule:
+
+```jsx
+<iframe src="https://www.github.com" title="Github"></iframe>
+```
+
+## Version

lib/configs/react.js

@@ -11,6 +11,7 @@ module.exports = {
     'jsx-a11y/role-supports-aria-props': 'off', // Override with github/role-supports-aria-props until https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/issues/910 is resolved
     'github/a11y-aria-label-is-well-formatted': 'error',
     'github/a11y-no-visually-hidden-interactive-element': 'error',
+    'github/a11y-no-title-attribute': 'error',
     'github/a11y-svg-has-accessible-name': 'error',
     'github/role-supports-aria-props': 'error',
     'jsx-a11y/no-aria-hidden-on-focusable': 'error',

lib/index.js

@@ -2,6 +2,7 @@ module.exports = {
   rules: {
     'a11y-no-visually-hidden-interactive-element': require('./rules/a11y-no-visually-hidden-interactive-element'),
     'a11y-no-generic-link-text': require('./rules/a11y-no-generic-link-text'),
+    'a11y-no-title-attribute': require('./rules/a11y-no-title-attribute'),
     'a11y-aria-label-is-well-formatted': require('./rules/a11y-aria-label-is-well-formatted'),
     'a11y-svg-has-accessible-name': require('./rules/a11y-svg-has-accessible-name'),
     'array-foreach': require('./rules/array-foreach'),

lib/rules/a11y-no-title-attribute.js

@@ -0,0 +1,66 @@
+const {getProp, getPropValue} = require('jsx-ast-utils')
+const {getElementType} = require('../utils/get-element-type')
+
+const SEMANTIC_ELEMENTS = [
+  'a',
+  'button',
+  'summary',
+  'select',
+  'option',
+  'textarea',
+  'input',
+  'span',
+  'div',
+  'p',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'details',
+  'summary',
+  'dialog',
+  'tr',
+  'th',
+  'td',
+  'label',
+]
+
+const ifSemanticElement = (context, node) => {
+  const elementType = getElementType(context, node.openingElement, true)
+
+  for (const semanticElement of SEMANTIC_ELEMENTS) {
+    if (elementType === semanticElement) {
+      return true
+    }
+  }
+  return false
+}
+
+module.exports = {
+  meta: {
+    docs: {
+      description: 'Guards against developers using the title attribute',
+      url: require('../url')(module),
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      JSXElement: node => {
+        const elementType = getElementType(context, node.openingElement)
+        if (elementType !== `iframe` && ifSemanticElement(context, node)) {
+          const titleProp = getPropValue(getProp(node.openingElement.attributes, `title`))
+          if (titleProp) {
+            context.report({
+              node,
+              message: 'The title attribute is not accessible and should never be used unless for an `<iframe>`.',
+            })
+          }
+        }
+      },
+    }
+  },
+}

lib/rules/a11y-no-visually-hidden-interactive-element.js

@@ -15,12 +15,12 @@ const schema = generateObjSchema({
  * because a visually hidden input field might cause a false positive.
  * (e.g. fileUpload https://github.com/primer/react/pull/3492)
  */
-const INTERACTIVELEMENTS = ['a', 'button', 'summary', 'select', 'option', 'textarea']
+const INTERACTIVE_ELEMENTS = ['a', 'button', 'summary', 'select', 'option', 'textarea']
 
 const checkIfInteractiveElement = (context, node) => {
   const elementType = getElementType(context, node.openingElement)
 
-  for (const interactiveElement of INTERACTIVELEMENTS) {
+  for (const interactiveElement of INTERACTIVE_ELEMENTS) {
     if (elementType === interactiveElement) {
       return true
     }
@@ -76,7 +76,6 @@ module.exports = {
             message:
               'Avoid visually hidding interactive elements. Visually hiding interactive elements can be confusing to sighted keyboard users as it appears their focus has been lost when they navigate to the hidden element.',
           })
-          return
         }
       },
     }

lib/utils/get-element-type.js

@@ -7,15 +7,15 @@ If a prop determines the type, it can be specified with `props`.
 
 For now, we only support the mapping of one prop type to an element type, rather than combinations of props.
 */
-function getElementType(context, node) {
+function getElementType(context, node, ignoreMap = false) {
   const {settings} = context
 
   // check if the node contains a polymorphic prop
   const polymorphicPropName = settings?.github?.polymorphicPropName ?? 'as'
   const rawElement = getPropValue(getProp(node.attributes, polymorphicPropName)) ?? elementType(node)
 
   // if a component configuration does not exists, return the raw element
-  if (!settings?.github?.components?.[rawElement]) return rawElement
+  if (ignoreMap || !settings?.github?.components?.[rawElement]) return rawElement
 
   const defaultComponent = settings.github.components[rawElement]
 

tests/a11y-no-title-attribute.js

@@ -0,0 +1,59 @@
+const rule = require('../lib/rules/a11y-no-title-attribute')
+const RuleTester = require('eslint').RuleTester
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+})
+
+const errorMessage = 'The title attribute is not accessible and should never be used unless for an `<iframe>`.'
+
+ruleTester.run('a11y-no-title-attribute', rule, {
+  valid: [
+    {code: '<button>Submit</button>'},
+    {code: '<iframe title="an allowed title">GitHub</iframe>'},
+    {code: '<span>some information</span>'},
+    {code: '<a href="github.com">GitHub</a>'},
+    {
+      code: '<Component title="some title">Submit</Component>',
+      settings: {
+        github: {
+          components: {
+            Component: 'iframe',
+          },
+        },
+      },
+    },
+    {
+      // Note: we are only checking semantic elements. We cannot make assumptions about how a React Components is using the title prop.
+      code: '<Link title="some title">Submit</Link>',
+      settings: {
+        github: {
+          components: {
+            Link: 'a',
+          },
+        },
+      },
+    },
+  ],
+  invalid: [
+    {code: '<a title="some title" href="github.com">GitHub</a>', errors: [{message: errorMessage}]},
+    {code: '<span><button title="some title">submit</button></span>', errors: [{message: errorMessage}]},
+    {
+      code: '<Component as="a" title="some title">Submit</Component>',
+      errors: [{message: errorMessage}],
+      settings: {
+        github: {
+          components: {
+            Component: 'iframe',
+          },
+        },
+      },
+    },
+  ],
+})