How to Meet the New Accessibility Requirements of the Shopify Theme Store

Accessibility is a requirement of Shopify themes. To help make sure all themes on the Shopify Theme Store are highly usable, we’re introducing new accessibility requirements. In this article, learn what those requirements are, and how to test your theme to make sure you’re meeting them.

With the launch of Online Store 2.0 and the re-opening of the Shopify Theme Store to theme submissions, it’s a great time to consider building a Shopify theme. To help ensure that all Shopify themes are usable and accessible, we’re introducing new requirements and guidelines for all new theme submissions. 

Accessibility is becoming increasingly more important to merchants when selecting their theme. We want to share clear, concise expectations for our theme partners to follow when designing new themes, so you build with inclusive best practices in mind from the beginning.

In this article, we review those new theme accessibility requirements, and how to make your theme compatible.

The importance of accessibility

As theme designers and developers, you have the great responsibility to include accessibility and inclusive design best practices by default. This is critical for a few reasons:

• Providing inclusive access helps people with disabilities—about 15 percent of the global population—to live independently and with dignity.
• There exists potential for increased income from your theme as more people are able to use the theme successfully.
• Accessibility helps with performance and increases SEO.
• Not discriminating against people with disabilities who rely on assistive technology helps to build a positive public perception for merchants who use your theme.
• Baking accessibility into your theme from the beginning will help merchants avoid digital accessibility based lawsuits. Many accessibility laws and policies around the world require minimum WCAG 2.0 Level AA compliance.

Making your themes accessible is a priority—so, let’s dive into the accessibility requirements your theme must meet to be published in the Shopify Theme Store.

How to test for accessibility

As noted above, accessibility should be baked into every aspect of your theme build. To ensure that you’ve done so successfully, thorough accessibility testing is key.

Not all pages of your theme need to be tested (though we encourage you to do so). Specifically, we expect partners to focus on the “critical path.” That is, getting from the homepage to checkout with relative ease while using assistive technology.

"We expect partners to focus on the “critical path.” That is, getting from the homepage to checkout with relative ease while using assistive technology."

For example, could someone using just the keyboard successfully go from the homepage, a product page, add an item to the to cart, then on to checkout?

In addition, not all homepage sections need to be tested (though again, you are encouraged to do so). Focus on critical sections, such as header navigation, product callouts, and footer navigation.

Test theme defaults

Make sure theme settings, colors, layout, imagery, and content are shipped and bundled with accessible defaults. If a theme comes with more than one demo, focus on testing the default theme demo.

The purpose of creating accessible defaults is to set the merchant up for success right out of the box. Imagine the scenario where a merchant installs the theme and only uploads their product content. Without any other changes or customizations, the theme should provide a highly accessible user experience.

Test for objective accessibility issues

Prior to submitting your theme to the theme store, test for objective accessibility issues. Do this by running the Lighthouse suite of accessibility testing tools which is built into Google Chrome browser.

Your theme must have a minimum average Lighthouse accessibility score of 90.

The average score includes Lighthouse test results of these theme pages:

1. Home page
2. Product page
3. Collection page 
4. Cart page

Find the average score by running Lighthouse accessibility tests on each individual page. Add each page score together, then divide by four (since we’re testing four pages). Alternatively, create a new Google Spreadsheet and use the AVERAGE function to find the average score.

Example theme scoring.

Our theme review team will also run the same test method. We do this by running the Lighthouse accessibility tests against a benchmark store, then assign a single score showing how accessible the theme is, according to Lighthouse.

In order to correct any issues found, follow the directions provided by Lighthouse. Review the Accessibility audits documentation for possible issues found. Review the video Accessibility Testing—Totally Tooling Tips from Google Chrome Developers on how to use Lighthouse.

Test for subjective accessibility issues

In addition to the automated test requirements outlined above, the team will also conduct a series of manual tests to identify specific subjective accessibility issues. The purpose of this is to help catch common barriers to access while using assistive technologies. We take a look at these eight subjective accessibility issues below.

1. All parts of a page must be keyboard accessible

Not all users are able to use a mouse. Use the keyboard alone to test the navigability and functionality of your theme. From the homepage to checkout, all workflows must work with only the keyboard. All custom controls, links, buttons, and form inputs must be actionable.

Note: Content such as plain text, content containers, images, etc., are not to be keyboard accessible.

Common issues the themes team will review include:

• Dropdown navigation elements open on click, not on focus. This allows keyboard users to easily bypass the navigation area. Open on Enter or Space. Close on Esc, returning focus to the parent element.
• Modal windows must shift focus to or within itself. This helps orient the keyboard user to use the newly revealed content. Esc returns focus to the launcher element.
• Cart drawers which dynamically “fly out” from the side or top of the screen must shift focus to or within itself. This helps orient the keyboard user to use the newly revealed content. Esc returns focus to the launcher element.
• Product cards which often feature multiple links to the same page (image, title, “more details,” etc.) should be built in a way which results in a single tab-stop, yet allow all details to be navigated by assistive technology.

Dawn theme product cart drawer.

How to test

A few tips on how to use the keyboard for testing your theme:

• Use the Tab key to move forward through focusable elements on the page
• Use Shift+Tab to move backward
• Use Enter to activate links, Enter or Space to activate buttons, Space to activate checkbox/radio/select input controls
• Use Arrow keys to navigate between grouped radio controls

What to watch for

Items of interest during keyboard accessibility testing may include:

• Anchor elements are used to open new pages or shift focus to content on the same page/context.
• Form submit controls are not disabled by default.
• Buttons elements are used to activate modal windows/cart drawers and when activated, focus shifts to the window.
• Esc is supported to dismiss modal, cart, and dropdown contexts, returning focus to the activator control.
• Only natively focusable elements should be focusable. Links, buttons, form controls, etc. Static content such as plain text, images, etc, should not be focusable. Use the tabindex attribute with caution.

Resources

• WCAG 2.1.1 Keyboard – W3C
• Disclosure (Show/Hide) – WAI-ARIA Authoring Practices
• Dialog (Modal) – WAI-ARIA Authoring Practices
• Cards – Inclusive Components
• Keyboard access fundamentals – Google Developers
• Ensure all interactive features are keyboard-accessible – Deque University
• Keyboard – MDN
• Keyboard Accessibility – WebAIM

You might also like: 5 Steps to Design Apps with Keyboard Accessibility in Mind.

2. Form input elements must have labels with for attributes

Form input, textarea, and select controls require a programatically associated label. In order to provide context on the input purpose via accessible name computation, a label element must have its for attribute match the id of the related input element. Without a label, a screen reader user might not know or understand the purpose of the data required. Voice dictation users might not be able to call out the command to select the specified form input.

Using the placeholder attribute is not a substitute for a label, as its purpose is to provide sample data.

❌ Bad example: Implementing a visual “label” only

<div class="label">First Name</div>
<input type="text" name="first_name" autocomplete="given-name">

✅ Good example: Implementing the label element, programmatically assigned to its related input

<label for="firstName">First Name</label>
<input type="text" id="firstName" name="first_name" autocomplete="given-name">

Alternatively, applying the aria-label attribute with an explicit text value or aria-labelledby referencing an existing content container directly onto the input element provides an accessible name and will satisfy test requirements. Use these techniques when appropriate.

✅ Good example: Applying the aria-label attribute to provide a label

<input type="search" aria-label="Search" name="q">

Chrome Devtools showing the “Your email” label in a form.

How to test

The Lighthouse report will include if form fields are missing a label association. To test manually:

1. Open Chrome DevTools 
2. Ensure the form label element exists in the DOM
3. Inspect the for attribute value, making sure it matches the id of the associated input

What to watch for

Form inputs must be associated with a label, preferably an always visible label. Alternatively, applying the aria-label attribute with explicit text value or aria-labelledby referencing an existing content container directly onto the input element provides an accessible name and will satisfy test requirements.

Resources

• WCAG 3.3.2 Labels or Instructions – W3C
• Label form elements – Google Developers
• Use Labels for Forms to Maximize Screen Reader Compatibility – Deque University
• Label – MDN
• Associate Form Labels with Controls – WebAIM

3. Themes must be built with valid HTML

Valid HTML helps to ensure a robust, device/browser-agnostic experience. It also helps to ensure an accessible user experience. By serving valid HTML, the browser will take information from the DOM and supply the details required for assistive technology to consume. These details make up what’s called the accessibility tree.

Always write/generate valid HTML per the HTML specification.

How to test

• If the test store is public, copy the URL and paste into Nu Html Checker
• If the store is password protected:

1. Open the DevTools inspector
2. Copy the code from the inspector window
3. Paste into the Nu Html Checker – Textarea

What to watch for

Address all reported Errors. Warnings are typically safe to ignore, but use your best judgement.

Resources

• WCAG 4.1.1 Parsing – W3C
• HTML specification – WHATWG
• The Accessibility Tree – Google Developers
• Use Valid Markup to Prevent Possible Accessibility Issues – Deque University
• HTML – MDN

4. Must output image.alt for all product images

Demo store product image alt text must describe the product; what it is, its physical features, how a model is wearing/using the product, etc. Provide enough information to build the mental image in the user’s mind, but not too many details to overwhelm the user. This helps screen reader users to understand what the product is.

Supplying the product title in place of an image description is not satisfactory.

Product alt text should be provided in each template where the image appears; homepage featured product section, collection pages, product variant images, cart, etc. This helps to provide product context throughout the user journey.

❌ Bad example: Using the product title as image alt text

<img src="{product.image.src}" alt="{product.title}">

✅ Good example: Using image alt text as provided by the merchant

<img src="{product.image.src}" alt="{product.image.alt}">

Consider the following product image. How would you describe the product to someone who couldn’t see the image?

Product alt text should describe this product to someone who can’t see it.

The generated markup for this image could be something like:

<img src="dress.jpg" alt="Leather dress with thin, rounded black collar in front and back, short black sleeves. Dress pattern is made up of colored and symmetrical vertical rectangles. Colors include mostly various shades of blue with a small amount of yellow, white, red, maroon and grey. Waist tapers inward.">

How to test

Use Chrome DevTools to inspect product images.

Alternatively, use a screen reader on your platform of choice: VoiceOver on macOS or NVDA on Windows. Use the virtual cursor to navigate the page content and listen to how each product image is described.

What to watch for

The alt value should describe the product. Provide enough information to build the mental image in the user’s mind, but not too many details to overwhelm the user.

Good alternative text shares details on what the image is conveying, its content. Read more details in the article Considerations When Writing Alt Text on the Shopify UX blog.

Resources

• WCAG 1.1.1 Non-text Content – W3C
• Include text alternatives for images and objects – Google Developers
• Alt Text Should Describe the Purpose of the Image – Deque University
• The Image Embed element – MDN
• Alternative Text – WebAIM

5. Test color contrast

The color contrast between background and foreground content (usually text) should be great enough to ensure legibility. Users with low-vision, color blindness, or anyone out in direct sunlight require enough contrast for text and non-text content to be perceivable.

Chrome Devtools showing the color contrast ratio of a button.

How to test

Lighthouse will report if contrast issues are found.

To manually test colors (such as text over a background image) use the macOS Digital Color Meter or a similar tool to select the color values, then use Contrast Ratio to test the contrast.

What to watch for

• Text content and control text in its default, hover, focus, or active state must meet 1.4.3: Contrast (Minimum):
• Contrast ratio of 4.5:1 for normal size text (below 24 pixels or 18 pixels, bold)
• Contrast ratio of 3:1 for large text (at or above 24 pixels or 18 pixels, bold)
• Control borders, adjacent background (if no border), icons, and custom focus rings must meet 1.4.11: Non-text Contrast:
• Contrast ratio of 3:1 for non-text content against its adjacent background
• Review active user interface component examples for more details.

Components which are exempt from the above:

• Controls in a disabled state via disabled attribute
• Default browser focus rings
• Text embedded within imagery which is meant to be decorative
• Logos

Resources

• WCAG 1.4.3 Contrast (Minimum) – W3C
• 1.4.11 Non-text Contrast – W3C
• Color and contrast accessibility – Google Developers
• Check Text and Background for Sufficient Color Contrast – Deque University
• Color contrast – MDN
• Contrast and Color Accessibility – WebAIM

6. Focusable elements must feature a visible focus state

Sighted keyboard-only, voice dictation, low-vision, and other user groups not able to use a mouse must have an understanding of the current keyboard cursor position.

The keyboard cursor position is represented by the focus ring. In CSS, the focus ring is typically described using the outline property. We strongly advise to not remove the default focus ring.

❌ Bad example: removing the focus ring for all users

*:focus {
 outline: none;
}

✅ Good example: Not removing the default focus ring

*:focus {
/* outline: none; */
}

As an alternative, consider applying the :focus-visible pseudo-class. This would remove the visible focus ring for mouse and touch users but remain for keyboard-only users. Use with caution as native browser support is limited.

✅ Good example: Using the :focus-visible pseudo-class to remove the focus ring for mouse/touch users only

*:focus:not(:focus-visible) {
 outline: none;
}

If a custom focus ring is present, its color contrast must adhere to the 3:1 ratio.

Dawn homepage “Shop bestsellers” section showing the custom focus ring.

How to test

Test by using the Tab key to move keyboard focus forward, Shift+Tab to move backward.

What to watch for

While navigating around the page using only the keyboard, are you able to see a visual focus ring? Do you know where the keyboard focus is located on the page?

Actionable page elements such as links, buttons, form controls are to feature a visual focus ring when in focus.

Resources

• WCAG 2.4.7 Focus Visible – W3C
• Style focus – Google Developers
• Enhancing Visual Focus for the Sighted Keyboard User – Deque University
• outline – MDN
• :focus-visible – MDN
• Focus indicators – WebAIM

7. Visible focus order must match DOM order

Keyboard focus rings are expected to move in a linear, predictable order: top-to-bottom, left-to-right (localized to right-to-left when appropriate—focus order should match reading order.) Focus shifting in an unexpected direction due to CSS content reordering can cause issues for low-vision, cognitive impairment, or neurodivergent users.

"Focus shifting in an unexpected direction due to CSS content reordering can cause issues for low-vision, cognitive impairment, or neurodivergent users."

For example, CSS properties such as flex-direction with a value of row-reverse should be avoided when possible. The basic rule of thumb to follow is to ensure the visible focus order matches the DOM order. This also holds true across breakpoints, including "mobile" layouts.

❌ Bad example: reversing content visually only

.box {
 display: flex;
 flex-direction: row-reverse;
}

✅ Good example: Content flows as outlined in the DOM

.box {
 display: flex;
 flex-direction: row;
}

How to test

Use the Tab key to move keyboard focus forward, Shift+Tab to move backward.

What to watch for

The keyboard focus ring is expected to move from top-to-bottom, left-to-right (localized to right-to-left when appropriate.)

Resources

• WCAG 2.4.3 Focus Order – W3C
• Content reordering – Google Developers
• Navigation order – WebAIM

8. Touch target size

Users with fine motor control impairments require large touch target sizing to be usable. If touch targets are too small, users may miss and activate another control unintentionally. This includes mouse/touch users as well as the aging population.

WCAG 2.5.5 Target Size specifies a target size of 44 by 44 CSS pixels. This applies to mobile navigation toggles, form inputs, navigation items, etc.—all critical navigation and input methods. Links within body copy are exempt.

Note: Use the CSS padding property to increase the physical size of the control without disrupting the intended design.

❌ Bad example: Using fixed width and height via pixel values

.navigation-toggle {
 height: 32px;
 width: 32px;
}

✅ Good example: Using flexible units and padding to increase touch target size

.navigation-toggle {
 height: 2em;
 width: 2em;
 padding: 1.25em;
}

Chrome Devtools on the Dawn homepage showing the physical size of the login link.

How to test

Use Chrome DevTools to quickly inspect the physical size of the control. Size is indicated in the top-right corner of the inspect window.

What to watch for

Critical items such as mobile navigation toggles, form input/buttons, etc., should have a physical touch target size of at least 44 by 44 CSS pixels.

Resources

• WCAG 2.5.5 Target Size – W3C
• Accessible tap targets – Google Developers
• Large touch targets – The A11Y Project

Making your themes accessible

Additional documentation for theme accessibility can be found on the theme store requirements and the accessibility best practices for Shopify themes pages on Shopify.dev.

Developers who use VS Code are encouraged to install the axe Accessibility Linter plugin. This linter watches for and reports any markup issues which could lead to accessibility barriers while you edit your theme templates.

For taking your theme accessibility to the next level, consider reaching out to Shopify partner Fable Tech Labs. Integrating feedback from people who rely on assistive technologies would increase the accessibility and usability of your theme.

If you have questions regarding these new Theme Store requirements, or about digital accessibility in general, reach out to the team on the #a11y channel at Shopify Theme Partners on Slack.

Meeting these requirements won’t just let you publish your theme in the Shopify Theme Store—you’ll also set your merchants and their shoppers up for success.