Image Alt Text — Catching Content Images That Ship With No Description

What it detects

content/image-alt-text reads every <img> tag in a page's HTML and asks one question of each: is this image content-bearing, and if so does it have an alt attribute at all? The rule parses the tag's attributes, then skips any image you have deliberately marked as decorative — role="presentation" or role="none", aria-hidden="true", or an explicit empty alt="". An empty alt is treated as an intentional signal that the image carries no information, so it is accepted, never flagged.

The rule fires only when the alt attribute is entirely missing from a content-bearing image — not when it is present but short, and not on images you told it to ignore. For each page it counts how many qualifying images lack alt, divides by the total content-bearing images on that page, and emits one summary finding per URL rather than one line per image. A sample of up to three image sources is attached so you can find the offenders fast.

Severity scales with how widespread the gap is on the page: when at least half of a page's content images are missing alt the finding is a warning; below that ratio it drops to info, on the logic that a single stray image is a smaller signal than a template that never binds the slot.

Why it matters

Alt text is the only description a screen reader, a slow connection, or a crawler has when the pixels do not load. WCAG 2.1 success criterion 1.1.1 (Non-text Content) requires a text alternative for every image that conveys information, which is why a missing alt is both an accessibility defect and, in many jurisdictions, a legal exposure. The same string is what Google Images indexes against — a product shot with no alt is a product shot Google cannot read, and the image-search traffic that would have found it goes to a competitor whose markup is complete.

For a programmatic site the failure is rarely one careless image. It is a template whose alt slot was left at a literal default — or left blank — and then iterated across every page in the catalog, so a single missing binding becomes thousands of undescribed images at once. That is exactly the shape this rule is built to surface: a per-page ratio that climbs toward 100% across a cluster is the tell that the data source never fed the alt attribute, the same way it feeds the heading and the body copy.

The fix costs almost nothing in content terms. Binding a real, per-image description from the same data the rest of the page already uses closes the accessibility gap and opens the Google Images channel in one edit.

A page that fails

A page that passes

How to fix it

1. 1Add a descriptive alt attribute to every content-bearing <img> that conveys information — describe what the image shows, not the file name, and keep it to a natural phrase a screen reader can speak.
2. 2For purely decorative images — dividers, background flourishes, spacer graphics — set alt="" explicitly or add aria-hidden="true" so the rule recognises the omission as intentional rather than forgotten.
3. 3In a pSEO template, bind the alt text from the same data source that fills the rest of the page — the product name, the city, the edition size — so each generated image gets its own description instead of a static default.
4. 4Never leave a templated alt at a literal placeholder like alt="image" or the entity name alone; a default that repeats across every page is its own duplicate-content tell even though it technically passes this rule.
5. 5Re-run the audit after fixing the template binding — because the finding is per page, a single corrected template binding clears the warning across the entire catalog at once.
6. 6Spot-check with a screen reader or the browser accessibility tree to confirm the descriptions actually make sense when read aloud, not just that the attribute is present.

SpamBrain context

Alt text sits at the intersection of accessibility law and search visibility, which is why it is worth getting right independently of any spam policy. The Web Content Accessibility Guidelines have required a text alternative for non-text content since WCAG 1.0 in 1999, carried forward unchanged into WCAG 2.0 (December 11, 2008) and WCAG 2.1 (June 5, 2018) as success criterion 1.1.1 — the most-cited clause in accessibility litigation. Google's own Image SEO documentation states plainly that alt text is how the crawler understands an image's subject and is a primary factor in Google Images ranking.

content/image-alt-text (in @pseolint/core, MIT-licensed at github.com/ouranos-labs/pseolint) is a content-category check, not a spam-weighted one. It does not claim a penalty; it surfaces a quality and accessibility gap that programmatic templates produce at scale when the image slot is the one field the data binding forgot. The signal it shares with the rest of the suite is templating: a missing alt that repeats across a whole catalog is the same mass-production fingerprint that spam/template-diversity and content/unique-value read elsewhere, just expressed in the one attribute crawlers and assistive technology both depend on.

Frequently asked questions

Does the rule flag every image without alt text?

No. It skips images you have explicitly marked as decorative — role="presentation", role="none", aria-hidden="true", or an empty alt="". An empty alt is read as a deliberate signal that the image carries no information, so it is accepted. The rule fires only when the alt attribute is entirely missing from a content-bearing image, because a missing attribute means the author never decided whether the image was informative or decorative.

Why is alt="" treated as passing rather than failing?

Because an explicit empty alt is the correct WCAG-recommended markup for a purely decorative image — it tells a screen reader to skip the image entirely instead of announcing a file name. Flagging it would push authors toward describing images that should stay silent, which harms accessibility. The rule distinguishes 'deliberately empty' from 'forgotten' by checking whether the attribute exists at all, and only the second case is a defect.

Why does severity change between warning and info?

The rule computes the share of a page's content images that are missing alt. When at least half are missing, the finding is a warning — that pattern almost always means a template never bound the slot, so it scales across the whole site. Below half, it drops to info, because a handful of stray images on an otherwise-complete page is a smaller, more isolated problem worth noting but not alarming over.

How should a pSEO template handle alt text for generated images?

Bind it from the same data source that fills the rest of the page. If each page renders a product name, a city, or an attribute from a record, the alt attribute should pull from that record too — alt="{productName} in {city}" — so every generated image gets a description as specific as the page. Leaving the slot at a static literal default produces thousands of identical, uninformative alts, which is its own templated-content signal even though it technically satisfies the presence check.

I run a fine-art print shop — how should I write alt text for a giclee listing?

Describe what the buyer is judging, not the file. For an archival giclee print, an alt like "Harbor Fog giclee print, 24x36 inch edition of 50, matte finish on cotton rag paper" carries the edition size, the aspect ratio, the paper stock, and the finish — the exact attributes a collector searches Google Images for. Mark the decorative gallery-wall mockup or the framing-corner flourish with aria-hidden="true", and bind the substantive description for each print from its catalog record so a 1,800-piece collection stays both accessible and indexable without a single hand-written attribute.

Related rules

• spam/thin-contentThin Content DetectionGoogle's Helpful Content System (rebuilt August 25, 2022) demoted an estimated 45% of low-effort pages in the March 5, 2024 scaled-content-abuse update — the spam/thin-content rule mirrors that floor by flagging every URL under 300 words of substantive body text (default), after stripping nav and footer chrome via SpamBrain-style readability heuristics.Read →
• content/unique-valueUnique Valuecontent/unique-value counts the distinct words on each page that appear on no other page in the audit, and fires an error below a 100-word floor — the page-specific-vocabulary test Google's scaled-content-abuse policy has applied since March 5, 2024 when it asks whether a URL adds anything genuinely new.Read →
• content/heading-structureHeading Structurecontent/heading-structure runs three checks on every page Google crawls — a missing H1 fires an error because it is almost always a CMS or template bug, two or more H1 elements raise a warning that the HTML5 outline and accessibility checkers both dislike, and any page past 600 words with no H2 sub-structure emits an info note about Featured Snippet eligibility.Read →