Rule ID: ace-img-alt-text

Verify images have alternative text or are explicitly marked as decorative

WCAG 2.0 (A) - WCAG 2.2 (A) 1.1.1: Non-text Content Blind Deafblind Legal Risk

What This Rule Checks

Images on a website convey important information, but for users who rely on screen readers or have visual impairments, these images are inaccessible unless accompanied by descriptive text. The alt attribute is essential because it provides a text alternative to images, allowing screen readers to describe the image’s content.

Who Is Affected

This issue primarily affects: Blind users, who rely entirely on screen readers or braille displays to navigate and interact with content; Deafblind users, who rely on braille displays and cannot access visual or auditory content.

Why This Matters

Missing image alt text is the most frequently cited violation in accessibility lawsuits worldwide. WCAG 1.1.1 (Non-text Content) is Level A — the most fundamental requirement. Without alt text, blind users encounter images announced as file names or simply “image,” missing all visual information on the page.

How to Fix

Use the alt Attribute:

Add a descriptive alt attribute to all <img> elements to provide a meaningful text alternative to the image.

Use Empty alt Attributes for Decorative Images:

If an image is purely decorative and doesn’t add meaning, provide an empty alt=”” to prevent screen readers from announcing it.

Use aria-label for Custom Labels:

Use the aria-label attribute to provide a custom, hidden label that can be read by screen readers.

Use aria-labelledby for Descriptive Associations:

Use the aria-labelledby attribute to associate the image with another element (such as a heading or label) that describes it.

Code Examples

Incorrect Markup Solutions:

Code example

<!-- Missing alt attribute -->
<img src="team-photo.jpg">

<!-- Meaningless alt text -->
<img src="chart.png" alt="image">

<img src="photo.jpg" alt="DSC_0042.jpg">

Copy

Correct Markup Solutions:

Code example

<!-- Descriptive alt text -->
<img
  src="team-photo.jpg"
  alt="The ACE team at the 2025 company retreat">

Copy

Correct Markup Solutions:

Code example

<!-- Decorative image silenced -->
<img
  src="decorative-swirl.png"
  alt="">

Copy

Correct Markup Solutions:

Code example

<!-- Complex image with extended description -->
<figure>
  <img
    src="q3-chart.png"
    alt="Q3 revenue chart showing 23% growth in EMEA">

  <figcaption>
    Q3 2025 revenue by region. EMEA led growth at 23%,
    followed by North America at 15%.
  </figcaption>
</figure>

Copy

Common Mistakes to Avoid

Starting with “Image of…” or “Picture of…” — screen readers already announce it as an image.
Using file names as alt text (e.g., alt=”DSC_0042.jpg”).
Duplicating adjacent caption text in the alt attribute.
Ignoring functional images — images used as buttons must describe the action, not the visual.
Writing alt text that describes appearance rather than purpose (e.g., “green button” vs “Submit form”).

AI Auto-Fix Available

This rule supports ACE™ AI Auto-Fix. When a violation is detected, ACE can automatically generate a code fix for review. The AI analyzes the specific element in context and proposes a targeted remediation that preserves your existing markup and styling. You can preview, modify, and approve the fix before it is applied.

Tip: When writing alt text, describe the image’s function and meaning, not just its appearance. For complex images like charts, provide a brief alt attribute and a longer description in surrounding text or a linked resource.

Related WCAG Criteria

• 1.1.1: Non-text Content