Write meaningful image alt text

What this check does

Walks every <img> element on the page and inspects the alt attribute. The check fails when the alt is one of: a filename (IMG_2837.jpg, hero-final-v2.png), a generic placeholder (image, picture, photo, img), a single character (x, .), or starts with “Image of” / “Picture of” — assistive tech already announces the role as “graphic,” so prefacing the description is redundant noise.

This is the companion check to Image alt text, which only checks for presence. This check rates quality.

Why it matters

Bad alt text actively hurts the experience.

• Screen-reader users hear it instead of seeing the image. “IMG underscore two eight three seven dot jay-peg” is the worst possible outcome — the assistive tech reads the filename letter by letter.
• Search engines use alt text as a ranking signal for image search. Filenames as alt text waste the slot.
• AI extractors (multimodal LLMs that scan a page) cite alt text when describing the page. A page where every image alt is hero.jpg reads as low-effort to both humans and AI.

The fix is not “add more words.” It’s “describe the image, in context, in plain language.”

How to fix it

Open each flagged image and rewrite the alt to describe what the image conveys in the context where it appears. Same image, different page, different alt — that’s normal.

Decorative images (logo borders, dividers, hero patterns) — empty alt:

<img src="/divider.svg" alt="">

alt="" tells screen readers “skip this; it carries no meaning.” Don’t omit the attribute entirely — the absence of alt makes some readers fall back to announcing the filename.

Informative images — describe the function or content:

<!-- Bad -->
<img src="/charts/q3.png" alt="chart">
<img src="/team/jane.jpg" alt="IMG_2837.jpg">
<img src="/screenshot.png" alt="Image of the dashboard">

<!-- Good -->
<img src="/charts/q3.png" alt="Q3 revenue up 38% over Q2, driven by enterprise tier">
<img src="/team/jane.jpg" alt="Jane Patel, CTO">
<img src="/screenshot.png" alt="MetricSpot dashboard showing five passing checks">

Linked images — describe the link destination, not the picture:

<a href="/docs/">
  <img src="/icons/book.svg" alt="Documentation">
</a>

Complex images (charts, infographics) — describe the data, then link out:

<img src="/q3-funnel.png" alt="Conversion funnel: 1000 visits → 230 signups → 28 paid (2.8%).">
<a href="/q3-funnel-full.txt">Full data table</a>

CMS / framework patterns.

• WordPress — Media Library → click any image → “Alternative Text” field. Audit existing posts via Tools → Site Health → Images without alt text.
• Astro / Next.js Image — <Image alt={...} /> is required at the type level; TypeScript will refuse to build without one.
• React — write a small lint rule (jsx-a11y/alt-text from eslint-plugin-jsx-a11y) and fail CI on missing or filename-like alts.

Audit yourself. Open DevTools console and run:

[...document.images]
  .filter(i => !i.alt || /^(image|img|picture|photo|\.|x)$/i.test(i.alt.trim()) || /\.(jpg|jpeg|png|gif|webp|svg)$/i.test(i.alt))
  .map(i => i.src);

Anything in the result list is a junk alt.

Frequently asked questions

Should every image have alt text?

Yes, but it can be empty (alt="") for decorative ones. The attribute itself must be present — absence is what tools flag as a violation.

How long should alt text be?

As long as it needs to be, as short as it can be. One sentence is typical; a chart might need two. Avoid the 125-character “limit” you may see quoted — that’s a screen-reader buffer rumor, not a real constraint.

Should I include the word “image”?

No. Screen readers already announce the role (“graphic”). Saying “Image of a dog” makes the reader say “graphic, image of a dog.” Just write “Golden retriever puppy chewing a shoe.”