Valence Metrics

How to fix "Buttons must have discernible text" in Shopify themes

· 6 min read

"Buttons must have discernible text" means a button has no name that a screen reader can announce. The customer hears only "button" and has to guess what it does. In Shopify themes this is usually an icon-only button, and the fix takes a few minutes.

Where these buttons hide

  • Menu toggle (the "hamburger" icon) and close buttons in drawers
  • Search and cart icons in the header
  • Previous and next arrows on sliders
  • Plus and minus buttons for the quantity
  • Sticky add-to-cart buttons that show only an icon on mobile

The rule behind the message comes from the axe-core engine and maps to WCAG success criterion 4.1.2 (Name, Role, Value).

Step 1: find the button

A scanner such as Valence shows the element's CSS selector and the page it was found on, for example .sticky-add-to-cart__button on a product page. You can also open the page in Chrome, right-click the button and choose Inspect to see its code.

Step 2: duplicate your theme

Go to Online Store › Themes, open the … menu of your live theme and choose Duplicate. Work on the copy, check it with the preview, then publish it.

Step 3: give the button a name

Open Edit code on the copy and search the theme files for the class name from step 1. Then use one of two options.

Option A: aria-label

<button type="button" class="header__icon" aria-label="Open menu">
  <svg aria-hidden="true" focusable="false">…</svg>
</button>

Option B: visually hidden text

Many themes, including Shopify's Dawn, have a visually-hidden class that hides text on screen but keeps it for screen readers:

<button type="button" class="header__icon">
  <svg aria-hidden="true" focusable="false">…</svg>
  <span class="visually-hidden">Open menu</span>
</button>

On multilingual stores, use your theme's translation keys (| t) instead of plain English text, with either option.

Tips

  • Describe the action, not the icon: "Open menu", not "Three lines".
  • Hide the icon itself with aria-hidden="true", so it isn't announced twice.
  • Don't rely on title alone. It is not announced consistently and doesn't show on touch screens.
  • Use a real <button>. A clickable <div> can't be reached with the keyboard by default.
  • App buttons: if the button comes from an app, ask the app's support to fix it.

Step 4: check the fix

Scan the page again, or use a screen reader: VoiceOver on iPhone and Mac, NVDA on Windows. The button should now be announced with its name.

Sources

This article is general information, not legal advice. Automated tools, including Valence, find only part of all accessibility barriers and cannot certify conformance with the ADA, WCAG, the European Accessibility Act or any other standard.

← All guides