Check for unhelpful alt text

code • July 4, 2020

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


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


Alt text should not contain “photo of” (

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:

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.

Keep reading code