NewThe tragent CLI is on npm: npx @tragent/cli scan your-store.com
tragent
Scan your site

Issue reference

Buttons and links have no accessible name

Issue code
A11Y_CONTROLS_UNNAMED
Stage
Read the details
Protocol
—
Severity
High

What it means

tragent reports this at the “Read the details” stage. The question there is “Can it understand what the product is?” Name, description, images and variants have to be readable as data, not just rendered as a page.

What it does to an agent

Most agents fail at this point. The few that find a way round it spend more time and model calls doing so, and may give up before checkout.

Browser agents find buttons the way screen readers do: by their accessible name. An icon-only basket button, a search icon, or a size swatch with no label has no name, so the agent cannot tell "add to basket" from "add to wishlist", and guesses. The same buttons are unusable for people on screen readers.

tragent counts the buttons and links on your pages with no accessible name. This is advisory and does not move the readiness score, but it is the commonest reason a browser agent clicks the wrong thing.

How to fix it

Give icon-only buttons and links an aria-label; screen readers announce it and agents click by it.

Before: No name
<button class="icon-cart"><svg>…</svg></button>
After: Named
<button class="icon-cart" aria-label="Open basket"><svg aria-hidden="true">…</svg></button>

On your platform

Shopify

Dawn and most current themes name their icon buttons with visually hidden text. Custom sections and apps are the usual offenders. Add an aria-label, using a translation key so it follows the shopper's language.

Liquid
<button type="button" aria-label="{{ 'general.search.search' | t }}">
  {% render 'icon-search' %}
</button>

WooCommerce

Check the header icons and any quick-view or wishlist buttons a plugin adds. Most themes let you add an aria-label in the template override.

Any site

Every button and link needs visible text, an aria-label, or an aria-labelledby that points at text. Mark decorative icons aria-hidden so they do not add noise.

In practice

Fix the controls on the buying path first: search, product options such as size and colour, quantity, add to basket, the basket itself and the checkout button. Those are the clicks an agent must get right, and a wrong guess on any of them ends the journey or buys the wrong thing. Footer social icons can wait.

Size and colour swatches are the most common gap. A swatch drawn as a coloured circle needs a name such as "Black" or "Size 10", and its selected state should be exposed with aria-pressed or by using a real radio input. An agent that cannot tell which size is selected cannot confirm it chose the one the shopper asked for.

Test the result with the tool your shoppers' agents resemble most: a screen reader. On a Mac, VoiceOver's rotor lists every button and link on the page by name; on Windows, NVDA does the same. Walk the buying path with it once. Every control that is read out as "button" with nothing after it is one an agent cannot identify either.

Check the fix

  1. In Chrome DevTools, open the Accessibility pane on an icon button and check its computed name.
  2. Run the scan; the count of unnamed controls should fall.

Run the check that reported A11Y_CONTROLS_UNNAMED again after the change. The scan needs no account; an issue found during an AI shopping test needs that test run again.

Terminal
npx @tragent/cli scan https://your-store.com

Common mistakes

  • Labels like "button" or "icon", which name nothing.
  • A title attribute alone, which not every reader uses.