Monitoring Accessible Names After Icon Swaps

An icon-only button with no accessible name is invisible to a screen reader. Theme updates swap icons constantly, and the name is usually the first thing lost.

A store swaps its search icon for a new one in a theme update. The button still looks the same to sighted users. To a screen reader it has just become an unnamed button, one of six unnamed buttons in the header, and the shopper who navigates by voice has no way to tell which one opens search. Nobody notices, because the regression is invisible to everyone who can see the page.

Accessible names are the most fragile part of a storefront. They live in aria-label attributes, in svg title elements, and in visually hidden text, and a redesign can strip all three without changing a single pixel. Monitoring them means checking the name, not the icon.

What an accessible name is, and where it hides

Every interactive element needs a name a screen reader can announce. For a button with visible text, the text is the name. For an icon-only button, the name has to come from somewhere else: an aria-label on the button, a title element inside the svg, or visually hidden text. The accessible name computation follows a fixed order, and a sloppy aria-label can override good visible text, so the check is the computed name, not the attribute you think you set.

The usual losses are predictable. A theme update replaces the svg and drops the title element. A developer copies a button and forgets the aria-label. A translation pass leaves the English label on a button whose visible text changed. A third-party app injects its own icon button with no label at all.

A monitoring check that catches it

Add accessible names to the regression suite, not the audit. After every theme release, run the page through a tool that lists the computed accessible name of every button, link, and form control, and diff that list against the previous release. Any button whose name changed to empty, or to button, is a finding, not a warning.

Screen reader spot checks are the second layer. Tab through the header and the product page with a screen reader and listen to what gets announced. Six unnamed buttons in a row is a defect you can hear in under a minute. Do the same after any app install, because injected controls are the most common source of new unnamed buttons.

Fixing names without breaking design

The fix is usually one attribute. Give the button an aria-label that says what it does, not what it looks like: search, not magnifying glass. For icons that repeat, like a close button on every modal, use the same label everywhere so the user learns it once. For an icon button next to visible text, let the text be the name and keep the icon decorative with aria-hidden.

Resist the temptation to fix it with a title attribute. Tooltips are not accessible names in most browsers, and they do nothing for keyboard and screen reader users. If the name has to be set in code, set it in code properly.

Related reading: Monitoring Skip Links After a Navigation Redesign, Monitoring Table Headers on Order History and Account Pages, Monitoring Focus Visibility When Sticky Headers and Banners Keep Changing.

Frequently asked questions

What is an accessible name?

It is the text a screen reader announces for an interactive element. Visible text supplies it for most buttons and links. Icon-only buttons need an aria-label, an svg title, or visually hidden text, or they are announced as unnamed button.

Why do icon swaps break accessible names?

The name often lives inside the svg or in an attribute on the old button markup. When a theme update replaces the icon, the name goes with it, and nothing on the visible page changes, so the regression is invisible to sighted testers.

Is a title attribute enough for an icon button?

No. Tooltips are not reliable accessible names across browsers, and they do nothing for keyboard and screen reader users. Use an aria-label on the button or visually hidden text inside it.

How often should accessible names be rechecked?

After every theme release and every app install. Both are the moments when new icon buttons appear and old labels get dropped. A computed-name diff against the previous release catches it before customers do.