A few months ago @jsnmrs and I started to build a linter that provides suggestions for image alternative text: alt-text.

Example:

altText("A photo of a dog.");

Returns:

Alt text should not contain “photo of” (https://git.io/JvqAM).

While the usefulness of alt text can be subjective to people who have low or no vision, context, detail, length, and relevance all contribute to the quality of the description. Determining alt text quality is a manual effort, but the linter’s goal is to help find patterns that you should avoid.

You can find a list of all suggestions in the documentation.

Building the documentation

We knew we wanted each suggestion to include a link back to documentation so the developer can better understand the rationale, see examples, and find resources to learn more. We built a system to automatically generate the documentation on commit:

• clues.js - Has metadata for each suggestion. All values are asserted with tests.
• rules.js - Creates a function for each suggestion and then uses the createSuggestion function to pull in the suggestion’s metadata from clues.js.
• write-docs.js - Runs on commit to rewrite README.md by parsing each suggestion from clues.js into markdown.
• urls.js - Runs on commit to generate shortened URL hash links for each suggestion heading and saves them to urls.json. The createSuggestion function in rules.js pulls in urls.json to append the link back to the documentation.

On GitHub

You can view and contribute to alt-text on GitHub. If you write in markdown, there’s a companion remark-lint plugin: remark-lint-alt-text.