Automated Alt Text Checks Aren't Enough
Image alt texts on websites are often missing or inadequate.
1Alt Text Issues Are Common
According to WebAIM's 2026 report, 16.2% of images on popular websites lack alt text. Alt text is an HTML attribute that describes the content of images. In addition to missing ones, 10.8% contain vague or copied text from neighboring images. While automated tools can detect missing alt text, they fall short in fixing poorly written text.
2Limitations of Automated Checks
Most alt text checkers test whether an image has an accessible name, but they don't verify if the text provides useful information about the image. This is a deliberate design choice: a rule with false positives is often disabled by teams. For example, 'IMG_2847.png' or '3/5 stars' on five star-shaped icons are considered valid.
3GitHub Accessibility Scanner Plugin
A plugin was developed for the GitHub Accessibility Scanner to improve alt text quality. This plugin defines the line between what a checker can prove and what it can only suspect. The worst bug turned out to be a layout issue rather than a parsing one. Changes after introducing the model are also discussed in this post.
4Challenges in Quality Control
The presence of alt text is an objective fact; the attribute is either there or not. However, quality is often a matter of judgment. A machine cannot prove whether a sentence adequately describes an image in context. But not all quality is subjective. There are several checks you can perform based on the alt text alone.
5Deterministic Rules
There are five deterministic rules for alt text: the attribute is missing or whitespace-only, it's a filename (e.g., 'hero.png'), it's a placeholder (e.g., 'TODO'), it's a generic word naming the medium (e.g., 'image'), or it repeats across adjacent images. These rules form our dividing line.
6Page Layout Issue
Repeated alt text presents an interesting problem. For example, if five star-shaped icons each say '3/5 stars,' a screen reader user hears the same thing five times and learns nothing new from four of them. The first version flagged any run sharing the same normalized alt in document order, but it caught things it shouldn't have.
7The Role of the Model
Deterministic rules only need the alt text string. Anything smarter needs to know what the page is about, none of which is tracked by the image element. Whether 'a smiling person' is fine depends entirely on its context: it probably works on a generic mood shot but doesn't provide enough detail under a heading naming a specific person.
8Importance of Context
In the optional alt-text-quality check, page context is extracted alongside each image: the nearest heading, page title, figcaption, whether the image is inside a link or button, and up to 600 characters of nearby prose. The link signal matters most because when an image is a link's only content, its alt becomes the link's accessible name.
9Model's Limitations
The plugin only records that an image is inside a link. It doesn't check whether it's the link's only content, which is what turns alt into a link name. Currently, both cases look identical to the model. This context, the alt text, and the image are sent to a vision model.
10Conclusion and Recommendations
Automated checks alone are not enough to improve alt text quality. Teams should prefer closed sets to avoid false positives. A reliable checker is one that developers enable. The model's role is to act like a reviewer, not a critic.
11Future Steps
More research and development are needed to improve alt text quality. The model needs to better understand context and reduce false positives. Teams should be more meticulous in writing alt text and use automated checks as a complement.
Original article: The GitHub Blog — Otomatik Alt Metin Kontrolleri Yeterli Değil