WCAG 2.2 Demo Suite

1.1.1 Level A Guideline 1.1 Text Alternatives Added in WCAG 2.0 Partly detectable automatically

Non-text Content

All non-text content has a text alternative that serves the equivalent purpose. Decorative images are given an empty alt attribute so assistive technology ignores them.

Who this affects

Screen reader users get nothing at all from an unlabelled image. Users who disable images, are on slow connections, or use text-only browsers lose the content entirely. Search indexing and translation tools also depend on it.

The failure and the fix

Each example below is a self-contained page, loaded in a frame so its markup cannot affect this page. Open either one on its own to test it with a keyboard or screen reader.

Fails 1.1.1

Open the failing example in a new tab

fail.html — the problem

<h1>Riverline Books — this week</h1>

<!-- FAILURE 1: informative image with no alt attribute at all.
     A screen reader falls back to announcing the file name:
     "graphic, cover-tidal-flats-9781234567890.png" -->
<img src="../../assets/media/book-cover.svg" width="120" height="170">

<h2>Tidal Flats</h2>
<p>Our staff pick for this week.</p>

<!-- FAILURE 2: decorative flourish given descriptive alt text.
     Nothing is communicated, but every screen reader user must listen to it. -->
<img src="../../assets/media/divider.svg" alt="decorative horizontal line divider graphic"
     width="320" height="8">

<!-- FAILURE 3: icon-only button with no accessible name.
     Announced as "button" - the user is told nothing about what it does. -->
<button type="button" class="button button--secondary">
  <svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor">
    <path d="M10 3a7 7 0 0 1 6.3 10.05l-.3.55 3 3-1.4 1.4-3-3A7 7 0 1 1 10 3Zm0 2a5 5 0 1 0 0 10A5 5 0 0 0 10 5Z"/>
  </svg>
</button>

<!-- FAILURE 4: alt text that exists but conveys nothing the image conveys.
     This passes every automated scanner and fails every actual user. -->
<img src="../../assets/media/sales-chart.svg" alt="chart" width="360" height="200">

<!-- FAILURE 5: meaningful image implemented as a CSS background with no text
     equivalent anywhere. There is no alt attribute to forget - which is why
     this one is so easy to miss in review. -->
<div class="badge-award" role="presentation"></div>

Meets 1.1.1

Open the passing example in a new tab

pass.html — the fix

<h1>Riverline Books — this week</h1>

<!-- FIX 1: the alt text serves the same purpose as the image. The adjacent
     heading already gives the title, so the alt describes what only the image
     shows, without repeating the caption or starting "image of". -->
<img src="../../assets/media/book-cover.svg" alt="Book cover: a pale estuary at low tide under a wide grey sky."
     width="120" height="170">

<h2>Tidal Flats</h2>
<p>Our staff pick for this week.</p>

<!-- FIX 2: purely decorative, so alt="" removes it from the accessibility tree.
     Note this is an EMPTY alt, not a missing one - the attribute must be present. -->
<img src="../../assets/media/divider.svg" alt="" width="320" height="8">

<!-- FIX 3: the button gets a name from visually hidden text, and the icon is
     marked aria-hidden so it is not announced twice. A visible label would be
     better still; this pattern is for when the design demands icon-only. -->
<button type="button" class="button button--secondary">
  <svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true" focusable="false">
    <path d="M10 3a7 7 0 0 1 6.3 10.05l-.3.55 3 3-1.4 1.4-3-3A7 7 0 1 1 10 3Zm0 2a5 5 0 1 0 0 10A5 5 0 0 0 10 5Z"/>
  </svg>
  <span class="visually-hidden">Search the catalogue</span>
</button>

<!-- FIX 4: a chart carries data, so the short alt states the conclusion and a
     full text equivalent follows. A complex image needs both: the summary for
     someone skimming, the detail for someone who needs the numbers. -->
<figure>
  <img src="../../assets/media/sales-chart.svg"
       alt="Bar chart: weekly sales rose from 40 in week 1 to 115 in week 5."
       width="360" height="200">
  <figcaption>
    Weekly sales, weeks 1 to 5.
    <details>
      <summary>Chart data as a table</summary>
      <table>
        <caption>Books sold per week</caption>
        <thead><tr><th scope="col">Week</th><th scope="col">Books sold</th></tr></thead>
        <tbody>
          <tr><th scope="row">1</th><td>40</td></tr>
          <tr><th scope="row">2</th><td>55</td></tr>
          <tr><th scope="row">3</th><td>70</td></tr>
          <tr><th scope="row">4</th><td>95</td></tr>
          <tr><th scope="row">5</th><td>115</td></tr>
        </tbody>
      </table>
    </details>
  </figcaption>
</figure>

<!-- FIX 5: the award badge carries meaning, so it becomes a real img element
     with real alt text. If a CSS background is unavoidable, give the element
     role="img" and an aria-label instead. -->
<img src="../../assets/media/award-badge.svg" alt="Winner of the 2026 Riverline Prize"
     width="96" height="96">

Choosing the right text alternative

Most alt-text mistakes come from asking "what is in this picture?" instead of "why is this picture here?" The same photograph needs different alt text depending on the job it is doing on the page.

Deciding what alt text an image needs
If the image… Then… Example
is purely decorative Use alt="". The attribute must be present and empty. Better still, move it to CSS. <img src="flourish.svg" alt="">
carries information Describe the information, not the picture. Skip "image of" — the screen reader already says "graphic". alt="Estuary at low tide under a grey sky"
is the only content of a link or button The alt text must describe the destination or action, not the artwork. alt="Riverline Books home", not alt="logo"
is complex — a chart, map or diagram Short alt stating the conclusion, plus a full text equivalent nearby. See the chart in the passing example
repeats adjacent text exactly Use alt="". Duplicating the caption makes a screen reader say it twice. A thumbnail beside a headline that already links
contains text The alt must contain that same text — and consider whether it should be real text instead (see 1.4.5 Images of Text). alt="Free delivery over £25"

Why the empty alt matters

alt="" and a missing alt are not the same thing. An empty alt tells assistive technology "this image carries nothing, skip it". A missing alt tells it "I do not know what this is" — so screen readers fall back to announcing the file name, which is usually worse than silence. This one-character difference is the most common finding in any real audit.

Try it yourself

  1. Open the failing example and run your screen reader's "list all images" command (Insert+Ctrl+G in NVDA, the Rotor in VoiceOver). Count how many tell you something useful.
  2. Tab to the icon-only button in each example and listen to the difference.
  3. Run npm run test:a11y and note that the scanner catches failures 1 and 3, but is completely blind to failures 2, 4 and 5 — the alt text that exists but is useless.

How to test it

Inspect every img, svg, canvas, area, input[type=image], and CSS background that carries meaning. Ask: if this image vanished and were replaced by its alt text, would the page still make sense? Decorative images must have alt="" (not a missing alt, and not alt="decorative image").

  • Automated

    Scanners detect a missing alt attribute reliably. They cannot judge whether the alt text is accurate or meaningful — alt="image" passes every automated tool and fails every real user.

    Relevant axe rules:

    • image-alt
    • input-image-alt
    • area-alt
    • role-img-alt
    • svg-img-alt
    • object-alt

  • Keyboard

    Unplug the mouse. Move through the page with Tab, Shift+Tab, Enter, Space and the arrow keys. See the keyboard testing script.

  • Screen reader

    Listen to both examples with NVDA, JAWS, VoiceOver or TalkBack and compare what is announced. See the screen reader cheat sheets.

  • Visual

    Zoom to 200% and 400%, narrow the viewport to 320 px, and apply the text-spacing overrides. See the visual testing procedures.

In the specification