Remediation guide

How to Fix Missing Alt Text on Images — WCAG 1.1.1

Missing or empty alt text on images is the most-cited accessibility failure in ADA website demand letters. Automated scanners detect it instantly from the HTML source. The fix is straightforward once you understand the three image types — but applying it correctly requires knowing when to describe, when to leave the alt empty, and when to describe the function instead of the visual content.

• Three image types
• Writing good alt text
• Find missing alt text
• Platform fixes
• Special cases
• Verify with ShipSafe
• FAQ

The three image types — and what each needs

Every image falls into one of three categories. The category determines whether you need alt text and how to write it.

Code examples for each type

<!-- Screenshot: describe what it shows -->
<img src="dashboard.png"
     alt="Project dashboard showing 3 active builds, 94% uptime, and a deploy button">

<!-- Team headshot in a bio section -->
<img src="alex-chen.jpg" alt="Alex Chen, Lead Engineer">

<!-- Diagram in an article -->
<img src="tcp-handshake.svg"
     alt="TCP three-way handshake: SYN from client, SYN-ACK from server, ACK from client">

<!-- Decorative divider: empty alt string, NOT omitted -->
<img src="wave-divider.svg" alt="">

<!-- Stock photo where adjacent text provides all context -->
<img src="team-collaboration.jpg" alt="">

<!-- Logo link: describe the destination -->
<a href="/">
  <img src="logo.svg" alt="Acme Corp — go to homepage">
</a>

<!-- Icon-only button: describe the action, not the icon -->
<button type="submit">
  <img src="search-icon.svg" alt="Search">
</button>

<!-- Missing alt attribute: screen reader announces the filename -->
<img src="hero-2024-v3.jpg">

<!-- Meaningless placeholder alt -->
<img src="product-shot.png" alt="image">

<!-- Empty alt on an informative image -->
<img src="revenue-chart-q3.png" alt="">

<!-- Describing appearance instead of function on a link image -->
<a href="/"><img src="logo.svg" alt="Blue circle with white text"></a>

5 rules for writing good alt text

These rules apply to informative images — the ones that need descriptive alt text. Apply them in order when you’re not sure what to write.

1. Describe what the image communicates, not what it looks like

   Alt text is a functional replacement — it should give the reader the same understanding they’d get from seeing the image. A screenshot of your SaaS dashboard should describe what information the dashboard shows, not that it is a "screenshot with a blue sidebar". Context matters: the same photo might need different alt text depending on what point the surrounding content is making.

2. Don’t start with “image of” or “photo of”

   Screen readers already announce “image” (or “graphic”) before reading the alt text. Starting with “image of a person” means users hear “image — image of a person”. Skip the prefix and go straight to the content: “Alex Chen, Lead Engineer” instead of “Photo of Alex Chen, Lead Engineer”.

3. Match length to information density

   There’s no required length limit. A team headshot: 3–6 words (name and role). A product screenshot: 15–25 words describing what the interface shows. A data chart: a brief summary in alt text, plus a data table or paragraph below the image containing the full data. The W3C technique G94 recommends a short text alternative in alt; G92 recommends a longer description in adjacent text for complex images.

4. For functional images, describe the destination or action

   An image inside a link or button is a UI control. Its alt text is the control’s accessible label, not an image description. For links: describe where the link goes (“Copper Bay Labs homepage”). For buttons: describe what the button does (“Search”, “Close menu”, “Submit payment”). The visual appearance of the icon is irrelevant.

5. For complex images, supplement with visible text

   Charts, infographics, and diagrams often communicate data that can’t be compressed into a short string without losing meaning. Provide a brief summary in the alt attribute, then include the underlying data as a visible HTML table or paragraph below the image. Use aria-describedby to link the image to its description element. This makes the data accessible to everyone, not just screen reader users.

How to find images with missing alt text

1. ShipSafe (fastest for a quick page check)

Paste your URL into ShipSafe. It reads the page’s source HTML and flags every <img> missing an alt attribute and every image with a suspicious placeholder value (“image”, “photo”, a URL-looking string). Results in under 10 seconds, no install required.

2. Axe DevTools browser extension (most thorough)

Install the free Axe DevTools extension for Chrome or Firefox. Open any page, right-click → Inspect → click the “axe DevTools” tab. Run the scan: Axe identifies every WCAG 1.1.1 violation with a specific element selector you can click to jump to the node. It catches missing alt attributes, empty alt on informative images, and alt="image"-style non-descriptions.

3. Chrome DevTools Elements search (bulk audit)

Open DevTools (F12) → Elements panel → Ctrl+F (Windows) or Cmd+F (Mac). Search for img:not([alt]) to find all images missing an alt attribute. This won’t catch empty-alt-on-informative-images; use Axe for that.

Fix missing alt text in your builder or framework

// Informative
<Image src="/dashboard.png"
  alt="Dashboard showing 3 active projects" />

// Decorative
<Image src="/divider.svg" alt="" />

Special cases

Inline SVG elements

An SVG embedded as a <svg> element in HTML doesn’t accept an alt attribute. For informative inline SVGs, add role="img" and a <title> child as the text alternative:

<svg role="img" aria-labelledby="chart-title" viewBox="0 0 400 200">
  <title id="chart-title">Monthly active users — Q3 2024</title>
  <!-- SVG content -->
</svg>

For decorative inline SVGs (icons next to visible text labels, background graphics), remove them from the accessibility tree entirely:

<svg aria-hidden="true" focusable="false" viewBox="0 0 24 24">
  <!-- decorative icon -->
</svg>

CSS background images

Images applied via background-image in CSS are invisible to screen readers — they are presentational by definition and cannot carry alt text. Only use CSS background-image for decorative content. If an image is informative and must remain as a background image for layout reasons, provide a visually-hidden text alternative in the HTML:

<div class="hero" style="background-image:url('hero.jpg')">
  <span class="sr-only">Aerial view of downtown at sunset</span>
</div>

Icon fonts (Font Awesome, Material Icons)

Icon fonts render glyphs as text characters that screen readers may announce unpredictably. The correct pattern: hide the icon element from the accessibility tree and provide the accessible name on the containing control:

<!-- Button: accessible name on the button, icon hidden -->
<button type="button" aria-label="Delete">
  <i class="fa fa-trash" aria-hidden="true"></i>
</button>

<!-- Link with visible text: hide the icon, keep the text -->
<a href="/settings">
  <i class="fa fa-cog" aria-hidden="true"></i>
  Settings
</a>

Complex images (charts, infographics)

For complex images where a brief alt string can’t capture all the information, provide a short summary in alt and link the image to a longer visible description with aria-describedby:

<figure>
  <img src="revenue-q3.png"
       alt="Q3 2024 revenue by product line"
       aria-describedby="revenue-q3-data">
  <figcaption id="revenue-q3-data">
    Product A: $1.2M (+18% vs Q2). Product B: $890K (flat).
    Product C: $420K (flat). Total: $2.51M.
  </figcaption>
</figure>

Verify your fixes with ShipSafe

After adding or updating alt text, run ShipSafe on the same URL to confirm the changes are live. ShipSafe reads the page’s HTML source and flags remaining <img> elements with a missing or suspicious alt attribute. Look for the Accessibility category in the results — a green check next to “Images have alt text” confirms the visible images in your source HTML are covered.

Note: ShipSafe reads the initial HTML source. Images injected by JavaScript after the page loads — lazy-loaded images, carousel images, images rendered by a JS framework without SSR — may not appear in the scan. For comprehensive JavaScript-rendered coverage, use Axe DevTools directly in the browser after the page fully loads.

Check my site with ShipSafe →

Related ShipSafe guides:

• WCAG compliance for AI-generated sites — all 5 most-flagged gaps
• ADA compliance checklist for developers — 30 testable WCAG 2.1 AA items
• WCAG remediation checklist for existing websites
• Received an ADA demand letter? What to do first

Frequently asked questions

Also in the Copper Bay Labs suite

Accessibility is one layer of pre-launch risk. These free tools cover the rest: