Skip to content
Tutorials Center
My learning

Topics

Lesson 41 of 61 ยท Performance and Quality

Accessibility in Themes

Build accessible Shopify themes: landmarks, headings, skip links, keyboard menus, live cart announcements, contrast, reduced motion, labels and screen reader testing.

An accessible store is one that people can use with a keyboard, a screen reader, voice control, a small screen, poor eyesight or a shaky hand. That is a large group of shoppers, and in many countries it is also a legal requirement for online shops. Accessibility is also good engineering: the same clean landmarks, labels and focus handling that help a screen reader user help search engines, automated tests and every other developer who touches your theme.

Most accessibility problems in themes are not exotic. They are an image without a description, a button with only an icon, a menu that opens on hover only, or a cart that changes without telling anyone. This lesson covers the issues you will meet most often, with read-only Liquid and HTML for the real theme and live stand-ins you can run: a small checker that finds common mistakes in markup, and a keyboard-friendly disclosure menu.

This lesson teaches practical techniques that fit the WCAG success criteria at levels A and AA. It is not legal advice, and automated tools only find a fraction of the problems. Always combine them with keyboard and screen reader testing.

Start with the structure

Semantic HTML gives you most of accessibility for free. Browsers and assistive technologies understand header, nav, main and footer without any extra attributes.

  • Use one <main> per page. In a theme, layout/theme.liquid wraps {{ content_for_layout }} in <main id="MainContent">.
  • Use landmarks once, or label them when repeated: <nav aria-label="Primary"> and <nav aria-label="Footer"> let a screen reader user jump between regions and tell them apart.
  • Set the lang attribute on <html> from the current locale, as in <html lang="{{ request.locale.iso_code }}">, so screen readers pick the right pronunciation (see Translations, Markets and Localization).
  • Use real buttons and links. A <button> triggers an action, an <a href> navigates. A <div onclick> does neither for a keyboard user.
LIQUID
<a class="skip-link" href="#MainContent">{{ 'accessibility.skip_to_content' | t }}</a>
<header>
  <nav aria-label="{{ 'general.navigation.primary' | t }}">
    ...
  </nav>
</header>
<main id="MainContent" tabindex="-1">
  {{ content_for_layout }}
</main>

The skip link is the first focusable element. It is usually hidden until it receives focus, then lets keyboard users jump past the header and menu to the content. tabindex="-1" on main allows the browser to move focus there when the link is activated.

Headings tell the story

Screen reader users often navigate by headings. Keep them in a logical outline:

  • One <h1> per page (the product title, the collection title, the page title).
  • Do not skip levels (h2 to h4) just to get a smaller size. Choose the right level, then style it with CSS.
  • Sections that are visual blocks, such as a hero banner, should still have a sensible heading. If a section has no visible heading, make a visually hidden one so it has a label.

A section schema can expose a heading level setting (a select of h2, h3, h4) so merchants can fix the outline without editing code. See Schema Settings.

Focus: visible, ordered and managed

Keyboard users move with Tab, Shift+Tab, Enter, Space, Escape and the arrow keys. Three rules prevent most problems:

  1. Never remove the focus outline without replacing it. outline: none with nothing else makes the page unusable for sighted keyboard users. Style :focus-visible instead so the ring appears for keyboard use.
  2. Keep DOM order equal to visual order. Do not rely on tabindex greater than 0, and be careful with CSS that visually reorders content.
  3. Move focus on purpose. When a drawer, modal or menu opens, send focus into it. When it closes, return focus to the control that opened it. Building a Cart Drawer shows the full pattern.
CSS
:focus-visible {
  outline: 3px solid var(--color-focus, #1a5fd1);
  outline-offset: 2px;
}

Names, labels and alternative text

Every control needs an accessible name: text a screen reader can announce.

  • Form fields need a <label for="id"> (or a wrapping label). A placeholder is not a label, because it disappears while typing and has weak contrast. See Forms: Contact, Newsletter and Custom Forms.
  • Icon buttons need text: either visible text, a visually hidden <span>, or aria-label. A cart icon button should say "Cart", and ideally the count too.
  • Images need alt text that describes their purpose. Product images usually come from the image's alt text in the admin (image.alt). Purely decorative images get an empty alt="" so they are skipped.
  • Links should make sense out of context. "Read more" repeated ten times is useless in a list of links; use "Read more about winter care".
LIQUID
<button type="button" class="icon-button" aria-label="{{ 'cart.title' | t }}">
  {% render 'icon-cart' %}
  <span class="visually-hidden">{{ cart.item_count }}</span>
</button>

Use aria-label as a last resort. Visible text is better for everyone, including voice control users who say the words they can see.

A navigation menu that opens when the mouse hovers is unreachable by keyboard and touch. Build menus as disclosures: a button that toggles a list.

  • The button has aria-expanded="false" or "true" and, optionally, aria-controls with the id of the panel.
  • Enter and Space (native for buttons) toggle it. Escape closes it and returns focus to the button.
  • Tab moves through the links inside the open panel. Do not use ARIA role="menu" for site navigation: that role promises application-style arrow-key behavior that a website menu does not implement.

Project: An Accessible Mega Menu builds a full example. The same logic applies to accordions, tabs and product filters.

flowchart LR
  A["Button: aria-expanded=false"] -->|"Enter or Space"| B["Panel shown<br/>aria-expanded=true"]
  B -->|"Tab"| C["Links inside the panel"]
  B -->|"Escape"| D["Panel hidden"]
  C -->|"Escape"| D
  D --> E["Focus returns to the button"]

A disclosure menu: the button opens it, Escape closes it, and focus goes back to where the user started.

Announcing changes: live regions

When a cart count changes, a price updates after a variant change, or an error appears after a failed add-to-cart, sighted users see it. Screen reader users hear nothing unless you tell them. An aria-live region fixes this:

HTML
<div id="cart-status" class="visually-hidden" role="status" aria-live="polite"></div>

After an Ajax update, write a short message into that element: "Added to cart. 3 items in cart." Use polite (wait for the user to pause) for most updates and assertive only for urgent errors. The element must exist in the page before you change its text, otherwise the update may not be announced. For error messages tied to a field, link them with aria-describedby and set aria-invalid="true" on the invalid input.

Color, contrast and motion

  • Contrast. Normal text needs a contrast ratio of at least 4.5:1 against its background at WCAG level AA; large text needs 3:1. Because merchants choose their own colors, offer color schemes with checked pairs, and consider warning in the schema info text. Do not use color alone to show state (an error that is only red, a selected swatch that is only a thicker border).
  • Reduced motion. Some people get sick from parallax and large animations. Respect their system setting:
CSS
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    scroll-behavior: auto !important;
    transition-duration: 0.01ms !important;
  }
}
  • Zoom and text size. Use rem for type, never set maximum-scale=1 in the viewport meta tag, and test at 200 percent zoom. Touch targets should be comfortably large (at least about 24 by 24 CSS pixels, and larger is better).

Stand-in: a small accessibility checker

Real tools such as axe, Lighthouse and the browser's accessibility panel check hundreds of rules. This stand-in implements six of them on a sample of markup, so you can see how an automated check works and what it cannot judge. Press the button, then fix the markup in the box and press it again.

Stand-in: find common accessibility mistakes

On the sample markup the checker reports seven problems: no lang, no main, an image without alt, a heading jump from h1 to h3, an unlabeled email field, a nameless icon button and the "click here" link. Add lang="en", a <main>, an alt, a label and so on until it reports none. Notice what it cannot tell you: whether the alt text is good, whether the colors have enough contrast, or whether the focus order makes sense. Those need a human.

Stand-in: a keyboard-friendly disclosure menu

This menu follows the rules above: it is a real button with aria-expanded, it opens on click or Enter/Space, Escape closes it and returns focus, and a live region reports the state. Try it with only the keyboard.

Stand-in: disclosure menu with Escape and live region

A button already handles Enter and Space, so there is no custom key code for them. That is the benefit of using the right element.

Testing for real

  1. Keyboard only. Unplug the mouse. Can you reach everything, see where focus is, and operate every control?
  2. Zoom to 200 percent and check on a narrow viewport. Nothing should overlap or hide.
  3. Screen reader. Use NVDA or JAWS on Windows, VoiceOver on macOS and iOS, TalkBack on Android. Listen to a product page and the checkout path.
  4. Automated tools. Lighthouse and axe catch missing labels and low contrast. They do not replace steps 1 to 3.
  5. Contrast checkers for the color schemes you ship.

Remember that checkout is controlled by Shopify, so your accessibility work covers the storefront, cart and account pages.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the purpose of a skip link?

    It is the first focusable element and moves focus to the main region, so keyboard users avoid tabbing through the whole header on every page.
  2. 2. Which markup gives an icon-only button an accessible name?

    aria-label (or visually hidden text) supplies a name. An empty title or no text leaves the button unnamed, and a div is not keyboard operable.
  3. 3. A customer adds an item and the cart count changes silently. What fixes it for screen reader users?

    A polite live region announces text changes. It must be in the DOM before you update it.
  4. 4. Which statement about outline and focus is correct?

    Keyboard users need a visible focus indicator. Keep DOM order logical instead of using positive tabindex values.

Summary

  • Semantic landmarks, one main, a skip link and a correct lang give a strong base.
  • Keep headings in order, give every control an accessible name, and use real buttons and links.
  • Show focus with :focus-visible, keep DOM order logical and move focus on purpose in drawers and menus.
  • Announce cart and form changes through aria-live regions and link errors to fields.
  • Meet contrast ratios, never rely on color alone, and honor prefers-reduced-motion.
  • Automated checkers find some problems; keyboard and screen reader testing finds the rest.

Next, help search engines and shoppers find your pages in SEO in Themes.