Image alt text auditor

Alt text serves two audiences at once: people using a screen reader and Google trying to understand what an image shows. This tool parses pasted HTML with the browser’s own DOMParser and checks every img tag’s alt attribute against Google’s documented guidance, plus a couple of its own heuristics for patterns Google has flagged as spam but never reduced to a formula.

What Google actually documents about alt text#

Google’s own image SEO guidance says to focus on useful, information-rich alt text that uses keywords appropriately and stays in context of the page, rather than treating alt text as a keyword slot. It separately advises against generic filenames, giving my-new-black-kitten.jpg as a good example against IMG00023.JPG as a bad one, and that same logic extends to alt text that is just a filename restated. Google’s spam policies go further and name keyword stuffing directly: filling an alt attribute with keywords is called out as a practice that produces a bad user experience and can get a site treated as spam. None of this amounts to a length limit or a maximum keyword count. It is guidance about writing for a reader first, not a threshold to hit.

What this tool checks, and which parts are Google’s rules versus its own guesses#

Two checks are direct reads of that documentation: an image with no alt attribute at all fails the basic requirement that alt text exist, and alt text that is a generic placeholder such as “image123” or a bare filename fails the descriptive-filename guidance. Both are labeled as following Google’s documentation because they map to a specific documented statement.

Two other checks are this tool’s own heuristics, and the results table says so on every flag. Google has never published an exact character count or repetition count that defines keyword stuffing in alt text, so this tool makes a judgment call: alt text that is nothing but a filename pattern gets flagged as filename-shaped, and alt text with a single word repeated three or more times across eight or more words gets flagged as possibly stuffed. Both exist to catch obvious cases, not to define a passing score, and both can be wrong on unusual real captions. Read the flag before rewriting solely to satisfy it.

Empty alt text gets its own, softer treatment. An alt="" is not flagged as an error here, because leaving alt text empty is the documented way to tell assistive technology that an image is purely decorative and can be skipped. Only a missing alt attribute, not an empty one, is treated as the accessibility and SEO problem.

Paste a real page’s markup to see where its images actually stand, then fix the missing and generic cases first since those map directly to Google’s documented guidance, and treat the heuristic flags as a second read rather than a verdict.