DEV Community

Cover image for Fix Shopify accessibility in the theme, not with a widget: what we measured
VibeFix
VibeFix

Posted on Originally published at vibe-fixer.com

Fix Shopify accessibility in the theme, not with a widget: what we measured

I run VibeFix, a service where an AI agent fixes accessibility issues in Shopify theme code. So I have a view on this topic, and you should weigh what follows with that in mind. I have tried to keep to what we measured and what the sources say.

The question I keep seeing from store owners: "Do I add an accessibility widget, or do I fix the theme?" Here is the difference in practical terms, and then four fixes you can make in your own theme.

What a widget changes, and what it does not

An accessibility widget (also called an overlay) is a script that loads in each visitor's browser and changes the page there. It does not change your theme's files. If the script does not load, is blocked, or misses a problem, the visitor gets the page your theme actually serves.

That is not a judgment on the people who like the menu of bigger text or stopped animations. Some visitors do. The point is narrower: the problems that live in your Liquid, CSS and admin content are still there after the script is added.

The US Department of Justice's web guidance says automated checkers and overlays "can be helpful tools", but "they need to be used carefully", and that a "clean" report "does not necessarily mean everything is accessible". Their suggestion is to pair them with a manual check.

What a widget costs in the browser

We measured one cost, and only one. On 15 November 2026 we ran Lighthouse (version 12.8.2, simulated mobile, 3 runs per store) on 10 public Shopify homepages that load an accessibility widget. We read the time Lighthouse attributes to the widget's own script.

  • Median blocking time: 756 ms.
  • Median main-thread time: 1,049 ms.
  • Store by store, blocking time ranged from 49 ms to 1,962 ms, so the median hides a wide spread.

Blocking time is the part of a long task that runs past 50 ms on the browser's main thread, the stretch in which the page cannot respond to a tap or keypress.

The limits matter. This is a lab run on one PC that was under CPU load from other work, single runs varied a lot, 10 stores is a small sample, and Lighthouse attributes time by script owner. It is not field data from real visitors. It says nothing about whether a widget helps or harms accessibility, and we make no comparison between vendors. It is one data point on one cost.

What the problems look like in theme code

We also ran one automated, read-only check (axe-core) on the public homepage of 108 US Shopify stores we had picked for outreach, between 5 and 11 November 2026. These are not a random sample, so read the numbers as "stores we checked", not as Shopify in general. Faint text was on 66.7% of them, and links with no text a screen reader can read out on 63.9%. Images with no text description were on 25.0%.

Those findings are code and content, and so are the fixes. Here are four. Work on a duplicate of your theme (Online Store, Themes, the three-dot menu, Duplicate), check the copy, publish it yourself, and re-check the live store afterwards.

Fix 1: image alt text

Product photos get their alt text in the Shopify admin (Products, the product, the media item, Add alt text). Images in theme sections get it in the theme editor. If a section hard-codes an image with no alt, that is a theme fix.

Before:

<img src="{{ section.settings.banner | image_url: width: 1600 }}">
Enter fullscreen mode Exit fullscreen mode

After, with a text setting the merchant can fill in:

<img
  src="{{ section.settings.banner | image_url: width: 1600 }}"
  alt="{{ section.settings.banner_alt | escape }}"
  width="1600"
  height="700"
  loading="lazy">
Enter fullscreen mode Exit fullscreen mode
{
  "type": "text",
  "id": "banner_alt",
  "label": "Banner image description",
  "info": "Short and specific. Leave empty only if the image is purely decorative."
}
Enter fullscreen mode Exit fullscreen mode

W3C's images tutorial says a text alternative gives "at least a short description conveying the essential information presented by the image", and that purely decorative images get an empty alt (alt=""). Shopify's guidance aims for 125 characters or fewer.

Fix 2: icon-only links and buttons

A cart or search icon with no visible words is announced by a screen reader as just "link" unless something gives it a name. In the study, 63.9% of stores had at least one such link, and the middle affected store had 5.

Before:

<a href="{{ routes.cart_url }}" class="header__icon">
  <svg aria-hidden="true" viewBox="0 0 24 24">...</svg>
</a>
Enter fullscreen mode Exit fullscreen mode

After:

<a href="{{ routes.cart_url }}" class="header__icon">
  <svg aria-hidden="true" focusable="false" viewBox="0 0 24 24">...</svg>
  <span class="visually-hidden">Cart ({{ cart.item_count }})</span>
</a>
Enter fullscreen mode Exit fullscreen mode

A visible-text span like this is more robust than an aria-label on its own, and most themes already ship a visually-hidden helper class. If your theme does not, add one to your CSS. If you prefer aria-label, aria-label="Cart" on the <a> works for the name too. Do not put the label on the SVG and also on the link, or it is read twice.

Fix 3: faint text

Light grey on white looks calm in a mockup and can vanish on a phone in sunlight. WCAG 1.4.3 asks for a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text. This was the most common finding in the study (66.7% of the stores we checked, a median of 6 elements among stores that had it).

Before:

.product-card__vendor,
.footer__small-print {
  color: #aaaaaa;          /* on white: far below 4.5:1 */
}
Enter fullscreen mode Exit fullscreen mode

After:

.product-card__vendor,
.footer__small-print {
  color: #595959;          /* on white: about 7:1 */
}
Enter fullscreen mode Exit fullscreen mode

Test any colour pair in a contrast checker such as WebAIM's before you save. The announcement bar, sale badges, button labels, footer links and text over photos are the first places to look. If your theme uses colour schemes, fixing the scheme in the theme editor can fix every section that uses it.

Fix 4: page language

The lang attribute tells screen readers which pronunciation rules to use. Themes normally set it from the store's locale, but customised or older themes sometimes hard-code it, or lose it in a layout edit.

Before:

<html>
Enter fullscreen mode Exit fullscreen mode

After:

<html lang="{{ request.locale.iso_code }}">
Enter fullscreen mode Exit fullscreen mode

Open layout/theme.liquid and check the opening tag. If your store sells in several languages, taking the value from the locale means each version announces itself correctly.

What this looks like when an AI agent does the work

On our own Shopify test store, our AI agent fixed all 6 issues our check found within 6 minutes of connecting, and we then confirmed every fix on phone and desktop. One store, one run, one afternoon: it shows what is possible, not what to expect on yours.

Check yours with the widget off

Whatever you decide about a widget, look at your store the way your theme serves it. Turn the widget off on a duplicate or in a private test, run an automated checker on your home, collection, product and cart pages, then try each page with only a keyboard. Automated checks find some issues, not all of them. Ours tests only what software can test of WCAG 2.0 and 2.1, Levels A and AA, and does not test the newer WCAG 2.2 criteria such as target size.

I wrote the longer version, with the table of where each fix goes, on our site: accessibility widget vs a real fix in your Shopify theme. The widget script measurements are in our blocking-time study. You can also run our free, read-only homepage check and see the report for your own store.

Nothing here is legal advice, and no scan can tell you whether your store meets a law.

Have you measured what your own widget costs on mobile, or checked your store with it turned off?

Originally published at vibe-fixer.com. I run VibeFix, an AI agent that fixes accessibility issues in Shopify theme code and re-checks the live store.

Top comments (0)