Help CenterContact support
All Custos: EU Compliance articles

How do I scan my theme and fix accessibility issues?

Updated

On this page
  1. Run a scan
  2. Fix an issue
  3. One-click theme fixes
  4. Good to know

The Accessibility module checks your published theme and main storefront pages against a set of WCAG 2.1 A and AA rules that can be tested automatically, and explains each issue it finds. Automated checks find some issues, not all: see “Good to know” below.

Run a scan

  1. Open Accessibility > Issues and click Run scan. A scan usually takes under a minute.
  2. The scan checks:
    • the theme’s layout, section and snippet files;
    • one or two pages for each template your store uses (home, collection, product, cart, content pages…), opened in a browser at desktop and mobile size, so issues that appear only once the page has loaded are found too;
    • every product’s description (images, links, headings, tables, text colour) and image alt text. Each issue names the theme file it comes from where it can, and how far it reaches, for example Shows on every page or Affects 120 products. The line above the list says how many templates were rendered and how many products were checked.
  3. When the AI review is available, it also looks for texts automated rules cannot judge: alt texts that do not describe the image, link texts that do not say where they go, headings that do not describe their section and unclear form labels. These issues carry an AI review badge and a confidence, and an AI model can be wrong: check each one before you change anything.
  4. After your first scan, the app scans again every week and after you publish another theme. When you save your published theme, it rechecks the files you changed; when you create or edit a product, it rechecks that product.
  5. The app waits between pages so your store is not slowed down. A page the store did not send (for example when it was busy) is listed as skipped, and the scan says so instead of counting it as clean.

Each issue shows its Severity (critical, serious, moderate, minor), the WCAG success criterion and level, and Where it was found. Filter by severity with Severity.

Fix an issue

Click an issue to open it. You see the code the scan found and How to fix it, with a link to the W3C’s explanation of the criterion. The Status column tells you what kind of fix it is:

  • Code fix ready: the page shows the file, the code Now and After the fix, and the steps:
    1. Click Open in the code editor to open the file in your theme’s code editor.
    2. Find the code shown under Now (Ctrl+F or Cmd+F).
    3. For a button or link without a name, write the Accessible name (aria-label) a screen reader announces, for example “Cart” or “Open menu”, then click Copy fixed code.
    4. Replace the code, save the file, then scan again to check it.
  • Guided fix: follow the steps under How to fix it, usually in the theme editor.
  • Alt text editor: click Open alt text editor. See write alt text for product images.

One-click theme fixes

One-click fixes appear only when the app has them switched on. Until then, every theme fix is a guided fix you copy into your theme yourself, as above. When a one-click fix is available for an issue, the issue page shows Apply fix:

  1. Check the code under Now and After the fix.
  2. Click Apply fix, then confirm. The app saves the file as it is now, then changes it in your published theme.
  3. The issue shows Fixed by the app. The change is listed under Changes, where you can undo it: see undo a change.

The app never changes your theme files from a scan on its own: a theme file changes only when you click Apply fix.

Good to know

  • Automated checks find only part of the barriers a visitor can meet. Test with a keyboard and a screen reader too.
  • If the browser check is not available for a scan, the pages are checked as your storefront sends them, and content that scripts add later (including some other apps’ blocks) is not checked. The line above the list tells you.
  • A password-protected store is checked from its theme files only. Remove the storefront password in Online Store > Preferences to check the pages too.
  • If you publish another theme after a scan, run the scan again before you copy or apply a fix.
  • A clean scan does not mean a store is accessible or meets any law. See accessibility rules: WCAG, EAA and ADA.
  • To keep a record of what the scan found and what you changed, see export an evidence report.

Built and supported by StoreFleet, Shopify app developers since 2021.