Alt Text Passes Automated Checks. That Does Not Mean It Works.

More than one in four images on the web's most popular home pages have alt text that is missing, vague, or copied from a neighboring image, according to WebAIM's 2026 Million report. That figure covers the top million home pages: 16.2% of images have no alt text at all, and a further 10.8% carry descriptions so generic they tell screen reader users nothing useful. GitHub's engineering team wrote about how they built an alt text plugin for the GitHub Accessibility Scanner to close that gap, and the design decisions transfer to any team building automated quality checks.

What happened

Fact	Detail
Source	WebAIM 2026 Million report, top 1 million home pages
Images missing alt text	16.2%
Images with vague or duplicated alt text	10.8%
Total with bad or absent alt text	More than 1 in 4
Plugin	Alt text plugin for GitHub Accessibility Scanner
Default rules (deterministic)	5, no API credentials needed
Optional AI rule context window	Up to 600 characters of nearby prose per image

Automated accessibility tools reliably catch a missing alt attribute. They are much worse at catching a bad one. A checker that flags alt="IMG_2847.png" or alt="image" as acceptable is passing something that gives a screen reader user zero useful information. GitHub’s team set out to build something stricter without triggering so many false positives that developers turn it off.

Why passing an automated check is not the same as being accessible

Most alt text validators check for the presence of an accessible name, not its quality. That is a deliberate choice by tool builders: a rule with too many false positives gets disabled. So alt="IMG_2847.png" passes. Five star icons each carrying alt="3/5 stars" pass. The check is satisfied; the user experience is not.

GitHub’s plugin draws a hard line between what a checker can prove and what it can only suspect. Everything provable from the text string alone runs as a deterministic rule. Everything that needs to see the image runs as an optional, AI-assisted rule.

The five deterministic rules

These run by default with no API key or network call required:

1. The attribute is absent or contains only whitespace.
2. The alt is a raw filename (for example, hero.png or IMG_2847.jpg).
3. The alt is an unfilled placeholder such as TODO or tbd.
4. The alt is a single generic word naming the medium rather than the content: image, logo, chart.
5. The same alt text repeats across adjacent images on screen.

The vague-alt rule normalizes the string and checks it against a curated list of words with no information value. It fires only on an exact match. alt="image" is flagged. alt="image of the login screen with the SSO button highlighted" is not. The team explicitly chose to miss some bad alt text rather than generate false positives that erode trust in the tool.

Why repeated alt text is a layout problem, not a markup problem

The repeated-alt rule turned out to be the trickiest to get right. A naive implementation walks images in document order and flags any run with the same normalized alt. The problem: a footer logo and a header logo with identical alt text might be adjacent in the DOM but nowhere near each other on screen. A screen reader user never experiences them as a group.

The fix was to check bounding box positions rather than document order. The rule only extends a “repeated” run when the gap between two boxes is small relative to the size of the boxes themselves. The team used a multiplier constant tuned against real pages, and when either image has no measurable bounding box, the check fails open (the run continues) rather than firing a false positive. A missed finding is invisible; a wrong one damages trust.

When does the AI rule kick in?

The optional alt-text-qualitycheck rule handles judgments that require knowing what surrounds an image. Whether alt="a smiling person" is adequate depends on context: it may be fine on a generic stock photo but inadequate under a heading that names a specific individual.

To give the model enough context, the plugin extracts, per image:

• The nearest heading
• The page title
• Any <figcaption> element
• Whether the image is inside a link or button (this matters most: when an image is a link’s only content, its alt becomes the link’s accessible name and should describe the destination, not the picture)
• Up to 600 characters of nearby prose

This rule requires API credentials and a network call, which is why it is opt-in. The design keeps fast, zero-cost checks separate from slower, model-assisted ones, something worth copying if you are building your own quality pipeline.

Why it matters

For teams working on UI and UX design, this is a useful reminder that accessibility compliance and accessibility quality are not the same thing. Passing a Lighthouse audit or an axe scan does not mean your images are actually usable by someone relying on a screen reader. The gap between “no violations found” and “genuinely accessible” is where most sites live.

There is also an SEO angle. Search engines use alt text as a signal for image indexing and relevance. Generic filenames and placeholder text cost you discoverability in image search, not just accessibility points. If you have been wondering whether your SEO work is leaving image traffic on the table, alt text quality is a quick place to look.

Our take

The GitHub team’s core insight is worth repeating: a reliable checker developers leave on beats a smart checker developers turn off. That tradeoff applies well beyond alt text. We see the same pattern with linting rules, performance budgets, and ad quality checks. If a rule has too many false positives, it gets disabled, and then it catches nothing at all.

The bounding box fix for repeated alt text is the most practically useful detail here. Document order is not user experience, and treating them as the same thing is how tools generate noise that trains teams to ignore warnings. If you are auditing a site with icon sets, star ratings, or any repeated decorative patterns, check whether your current tool is doing layout-aware comparison or just walking the DOM.

The AI-assisted rule is interesting but its value depends entirely on the model’s context window and the quality of surrounding markup. Pages with thin or missing semantic structure will give the model very little to work with. Fix your heading hierarchy and your figcaptions first, then let the model weigh in.

What to do about it

1. Run WebAIM’s WAVE tool or axe on your key pages to get a baseline count of missing alt attributes.
2. Grep your codebase for common placeholders: alt="image", alt="logo", alt="TODO", raw filenames with extensions.
3. Check any icon sets or star-rating components for repeated identical alt text across adjacent elements.
4. For images inside links with no accompanying link text, make sure the alt describes the destination, not the visual.
5. Consider adding GitHub’s Accessibility Scanner plugin to your CI pipeline for ongoing coverage.

A site that passes automated accessibility checks but still has one in four images with broken alt text is a good reminder: audits set a floor, not a ceiling.

Source: GitHub Blog