Search topics
Decorative images read out as file names or repeated text
A workshop page has leaf dividers with no alt, so their file names are read, and a card photo whose alt repeats its link text takes an extra Tab stop.
alt="Glazing mugs" tabindex="0" The problem
Screen reader users hear file names and the same title twice, and keyboard users stop on a photo that does nothing.
A pottery shop has a page listing its workshops. Under the "Workshops" heading sits a thin line with a leaf in the middle, a small ornament from the theme. Below it, each workshop is a card: a photo of mugs on a shelf, then the title "Glazing mugs" and the date. The whole card is one link. A screen reader reads "Workshops, heading", then "divider-leaf.png, image", then "link, Glazing mugs, image, Glazing mugs". When someone presses Tab, focus lands on the link, then on the photo inside it, which shows a focus ring and does nothing when Enter is pressed. Every card costs two Tab stops and is read twice.
1.1.1 Non-text Content asks for decoration to be implemented so that assistive technology can ignore it. The divider is an <img> with no alt attribute at all. A missing alt doesn't mean "skip me": screen readers fall back to the file name. The card photo has alt="Glazing mugs", the same words as the link text beside it, so the link's name says the title twice. The photo also has tabindex="0", added by a zoom-on-focus effect, which puts an image that is neither a link nor a button in the tab order. None of these images tells anything the text doesn't, but none of them is implemented to be ignored.
The noise grows with the page. A list of twelve workshops means twelve repeated titles and twelve extra Tab stops, on top of a file name at every section break.
2 of 10 groups affected
- No vision (affected)
- Low vision (not affected)
- Colour vision (not affected)
- No hearing (not affected)
- Hard of hearing (not affected)
- No speech (not affected)
- Motor (affected)
- Reach, strength (not affected)
- Cognitive (not affected)
- Seizures (not affected)
- Without vision Screen reader users hear “divider-leaf.png, image” between headings, and every workshop title twice, so each pass through the list takes longer and sounds broken.
- Limited manipulation Keyboard users stop on each card photo as well as its link, so every card costs two Tab presses and the photo does nothing when they get there.
axe's image-alt flags the divider because it has no alt, and some checkers flag a focusable image. They can't tell whether an image is decoration: alt="Glazing mugs" passes because it isn't empty, and alt="divider" or alt="decorative leaf" pass too, although each reads a useless word. A quick AI fix often writes a description for every image ("A thin brown line with a leaf"), which turns noise into more noise, or adds aria-hidden="true" to the photo but leaves its tabindex, so focus lands on something a screen reader says nothing about. Deciding that an image adds nothing needs a person who can see it next to its text.
Try it
Read the page from the top, then press Tab through the workshop card.
The panel shows both: what is read from the top, and what is said at each Tab stop. Listen for the divider, count the stops on the card.
Broken Can you fix this?
Reading from the top, a screen reader says:
- Workshops, heading
- divider-leaf.png, image
- link, Glazing mugs, image, Glazing mugs, Saturday 14 November, 10:00
Pressing Tab, it says at each stop:
- link, Glazing mugs, image, Glazing mugs, Saturday 14 November, 10:00
- Glazing mugs, image
A recreated demo. The broken version is intentionally inaccessible.
The fix
Give images that add nothing an empty alt, or draw them with CSS, and never put them in the tab order.
- 1An image that adds nothing beside its text gets alt="", never a missing alt or a word like “divider”.
- 2Ornaments can be an img with alt="" or drawn with CSS; either way, nothing is read.
- 3No silent image has a tabindex, or is the only content of a link.
<h2>Workshops</h2><img src="/images/divider-leaf.png" class="divider"> <a class="card" href="/workshops/glazing"> <img src="/images/glazing.jpg" alt="Glazing mugs" tabindex="0"> <h3>Glazing mugs</h3> <p>Saturday 14 November, 10:00</p></a>An empty alt on every image that adds nothing
<h2>Workshops</h2><img src="/images/divider-leaf.png" class="divider" alt=""> <a class="card" href="/workshops/glazing"> <img src="/images/glazing.jpg" alt=""> <h3>Glazing mugs</h3> <p>Saturday 14 November, 10:00</p></a>Why this fix: Use native HTML first
The divider has no alt, so its file name is read. The photo's alt repeats the heading inside the same link, and its tabindex adds a Tab stop that does nothing.
The divider and the photo get alt="", and the tabindex is gone. An empty alt is HTML's own way to say an image is decoration: screen readers skip it, and the browser shows nothing if it fails to load. The link is now read once, "link, Glazing mugs, Saturday 14 November, 10:00", and takes one Tab stop. The alt is empty because this photo shows nothing the card's text doesn't; a photo that does gets alt text for that part, as described under Implementation decisions.
Both options leave the ornaments silent and the cards read once. An empty alt is the one to start with, because it is a single attribute that works for every kind of image, from a theme divider to a photo picked in the CMS, and it is the method HTML defines for decoration. Drawing ornaments with CSS costs a stylesheet change and suits only images fixed in the theme, but it also means nobody can put the divider back without an alt. Background images are dropped in forced colors mode, which is fine for an ornament but a reason never to use CSS for anything that carries meaning.
Images next to text: case by case. An image is decoration only where removing it would lose nothing a reader needs, so the same picture can be silent in one place and need alt text in another. The alt never repeats the text beside it; what changes is whether the image adds anything of its own. These are the common cases.
- A mood or stock photo on a card whose title and link say everything, like the mugs on the "Glazing mugs" card:
alt="". - An image and its text inside the same link to the same place: one link, with the image
alt=""and the text as its name (WCAG technique H2). - A product photo that shows what the text doesn't, such as a colour, a pattern or the item's condition: alt text that says only that ("Cream glaze with a brown rim"), not the product name again.
- An icon beside a label that says the same thing, such as a dishwasher icon next to "Dishwasher safe":
alt="". - An image that is the only content of a link or button: never empty; its alt is the name of the link or button.
- A chart, map or diagram beside text that summarises only part of it: informative, so it needs a text alternative (see the guide on informative images).
When in doubt, read the card aloud without the image and ask whether anything is missing.
An empty alt, not a missing one. alt="" and no alt mean opposite things. alt=" ", alt="divider", alt="spacer" and alt="decorative" are not fixes: each is read aloud.
aria-hidden and role="presentation". Both hide an image from screen readers too, and they are useful for inline SVG, which has no alt. On an <img>, alt="" does the same job without ARIA, and an image with aria-hidden but no alt still fails the scanner and shows a broken-image icon when it fails to load.
Images that are the whole link. If a link holds only an image, the image can't be silent: its alt is the link's name. Give it the destination ("Glazing mugs workshop"), or add visible text and then make the image silent.
Focus. Remove any tabindex from silent images, and check the scripts that add it, such as zoom or lightbox effects. If an image needs to do something, wrap it in a real button with a name.
How Section 508 testing checks it. The Trusted Tester test for decorative images (7.B) passes an image only when all three of these hold.
- it is not the only means of conveying important information on the page;
- it is not in the tab order;
- its accessible name is empty, not missing.
The divider fails the third, and the card photo's tabindex fails the second. The test does not apply to images with a non-empty name, so a photo whose alt repeats its title is judged under the test for meaningful images (7.A) instead; fix it for the reasons above all the same. Background images are outside 7.B too, and are tested separately.
CMS and component libraries. Give image fields a "decorative" checkbox that outputs alt="", rather than leaving the field empty and letting the theme fall back to the file name. Card components that take both a title and an image should never copy the title into the image's alt; let the editor describe what the photo adds, or mark it decorative.
Fixing this with an AI coding assistant? Get this guide as Markdown
Verify the fix
4 checks, no mouse.
Test with: Screen reader, Keyboard
Record the OS, browser and assistive-technology versions, the build, the date, and the actual result of each step. Repeat whenever the theme, the card component or the image fields change.
Limits
This is a starting pattern, not a guarantee for every application. Paths and class names in the snippets are placeholders. Whether an image is decoration depends on the page around it, so only a person who knows both can decide; keep that decision in your publishing review. Test the complete journey with your target assistive technology.
This is a recreated teaching example, not a finding about a named client. The code is a starting pattern: test it in your own product. No completed assistive-technology test is claimed here.
References
- WCAG Understanding: non-text-content (opens in a new tab)
- WAI Tutorial: images/decorative (opens in a new tab)
- WCAG Technique H67 (opens in a new tab)
- WCAG Technique H2 (opens in a new tab)
- WCAG Technique C9 (opens in a new tab)
- WCAG Technique F38 (opens in a new tab)
- WCAG Technique F39 (opens in a new tab)
- developer.mozilla.org: img (opens in a new tab)
Keep this fixed as your code changes.
Turn guides like this into rules your coding agents and CI follow, then have the result retested with a keyboard and screen readers.