Accessibility fixes in your Shopify theme’s code

A layout whose <html> element has no lang attribute, an empty one or an invalid one gets the language your store is showing, so screen readers pronounce the page in the right language. Where the theme already keeps a page’s own language in a metafield, for example for German legal pages in an English store, the layout uses that metafield when it is set. Without such a field the recipe does not guess a page’s language.

A “Skip to content” link becomes the first element of each page. It stays hidden until a keyboard user reaches it, and it leads to the main content, which is marked as the page’s main area. Navigation areas that appear on the same page get distinct names, such as Main menu, Footer menu or Breadcrumbs, and content outside every page area, such as an announcement bar, becomes a named region. An existing skip link that points nowhere is pointed at the main content. Which of these changes are made depends on what the scan found.

Every layout whose <title> is missing, empty or the same fixed text on every page gets a title built from Shopify’s variables. If your main layout already has a title that names the page, the other layouts get the same one. Otherwise the title holds the page title, the page number of a paginated list and the shop name, with the word for “page” translated through the theme’s locale files.

A heading that skips a level, such as an h4 right after an h2, gets the next level below the heading before it, in the section file where it is written. Where the theme styles headings by their level, a small style rule keeps the heading’s old look. A page without a main heading gets the element that already looks like its title turned into the h1; on the home page that is the theme’s own option to show the logo as the h1. If a page has no such element, the recipe adds no hidden heading, because that is a content decision.

The main stylesheet gets one outline for keyboard focus: 2 pixels, solid, 2 pixels away from the element, in your theme’s accent colour (or its text colour, or black or white, where the theme has no accent colour), made lighter or darker in the same hue until it has a contrast of at least 3:1 against the page background. Theme rules that would still hide the outline lose their outline: none, unless they show focus in another way, such as a border or a shadow. The outline has one colour for the whole theme, so on sections with a dark colour scheme it may need a lighter colour, which your developer checks in the preview.

A tabindex above 0 pulls an element to the front of the keyboard order. The recipe removes it from links, buttons, form fields and other elements that can take focus anyway, and sets it to 0 on other elements, so they stay reachable while the Tab key follows the order of the page. A tabindex that the theme’s template code writes is left to a person. The recipe also handles the findings of the focus order check vs-focus-order that are about a tabindex above 0; the rest of that check stays MANUAL.

Clickable elements that only work with a mouse, such as slideshow dots or the choices in a cookie banner built from <div> or <span> elements, become real <button> elements. Every class and attribute stays, so the theme’s script keeps working, and Enter and Space now do what a click does. A button without a name gets one from its purpose, for example “Load slide 2 of 3”, and a small style reset keeps its look. An element that no script listens to, or whose purpose is unclear, is left as it is.

The recipe removes user-scalable=no and any maximum-scale below 5 from the viewport tags in the theme’s Liquid files, so visitors can pinch-zoom your store up to 500 %. The other viewport settings stay exactly as they were. A zoom limit that the theme’s template code sets is left to a person.

Controls that the scan found too small, such as header icons, colour swatches or quantity buttons, get a minimum size of 24 by 24 pixels in the main stylesheet, addressed by their class. The icons inside them keep their size. A link or other element that the theme leaves inline is made inline-flex with its icon centred, because inline elements ignore a minimum size.

When text fails the contrast check and its colour is defined in a single place, that colour moves to the nearest lighter or darker shade of the same hue that reaches the required contrast against every background the scan reported for it. The place can be the stylesheet rule that styles the text, or a CSS variable or a colour setting in config/settings_data.json that nothing else in the theme uses. A colour that is computed in Liquid or defined more than once is left to a person, and so is a shared colour, because changing it would affect colour pairs the scan did not measure.

When a visitor’s device is set to reduce motion, a block at the end of the main stylesheet lets every CSS animation run only once, too briefly to see, shortens transitions and turns smooth scrolling off. Where the theme’s script starts a slideshow’s autoplay itself, the start is skipped for those visitors. Motion that a third-party script drives is not changed by this recipe.

A slideshow that moves on its own gets a visible, translated button to pause and play it, among its controls and shown only when autoplay is on. A short script in the theme’s main script file connects the button to the slider’s own autoplay: Dawn’s slideshow, Swiper, Slick, Flickity, Splide, or a CSS animation. For visitors whose device asks for reduced motion, the slideshow starts paused.

<blink> and <marquee> elements in the theme become static elements with the same content, classes and ids: a <span> for blink, a <div> for marquee, or a <span> where the marquee sits inside a paragraph or a link. The marquee’s scrolling settings are removed, so no text moves on its own.

A video that plays on its own gets muted and playsinline, so it keeps playing silently, as a background video does, and Shopify’s video_tag filter gets muted: true. Audio that starts by itself no longer does. Embedded YouTube and Vimeo players are left to a person. In a Validiscan scan, sound that starts by itself is reported by the media check vs-media, which takes the place of the axe-core rule this recipe serves. vs-media has the tier MANUAL, and on Shopify this recipe is not used for its findings.

A form field whose label text is already visible on the page, but not connected to the field, gets connected: a <label> next to it gets a for that points at the field, or a text just before the field, such as the name of a size or colour option, becomes its label through aria-labelledby, so the layout does not change. Screen readers then read the label when the field gets focus. A field that only has a placeholder is left to a person, because writing a label is a content decision.

Address, account, login and contact fields that the scan flagged get the autocomplete value for what they ask for, such as email, first and last name, street address, postal code, country, phone number or password. The value is worked out from the field’s type, name, label and placeholder. Where a snippet prints its fields from parameters, the fields print an autocomplete parameter, and each render call of the snippet passes the value its own arguments call for. Browsers can then fill the fields in, and assistive technology can tell what each one is for. A field whose purpose the code does not show is left as it is.

The part of a page that the theme’s script rewrites when a customer picks another variant or changes a quantity, such as the price, the stock note or the cart subtotal, is marked as a status region. Screen readers then announce the new value without the customer having to move there. The theme’s script itself is not changed. An area that also holds buttons or links, which would be read out with it, is left as it is.

Buttons and links that show only an icon, such as search, cart, account, slideshow arrows, quantity buttons and cookie choices, get a name that says what they do, where the code shows their purpose. The name is visually hidden text inside the control, or an aria-label where the theme has no class for hidden text. A logo link whose image has no text alternative gets your shop name. A control whose name would have to come from your own content is left to a person.

An image is marked as decorative only when the code proves it adds nothing: it sits in a link or button that has its own text, it is an icon next to its own text label, or it is a spacer or divider. An <img> then gets an empty alt="", and an SVG icon gets aria-hidden="true", so screen readers skip it instead of reading out a file name or the word “image”. Every other image is content, and its text alternative is left to a person.

An embedded frame without a title, such as a map or a YouTube or Vimeo video, gets a translated title that says what it shows. The recipe reads that from the frame’s source address or content. A frame whose content the code does not show gets no generic title; it is left to a person.