More than one in four images on the web’s most popular home pages have alt text that’s missing, vague, or copied from adjacent images.
That’s from WebAIM’s 2026 WebAIM Million report, which found that alt text,an HTML attribute containing text describing the content of an image, was missing on 16.2% of images across the top million home pages.
Among the images that did have alt text, another 10.8% provided an undescriptive attribute, such as , a raw filename, or a description duplicated from a neighbor.
While automated tooling reliably flags missing alt text, it isn’t as good at fixing poorly written alt text.
Most alt text checkers test whether an accessible name for an image exists, not whether the provided alt text says anything useful about the associated image, and that’s a deliberate design choice: a quality-oriented rule with false positives is a rule teams switch off.
So passes.
So does the same on five different star-shaped icons.
We built an alt text plugin for the GitHub Accessibility Scanner to help improve your alt text.
This post covers where we drew the line between what a checker can prove and what it can only suspect, why our worst bug turned out to be a layout problem rather than a parsing one, and what changed once we let a model into the loop.
If you’re building automated checks of your own, for accessibility or otherwise, the tradeoffs should transfer.
Proving a string is wrong without seeing the picture Presence of alt text is an objective fact; the attribute is there or it isn’t.
Quality is often a judgment call.
A machine can’t prove whether a sentence adequately describes a picture in context from markup.
However, not all quality is subjective.
There’s several checks you can perform based on the alt text alone, with no need to consult the image content: The attribute is absent (not empty) or whitespace-only.
The alt is a filename, such as , .
The alt is a placeholder somebody meant to replace, such as , .
The alt is one generic word naming the medium instead of the content, such as , , .
The same alt repeats across adjacent images.
Every one of those is a claim about a string, and that became our dividing line.
Five deterministic rules run by default which need no credentials for running AI models or network calls.
One opt-in rule calls a model with provided image content and surrounding context, for judgments an alt text string can’t support on its own.
First, we had to determine which images to judge on a scanned webpage.
We use Playwright’s role-based locator rather than , so anything not included in the browser’s accessibility tree drops out, including anything carrying .
That last exclusion matters most.
An empty alt is the author explicitly saying the image is decorative, and flagging it would punish exactly the behavior you want to encourage.
So, how strict should it be?
A quality checker lives or dies on false positives, so we chose closed sets over clever heuristics.
The vague-alt rule normalizes a string, then checks it against a curated list of words that carry no information on their own.
It fires only on an exact match: gets flagged. doesn’t.
Rules this literal miss plenty of bad alt text.
We took the miss over the false positive, because a reliable checker that developers enable beats one that gets switched off.
Repetition is a layout problem, not a DOM problem Repeated alt text presented an interesting problem.
Picture a row of five star-shaped icons that each say .
A screen reader user hears the same thing five times and learns nothing new from four of them.
Our first version walked the images in document order and flagged any run sharing the same normalized alt.
It caught things it shouldn’t have.
For example, a footer “GitHub” logo and a header “GitHub” logo might sit next to each other in the extracted list but nowhere near each other on screen, so nobody experiences them as a group.
What matters is where images land on screen, not where they sit in the markup.
So the rule now checks page layout, and only extends a run when the gap between two bounding boxes is small compared to the boxes themselves: Two details worth noting: The multiplier is a judgment call, not a number we derived from anything.
It’s the kind of value you tune against real pages instead of trusting from a spec.
When either image has no measurable box, the check fails open and the run continues.
A missing finding is invisible; a wrong one isn’t.
Getting a model to act like a reviewer, not a critic Deterministic rules only need the alt string.
Anything smarter needs to know what the page is about, and none of that is tracked by the image element.
Whether is fine depends entirely on what surrounds it: on a generic mood shot, it’s probably works.
But under a heading where a specific person is named, it doesn’t provide enough detail.
In our optional check, we extract page context alongside each image: the nearest heading, the page title, any , whether the image sits 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.
The right alt then names the destination instead of describing the picture.
One caution: The plugin only records that an image sits inside a link.
We don’t check whether it’s the link’s only content, which is the part that actually turns alt into a link name.
So right now both cases look identical to the model.
That context, the alt, and the image go to a vision model through GitHub Models.
Our failure modes were rarely the model misreading a picture.
They were the model having opinions.
Given perfectly good alt text, our first version of the checker would suggest different alt text, because “could this be better?” is a question a language model always answers yes to.
Every image becomes a finding, so the signal disappears.
Three changes fixed it: A decision procedure instead of an instruction.
The prompt walks four ordered steps, stops at the first that matches, and emits that step’s verdict: decorative, redundant with a caption, functional, or informative.
Explicit anti-nitpick rules.
Trust the author’s framing.
Separate redundant prefixes (“Image of…”) from semantic ones (“Photograph of…”).
Treat a short alt as correct when the surrounding prose already analyzes the image.
Structured output with a forced field order, so is generated before and the model has to build an argument before it picks a label.
None of that makes the model unfailingly correct.
It makes it consistent enough to iterate against.
The repository carries an offline grading harness built from published teaching material: WebAIM, the W3C images tutorial, and POET.
The rule and the harness share one prompt, so what you tune offline is what runs in CI.
That harness only tests the model’s judgment, though, not the whole pipeline.
A case can score perfectly there and never reach the model in a real scan.
Sending images to a model is a privacy and cost decision The moment a check calls an external model with webpage data, it stops being just a lint rule and requires careful data flow design.
A few things follow from that: The rule is off by default.
It won’t run unless you deliberately enable it in your plugin configuration, and it needs a token with access to GitHub Models.
URLs get redacted.
Image URLs and link s often carry signed CDN tokens or session identifiers, so query and fragment are stripped from anything entering the model context or the rule’s error logs.
For the same reason, and are replaced with in the markup we send.
Everything in that context window is untrusted input.
Titles, headings, and prose all come from the page being scanned, and a page can contain text written