GitHub accessibility scanner gains alt-text checks that judge quality, not just presence

The gap it fills

GitHub has released an alt-text plugin for its Accessibility Scanner that goes beyond confirming whether alt text exists and starts asking whether it is actually useful. In a post on the GitHub Blog, the engineering team behind the plugin explains how it separated what a checker can prove about a string from what only a model can estimate.

According to the GitHub Blog, more than one in four images on the web's most popular home pages carry alt text that is missing, vague, or copied from a neighboring image. The numbers come from WebAIM's 2026 WebAIM Million report, which found the attribute absent on 16.2% of images across the top million home pages, and found that another 10.8% of the images that did have alt text offered nothing useful: a filename, alt="image", or a description duplicated from an adjacent image.

Existing tooling catches the missing cases reliably. What it generally does not do is evaluate quality. Most checkers only confirm that an accessible name exists, and the GitHub Blog argues this is deliberate, since a quality rule that produces false positives is a rule teams turn off. As a result, alt="IMG_2847.png" passes, and so does the same "3/5 stars" applied to five star-shaped icons.

Five deterministic rules

The plugin ships five checks that run by default and require no network access or model credentials. They flag alt attributes that are whitespace-only, contain filenames such as hero.png, contain placeholders like TODO, consist of a single generic word such as "image", "logo" or "chart", or repeat across adjacent images.

To decide which images to judge, the scanner uses Playwright's role-based locator rather than querying the DOM directly, so anything outside the browser's accessibility tree drops out, including empty alt attributes. That exclusion is deliberate: an empty alt is the author declaring an image decorative, which is behavior a checker should encourage rather than punish.

The vague-word rule normalizes the string and compares it against a curated list, firing only on exact matches. "image" gets flagged; "image of the login screen with the SSO button highlighted" does not. GitHub concedes that such a literal approach misses plenty of genuinely bad alt text, but says a dependable checker that developers keep enabled beats a cleverer one they disable.

Repetition needed a layout fix

The repeated-alt rule produced what the team calls its worst bug, and it was a layout problem rather than a parsing one. The first version flagged runs of identical alt text in document order, which meant a header logo and a footer logo both reading "GitHub" could be treated as duplicates even though no user experiences them as a group.

The rule now compares bounding boxes and only extends a run when the gap between two images is small relative to the images themselves. GitHub notes that the distance multiplier is a judgment call tuned against real pages rather than a value derived from a specification, and that the check errs toward silence when an image has no measurable box, since an overlooked case is invisible while a wrong flag erodes trust.

An optional model in the loop

One opt-in rule sends the image, its alt text, and surrounding context to a vision model through GitHub Models. That context includes the nearest heading, the page title, any figcaption, 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 plugin has a known limitation here: it records that an image sits inside a link but not whether it is the link's only content, so both cases look identical to the model.

The team's main failure mode was not the model misreading pictures but the model offering unsolicited rewrites. When asked whether alt text could be improved, a language model tends to answer yes, so every image became a finding and the signal collapsed. Three changes addressed it: a decision procedure that walks four ordered steps (decorative, redundant with a caption, functional, informative) and stops at the first match; explicit anti-nitpick rules that prefer the author's intent over the model's taste; and structured output that forces reasoning to be generated before the verdict. An offline grading harness built from WebAIM, the W3C images tutorial, and POET shares the same prompt as the live rule, so offline tuning matches CI behavior, though the harness tests only the model's judgment and not the full pipeline.

The GitHub Blog closes by framing the opt-in rule's tradeoff: once a check sends webpage data to an external model, it raises privacy and cost questions that a purely local lint rule never does.

Why it matters

Automated accessibility testing has a well-known ceiling: it verifies presence, not usefulness. The vague and duplicated share of the alt text problem is invisible to conventional checkers, and GitHub's plugin is a concrete attempt to close that gap without shipping a checker that cries wolf. The design decisions also generalize beyond accessibility: closed word lists instead of heuristics, layout-aware repetition detection, erring toward silence on missing data, and prompting a model with a decision procedure rather than an open-ended question. For teams building automated checks of their own, the tradeoffs GitHub describes transfer directly.