Accessibility Fix Guide

Step-by-step instructions for resolving accessibility audit findings. Improving accessibility also improves SEO — search engines reward well-structured, accessible pages.

Note

Accessibility fixes improve your store for all visitors, including those using screen readers, keyboard navigation, or high-contrast modes. Many of these changes also benefit SEO.

Colour Contrast

Insufficient text colour contrast

Text on the page doesn't have enough contrast against its background. WCAG AA requires a minimum ratio of 4.5:1 for normal text and 3:1 for large text.

Identify the affected elements from the audit findings.

Use the WebAIM Contrast Checker to test colour combinations and find compliant alternatives.

Update the CSS in your theme stylesheet or theme editor. If the colours are set via theme settings, go to Themes → Customize → Theme settings → Colours.

Test across different page types and in both light and dark mode if your theme supports it.

Colour contrast issues (general)

Broader colour contrast issues detected beyond individual text elements — buttons, links, or decorative elements may also have insufficient contrast.

Review the contrast findings and identify affected elements.

Update CSS variables or stylesheets for the affected selectors.

Test across all page types after making changes.

Headings & Landmarks

Incorrect heading hierarchy

Headings skip levels (e.g. <h1> followed by <h3> with no <h2>). Screen readers use heading levels to build a page outline.

Review heading structure in the relevant theme templates.

Ensure logical hierarchy: h1 → h2 → h3. Each page should have exactly one <h1>.

Don't skip levels. If you need a smaller visual style, use CSS instead of a lower heading level.

Missing main landmark

The page has no <main> element. Screen reader users rely on landmarks to jump directly to the main content.

Open Themes → Edit code → layout/theme.liquid.

Wrap the main content area in a <main> element. Ensure there is exactly one per page.

The typical location is around the {{ content_for_layout }} tag.

Focus & Keyboard Navigation

Missing focus indicators

Interactive elements (links, buttons, inputs) have no visible focus ring when navigated with a keyboard. This makes keyboard navigation impossible to follow visually.

Check your theme's CSS for outline: none or outline: 0 rules. These remove the browser's default focus ring.

Add visible focus styles using :focus-visible:

:focus-visible {
  outline: 2px solid #005bd3;
  outline-offset: 2px;
}

Ensure focus indicators have at least 3:1 contrast against the background. Test keyboard navigation throughout the store.

Modal missing focus trap

When a modal/dialog opens, focus can escape to elements behind it. This confuses keyboard and screen reader users.

When the modal opens, move focus to the first focusable element inside it.

Trap Tab and Shift+Tab so they cycle only within the modal.

When the modal closes, return focus to the element that opened it.

Ensure Escape closes the modal. Add role="dialog" and aria-modal="true" to the modal container.

Forms & Labels

Variant selectors missing fieldset

Product variant radio buttons (Size, Colour, etc.) aren't grouped in a <fieldset> with a <legend>. Screen readers can't tell what the options belong to.

Find the variant selector template in your theme (often in sections/main-product.liquid or a snippet).

Wrap each group of radio buttons in <fieldset> and add a <legend> with the variant name (e.g. "Size", "Colour").

Gallery thumbnails missing labels

Product gallery thumbnail buttons have no accessible label. Screen readers announce them as unlabelled buttons.

Find the product gallery thumbnail template in your theme.

Add aria-label attributes like "View image 1", "View image 2" to each thumbnail button.

Add aria-current="true" to the currently active thumbnail.

Interactive Components

Carousel controls missing labels

Carousel/slider navigation buttons (next, previous, dots) have no accessible labels.