Your alt text passes automated checks. That doesn’t mean it’s any good.
A study by WebAIM found that 16.2% of images on the top million home pages lack alt text, while 10.8% have undescriptive alt text. GitHub has developed an alt text plugin for the GitHub Accessibility Scanner to help improve alt text quality.
Intelligence analysis by Llama

The plugin uses five deterministic rules to check for missing or poor alt text, including the presence of alt text, filenames, placeholders, generic words, and repeated alt text. It also uses an optional alt-text-quality check that extracts page context to determine the quality of alt text.
Imagine you're a screen reader user, and you're trying to understand what's on a webpage. Alt text is like a description of the pictures on the page. If the alt text is missing or not descriptive, it's hard for the screen reader to tell you what's going on. The GitHub Accessibility Scanner's alt text plugin helps improve alt text quality by catching obvious errors and using a model to evaluate the quality of alt text.
Analysis
Automated Checks vs. Human Reviewers
The GitHub Accessibility Scanner's alt text plugin uses a combination of deterministic rules and an optional alt-text-quality check to evaluate the quality of alt text. The deterministic rules are designed to catch obvious errors, such as missing alt text, filenames, placeholders, generic words, and repeated alt text. However, these rules are not perfect and can produce false positives. For example, a row of five star-shaped icons with the same alt text will be flagged as an error, even if the alt text is descriptive in context.
Layout Matters
The plugin's repetition rule was initially designed to flag repeated alt text in document order. However, this approach had some issues. For example, a footer and header logo might be flagged as repeated alt text, even if they are not adjacent on the page. To address this issue, the plugin now checks the page layout and only extends a run when the gap between two bounding boxes is small compared to the boxes themselves.
Getting a Model to Act Like a Reviewer
The optional alt-text-quality check uses a model to evaluate the quality of alt text. The model is trained on a dataset of images with their corresponding alt text and surrounding context. The plugin extracts page context, including the nearest heading, page title, <figcaption>, whether the image sits inside a link or button, and up to 600 characters of nearby prose. The link signal matters most, as when an image is a link's only content, its alt becomes the link's accessible name. The right alt then names the destination instead of describing the picture.
Key points
- The GitHub Accessibility Scanner's alt text plugin uses five deterministic rules to check for missing or poor alt text.
- The plugin also uses an optional alt-text-quality check that extracts page context to determine the quality of alt text.
- The plugin's repetition rule now checks page layout instead of document order.
- The plugin uses a model to evaluate the quality of alt text in the optional alt-text-quality check.
The development of the alt text plugin is a step towards improving accessibility on the web. With this plugin, developers can catch and fix obvious errors in alt text, making it easier for users with visual impairments to navigate the web.
However, there is still a long way to go in improving alt text quality. Many images on the web still lack alt text or have undescriptive alt text. The plugin's reliance on deterministic rules and a model may also lead to false positives and false negatives.