Writing Alt Text That Actually Works

1. What is the image-alt violation?

axe-core's image-alt rule fires when an <img> has no alt attribute, or an element with role="img" has no accessible name. Mapping is direct: WCAG 2.1 1.1.1 Non-text Content (Level A).

One critical distinction: alt="" (empty alt) and a missing alt are different. Empty alt explicitly marks the image as decorative and the screen reader skips it. A missing alt is “information present, undisclosed” — the screen reader falls back to reading the file name.

2. Why it matters

For a blind user, alt is the only bridge between the image and the page's meaning. Missing alt on a product card means the user has to guess what the product is from the caption. Missing alt on a blog diagram means half of the argument is just gone.

It isn't only about disabled users. Anyone whose image fails to load — slow connection, image blocker, missing file — sees the alt text instead. Search engines also ingest images largely through alt: a well-written one earns both accessibility and image-search traffic.

3. When does it fire?

1. No alt attribute at all: The most common offender. <img src="/banner.jpg"> violates the rule on every page.
2. Whitespace-only alt: alt=" " doesn't count as an accessible name in screen readers.
3. Meaningless CMS defaults: Auto-generated alt="image", alt="photo" tell users nothing.
4. SVG with no accessible name: Inline SVGs ignore the alt attribute. Use a <title> child or aria-label.
5. role="img" without a name: A div with a background image and role="img" still needs aria-label.

4. The fixes

4.1 Informational images

Product photo, in-article diagram, hero shot — anything that contributes meaning to the page needs alt that reflects what the image means in this context, not just what it is.

<img src="/IMG_2435.jpg" alt="IMG_2435">

<img
  src="/IMG_2435.jpg"
  alt="Blue wool sweater, 92cm chest"
>

4.2 Decorative images

Anything that's pure visual flourish and adds no information uses alt="". The screen reader skips it; image-alt passes.

<img src="/divider.svg" alt="" aria-hidden="true">

4.3 Functional images (inside button/link)

When an image is the sole content of a button or link, the alt must describe the action, not the picture. “Magnifying glass” is wrong. “Search” is right.

<button>
  <img src="/icons/search.svg" alt="Magnifying glass">
</button>

<button>
  <img src="/icons/search.svg" alt="Search">
</button>

4.4 Image redundant with adjacent text

When the image and a sibling text element say the same thing, set alt to empty. Otherwise the screen reader reads the same name twice.

<a href="/">
  <img src="/logo.svg" alt="Keysonar">
  <span>Keysonar</span>
</a>

<a href="/">
  <img src="/logo.svg" alt="">
  <span>Keysonar</span>
</a>

4.5 Complex images (charts, infographics, maps)

A chart with multiple data points can't fit in alt alone. Put a one-sentence summary in alt and expose the full data as an accessible table or description elsewhere.

<figure>
  <img
    src="/charts/visibility-2026q1.png"
    alt="Q1 2026 visibility growth: Gemini +42%, GPT-4o +28%"
  >
  <figcaption>
    <a href="#chart-data">View full data as a table</a>
  </figcaption>
</figure>

4.6 Inline SVG

The alt attribute is ignored on inline <svg>. Use a <title> child or aria-label. If decorative, drop the role and add aria-hidden="true".

<svg role="img" aria-label="Star rating: 4.6 out of 5">
  <use href="#star-rating-icon" />
</svg>

<svg aria-hidden="true" focusable="false">
  <use href="#decorative-flourish" />
</svg>

5. How to write a good alt

• Lead with context, not appearance: The same photo means different things on different pages. A smiling woman could be “happy customer” on the home page and “customer review of cream X” on a product page.
• Keep it short: 125 characters is plenty for most cases. Screen readers announce alt in one breath; long, dense alt becomes exhausting.
• Use the page's language: An English alt on a Turkish page gets fed to the Turkish speech engine and turns into noise.
• Audit AI suggestions: Auto-generators describe surface (“building under blue sky”), not meaning. Review every AI-generated alt before publish.

6. Cases that get missed

• CSS background-image: Invisible to the accessibility tree; image-alt won't catch it. If the visual carries meaning, switch from CSS to an HTML img.
• Editor uploads with no alt: WordPress, Shopify and similar treat alt as optional. Add validation at the editor layer so authors can't skip the field.
• Same image reused across pages: One alt may not fit every context. Allow per-placement override in your image manager.
• Drag-and-drop in rich-text editors: Pasted images often arrive without alt. Enforce a non-empty-alt rule before save.
• Avatar images: Putting alt="Jane" next to a visible “Jane” produces a duplicate. Empty alt next to the name is correct.

7. How to test

1. axe DevTools: Browser extension that highlights every img missing alt on the current page.
2. Disable images in your browser: The remaining text should still communicate the page's purpose. If it doesn't, you're leaning on visuals without alt fallbacks.
3. Keysonar SEO Tools: Site-wide crawl that lists every page with missing-alt images and offers AI-suggested alt text. Best path for catching backlog at scale.
4. Screen-reader walkthrough: Run NVDA or VoiceOver, navigate the page, and listen for “graphic” announcements. The text after each one should actually convey something.

8. Quick checklist

• ✓Every <img> has an alt attribute (even if empty).
• ✓Informational images have alt that reflects their meaning in context.
• ✓Decorative images use alt='' and aria-hidden='true'.
• ✓Functional images (inside button/link) describe the action, not the appearance.
• ✓When adjacent text already conveys the meaning, the image's alt is empty.
• ✓Complex charts have a summary alt + a detailed accessible table or text.
• ✓Inline SVGs use <title> or aria-label; decorative ones use aria-hidden.
• ✓Alt text is in the same language as the page.
• ✓Auto-generated 'image', 'IMG_1234' values are scrubbed.

9. References

• WCAG 2.1 SC 1.1.1 — Non-text Content — Level A
• HTML Living Standard — Requirements for providing text alternatives
• W3C: An alt Decision Tree
• WAI-ARIA Authoring Practices: img role