Multiple in 4 pictures on the internet’s hottest house pages have alt textual content that’s lacking, obscure, or copied from adjoining pictures.
That’s from WebAIM’s 2026 WebAIM Million report, which discovered that alt textual content,an HTML attribute containing textual content describing the content material of a picture, was lacking on 16.2% of pictures throughout the highest million house pages. Among the many pictures that did have alt textual content, one other 10.8% supplied an undescriptive attribute, comparable to alt=”picture”, a uncooked filename, or an outline duplicated from a neighbor.
Whereas automated tooling reliably flags lacking alt textual content, it isn’t nearly as good at fixing poorly written alt textual content. Most alt textual content checkers take a look at whether or not an accessible title for a picture exists, not whether or not the supplied alt textual content says something helpful in regards to the related picture, and that’s a deliberate design selection: a quality-oriented rule with false positives is a rule groups swap off. So alt=”IMG_2847.png” passes. So does the identical alt=”3/5 stars” on 5 totally different star-shaped icons.
We constructed an alt textual content plugin for the GitHub Accessibility Scanner to assist enhance your alt textual content. This publish covers the place we drew the road between what a checker can show and what it may solely suspect, why our worst bug turned out to be a structure drawback relatively than a parsing one, and what modified as soon as we let a mannequin into the loop.
Should you’re constructing automated checks of your personal, for accessibility or in any other case, the tradeoffs ought to switch.
Proving a string is flawed with out seeing the image
Presence of alt textual content is an goal reality; the attribute is there or it isn’t. High quality is commonly a judgment name. A machine can’t show whether or not a sentence adequately describes an image in context from markup.
Nevertheless, not all high quality is subjective. There’s a number of checks you’ll be able to carry out primarily based on the alt textual content alone, without having to seek the advice of the picture content material:
The attribute is absent (not empty) or whitespace-only.
The alt is a filename, comparable to hero.png, IMG_2847.jpg.
The alt is a placeholder any person meant to interchange, comparable to TODO, tbd.
The alt is one generic phrase naming the medium as a substitute of the content material, comparable to picture, brand, chart.
The identical alt repeats throughout adjoining pictures.
Each a type of is a declare a few string, and that grew to become our dividing line. 5 deterministic guidelines run by default which want no credentials for working AI fashions or community calls. One opt-in rule calls a mannequin with supplied picture content material and surrounding context, for judgments an alt textual content string can’t assist by itself.
First, we needed to decide which pictures to guage on a scanned webpage. We use Playwright’s role-based locator relatively than querySelectorAll(‘img’), so something not included within the browser’s accessibility tree drops out, together with something carrying alt=””. That final exclusion issues most. An empty alt is the writer explicitly saying the picture is ornamental, and flagging it might punish precisely the habits you need to encourage.
So, how strict ought to it’s? A high quality checker lives or dies on false positives, so we selected closed units over intelligent heuristics. The vague-alt rule normalizes a string, then checks it in opposition to a curated listing of phrases that carry no data on their very own. It fires solely on an actual match:
alt=”picture” will get flagged.
alt=”picture of the login display with the SSO button highlighted” doesn’t.
Guidelines this literal miss loads of unhealthy alt textual content. We took the miss over the false optimistic, as a result of a dependable checker that builders allow beats one which will get switched off.
Repetition is a structure drawback, not a DOM drawback
Repeated alt textual content offered an fascinating drawback. Image a row of 5 star-shaped icons that every say “3/5 stars”. A display reader consumer hears the identical factor 5 occasions and learns nothing new from 4 of them.
Our first model walked the photographs in doc order and flagged any run sharing the identical normalized alt. It caught issues it shouldn’t have. For instance, a footer “GitHub” brand and a header “GitHub” brand may sit subsequent to one another within the extracted listing however nowhere close to one another on display, so no person experiences them as a gaggle.
What issues is the place pictures land on display, not the place they sit within the markup. So the rule now checks web page structure, and solely extends a run when the hole between two bounding containers is small in comparison with the containers themselves:
const largerDim = Math.max(a.boundingBox.width, a.boundingBox.peak,
b.boundingBox.width, b.boundingBox.peak)
return hole > GAP_MULTIPLIER * largerDim
Two particulars value noting:
The multiplier is a judgment name, not a quantity we derived from something. It’s the sort of worth you tune in opposition to actual pages as a substitute of trusting from a spec.
When both picture has no measurable field, the verify fails open and the run continues. A lacking discovering is invisible; a flawed one isn’t.
Getting a mannequin to behave like a reviewer, not a critic
Deterministic guidelines solely want the alt string. Something smarter must know what the web page is about, and none of that’s tracked by the picture ingredient. Whether or not alt=”a smiling particular person” is ok relies upon totally on what surrounds it: on a generic temper shot, it’s in all probability works. However underneath a heading the place a selected particular person is known as, it doesn’t present sufficient element.
In our non-compulsory alt-text-qualitycheck, we extract web page context alongside every picture: the closest heading, the web page title, any
The hyperlink sign issues most, as a result of when a picture is a hyperlink’s solely content material, its alt turns into the hyperlink’s accessible title. The correct alt then names the vacation spot as a substitute of describing the image.
One warning: The plugin solely data that a picture sits inside a hyperlink. We don’t verify whether or not it’s the hyperlink’s solely content material, which is the half that really turns alt right into a hyperlink title. So proper now each circumstances look similar to the mannequin.
That context, the alt, and the picture go to a imaginative and prescient mannequin via GitHub Fashions. Our failure modes had been not often the mannequin misreading an image. They had been the mannequin having opinions. Given completely good alt textual content, our first model of the checker would counsel totally different alt textual content, as a result of “may this be higher?” is a query a language mannequin all the time solutions sure to. Each picture turns into a discovering, so the sign disappears.
Three modifications fastened it:
A choice process as a substitute of an instruction. The immediate walks 4 ordered steps, stops on the first that matches, and emits that step’s verdict: ornamental, redundant with a caption, purposeful, or informative.
Specific anti-nitpick guidelines. Belief the writer’s framing. Separate redundant prefixes (“Picture of…”) from semantic ones (“{Photograph} of…”). Deal with a brief alt as appropriate when the encircling prose already analyzes the picture.
Structured output with a pressured subject order, so reasoning is generated earlier than verdict and the mannequin has to construct an argument earlier than it picks a label.
None of that makes the mannequin unfailingly appropriate. It makes it constant sufficient to iterate in opposition to. The repository carries an offline grading harness constructed from revealed instructing materials: WebAIM, the W3C pictures tutorial, and POET. The rule and the harness share one immediate, so what you tune offline is what runs in CI. That harness solely assessments the mannequin’s judgment, although, not the entire pipeline. A case can rating completely there and by no means attain the mannequin in an actual scan.
Sending pictures to a mannequin is a privateness and value choice
The second a verify calls an exterior mannequin with webpage knowledge, it stops being only a lint rule and requires cautious knowledge circulation design. A number of issues observe from that:
The rule is off by default. It gained’t run until you intentionally allow it in your plugin configuration, and it wants a token with entry to GitHub Fashions.
URLs get redacted. Picture URLs and hyperlink hrefs typically carry signed CDN tokens or session identifiers, so question and fragment are stripped from something getting into the mannequin context or the rule’s error logs. For a similar cause, src and srcset are changed with (omitted) within the markup we ship.
Every little thing in that context window is untrusted enter. Titles, headings, and prose all come from the web page being scanned, and a web page can comprise textual content written to steer a mannequin. Structured output constrains the form of a response, not the reasoning behind it.
One warning, as a result of that listing is simple to over-read: findings nonetheless carry the actual web page URL and unique HTML into the scanner’s regular reporting pipeline. That’s on goal, since you’ll be able to’t repair a picture you’ll be able to’t find. Redaction narrows what reaches the mannequin and the logs, not what lands in your personal points. And in case you arrange Azure AI Imaginative and prescient credentials, an non-compulsory OCR pre-pass sends picture bytes to a second place. Nothing requires Azure, however a data-flow overview must cowl each paths.
Value follows the identical form. Within the frequent case that is one mannequin name per picture per scan, which on an image-heavy web site dominates the price of the entire run. That’s cause sufficient to place it on a schedule relatively than on each commit.
What this nonetheless can’t do
The deterministic guidelines are literal. They catch alt textual content that’s clearly unwritten, not alt textual content that’s fluent and flawed. Additionally they learn the alt attribute relatively than the computed accessible title, so an aria-label that fixes the issue gained’t cease the discovering.
The model-backed rule produces false positives. Each discovering is a immediate for human consideration, not a verdict.
Silence isn’t protection. That rule re-fetches pictures exterior the browser session, so something behind authentication can fail to load. Fetch and mannequin errors are logged and skipped, which implies a web page can come again clear as a result of nothing acquired checked.
Instructed alt textual content is a draft. A mannequin that sees the picture and some close by phrases can’t account on your viewers, your own home type, or the job that picture is doing on the entire web page.
Some findings double up with the scanner’s built-in checks, since our missing-alt rule covers the identical floor.
We solely verify HTML tags. SVG, position=”img” containers, CSS backgrounds, and canvas aren’t lined but.
That is new code with restricted real-world suggestions. Guidelines like these enhance after they meet the number of markup and content material discovered throughout actual websites. This plugin hasn’t had that but, so deal with early findings accordingly.
Passing isn’t conformance. Automated checks are a ground. Testing with individuals who use assistive tech is the purpose.
What we’d let you know in case you’re constructing one thing comparable
Separate what you’ll be able to show from what you’ll be able to solely suspect, and provides them totally different defaults. Checks that show one thing must be low cost, predictable, and on by default. Checks that solely suspect one thing must be opt-in, and may learn as a suggestion relatively than a verdict. Then, ask what the consumer experiences relatively than what the DOM says. Each hole nonetheless open on this plugin has that second form. We report that a picture is inside a hyperlink, not that it’s the hyperlink. We learn an attribute, not a computed title.
That distance is the actual boundary, and a greater mannequin doesn’t shut it. Deciding what the performance of a picture is for a consumer who can’t see it nonetheless requires human judgment. What automation buys you is ensuring that human is giving the correct pictures a second examination.
Attempt the alt-text plugin in your accessibility scanning workflow. If it tells you the flawed factor, please report it. Open a difficulty with the discovering and, if public, a hyperlink to the affected web page.
Written by
