Alt Text for Images, Icons and Charts Under the ADA

What a screen reader says when alt text is missing

A resident who is blind opens a county permit portal. The screen reader reads "link, plus dot png" where a button should be, then "graphic" four times where a site plan should be. The page has not failed to load; it has failed to describe itself.

WCAG 1.1.1 (Level A) says that all non-text content presented to the user needs a text alternative that serves the equivalent purpose. Text is the format that works across senses: it can be spoken, shown in braille, enlarged, translated or searched. The word that matters is equivalent purpose, not "literal description".

The criterion lists a handful of situations, each with its own expectation:

• Controls and inputs: the text alternative is the control's name, so it says what happens when you activate it.
• Time-based media: at minimum, text that identifies what the audio or video is. The 1.2 criteria cover captions and descriptions.
• Tests and exercises: if the content would be invalid as text, describe its purpose.
• Sensory experiences: a descriptive label for music or art that exists to be experienced.
• CAPTCHA: text that says what the CAPTCHA is for, plus another form that uses a different sense.
• Decoration, formatting, invisible content: build it so assistive technology skips it.

A phone test for choosing alt text

Imagine reading the page aloud to a friend over the phone. What would you say when you reached this image? The answer is the alt text. If the honest answer is "nothing, it is just a pretty border", the image is decorative and should be empty.

• Photo that adds information: state what matters in the context of the page, usually one sentence. A photo of the new library entrance on a "Visit us" page: "Ramp and automatic doors at the east entrance".
• Image that is a link or button: describe the destination or action, not the picture. "Pay your water bill", not "blue droplet icon".
• Chart or map: a short name in the alt text, with the data or the route in text nearby, such as a table or a list.
• Decorative image: alt="", or a CSS background, so it is skipped.
• Text inside an image: the alt text repeats that text exactly (and see criterion 1.4.5 about whether the image should exist at all).

Do not begin with "image of" or "picture of"; the screen reader already announces the role.

Where public-sector pages usually fall short

Missing alt text appears on the Department of Justice's list of common web accessibility barriers, and it is easy to see why. Government sites accumulate images through years of manual uploads: council photos, scanned flyers pasted in as pictures, maps of polling places, budget charts exported as PNG files, and icon buttons in portals built by vendors.

The patterns that matter most are the ones that block a task. An icon-only "Renew" button with no name, a campground map that is the only place the accessible sites are shown, or a flyer image that carries the time and place of a public hearing leave a person without the information or the action. Because Title II points to WCAG 2.1 Level A and AA, a missing text alternative on a page a city or county provides is a plain gap against 1.1.1. See also the broader list of common barriers for how this fits with other frequent problems.

Web patterns: from file names to useful names

Start with controls, because an unnamed control is the most disruptive case. The name must describe the action.

<a href="/permits/new">
  <img src="/img/plus-circle.png">
</a>

<a href="/permits/new">
  <img src="/img/plus-circle.png"
       alt="Start a building permit application">
</a>

Complex images need two layers: a short name in the attribute and the real content in text a reader can reach.

<img src="pine-hollow-map.png" alt="map">

<figure>
  <img src="pine-hollow-map.png"
       alt="Pine Hollow campground map, loops A to C">
  <figcaption>
    Accessible sites: A4, A9, B2 and C1.
    <a href="/parks/pine-hollow/sites">Full site list</a>
  </figcaption>
</figure>

Decoration should be silent. An empty alt is a deliberate statement, not an omission.

<img src="wave-divider.png"
     alt="decorative wave divider image">

<img src="wave-divider.png" alt="">

<!-- or, better, keep it in CSS -->
.section-break { background: url(wave-divider.png) repeat-x; }

Native app patterns for transit and service apps

Native apps have the same duty. In SwiftUI an icon-only button needs an explicit label, and purely decorative images should be marked as such.

Button(action: refreshArrivals) {
    Image("refresh-arrows")
}

Button(action: refreshArrivals) {
    Image(decorative: "refresh-arrows")
}
.accessibilityLabel("Refresh bus arrivals")

In Jetpack Compose, contentDescription = null on an icon inside a button removes the only name the control had. Put the description on the control that the user operates.

IconButton(onClick = { refreshArrivals() }) {
    Icon(Icons.Default.Refresh, contentDescription = null)
}

IconButton(onClick = { refreshArrivals() }) {
    Icon(
        Icons.Default.Refresh,
        contentDescription = "Refresh bus arrivals"
    )
}

Testing: listen first, then run the checker

1. Open the page with a screen reader (NVDA, JAWS, VoiceOver or TalkBack). Tab through every link and button; each should announce a purpose, not a file name or "unlabeled".
2. Browse by graphics. Does each announced image tell you what a sighted visitor learns? Are decorative images skipped?
3. Turn images off in the browser or hover over each image in a dev-tools accessibility tree. The text that appears is what the alt text must stand in for.
4. Only then run an automated checker. It can find a missing attribute but cannot judge whether "chart" is a useful description, and a clean report does not mean the page is accessible.

Mistakes that keep appearing in audits

• File names as alt text: alt="IMG_4471.jpg".
• One description pasted into every image of a gallery.
• Describing the look of an icon button instead of its action.
• Putting a long paragraph in the attribute where a visible text description belongs.
• Leaving the attribute off decorative images, so some tools read out the file path.
• Marking a meaningful image as decorative because the surrounding text "mostly" covers it.

Ship it when

• Every img, svg, image button and image map area has a deliberate text alternative or is deliberately empty.
• Controls are named by their action.
• Charts and maps have their data available as text on the same page.
• A screen reader pass over the main task flow finds nothing announced as "graphic" or a file name.

Sources

• Understanding SC 1.1.1: Non-text Content (W3C), opens in a new tab
• H37: Using alt attributes on img elements (W3C), opens in a new tab
• 28 CFR Part 35, Subpart H: Accessibility of Web Information and Services (eCFR), opens in a new tab

Standard version: WCAG 2.1 (W3C Recommendation, 5 June 2018), as named in the Title II web rule. This page is for informational purposes only and is not legal advice. For binding requirements, refer to the official ADA statute and regulations, and ask a lawyer how they apply to you.