Accessibility fixes in your WooCommerce theme’s code

The recipe makes the <html> element of your header templates take its language from WordPress’s language_attributes(), which prints the site language, or the language a multilingual plugin sets, so screen readers pronounce the page correctly. A header template that leaves the language out gets the call added, and a fixed lang value that is not valid is replaced by it. If the wrong value comes from the Site Language setting in your WordPress admin, the recipe changes nothing, because that is a setting and not theme code. Where the theme already reads a language field for each page, for example for German legal pages in an English shop, a filter in functions.php declares that page’s language, and the site header and footer keep the shop’s language. Without such a field the recipe does not guess the language.

Each header template without a skip link gets a “Skip to content” link right after the opening <body> tag, or after the wp_body_open() call that follows it. It stays hidden until it receives focus and jumps to the page’s content. If your theme is a child theme of Storefront and switched off Storefront’s skip links, they are switched back on instead. Where the templates have no main area yet, the content wrapper of the page templates, a <div> with the id main or the class site-main, becomes a <main> element, which marks it as the page’s main area; where the theme’s styles or scripts select that wrapper as a div, it stays as it is. Navigation areas whose purpose shows in their id or class get a name, such as Primary navigation, Breadcrumb, Footer navigation or Pagination. An existing skip link that points nowhere is pointed at the content. The link text and the names are added in English.

WordPress builds a page title on its own, from the name of the page or product, the page number of a paginated list and the shop name. The recipe repairs what in the theme stops that title from appearing. A title filter that returns a custom title, for example from an SEO field, falls back to the generated title when the field is empty. A fixed <title> text in a header template is replaced by the title WordPress generates. A theme that is not a child theme and prints no title at all gets WordPress’s title support switched on in functions.php. When the title comes from an SEO plugin or from a page’s own settings, the recipe changes nothing.

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 template or in the PHP string that prints it. Widget titles and headings in the footer or a sidebar become h2. When the skip comes from a WooCommerce template shown right after the page title, such as Billing details and Shipping details at the checkout, the headings of the same level in the neighbouring templates move with it. Only the level changes: each heading keeps its classes, and a heading that the theme’s styles or scripts select by its level is left as it is. A heading without a class takes the theme’s look for its new level. A page without a main heading gets the element that already looks like its title, with a title class set to at least 24 pixels, turned into the h1. If a page has no such element, the recipe adds no heading and leaves it to a person.

The theme’s main stylesheet gets one outline for keyboard focus: 2 pixels, solid, 2 pixels away from the element, in a colour the theme already uses. That is a colour variable whose name says focus, accent, brand, primary or link, or else the colour of links or of the body text. The first of these with a contrast of at least 3:1 against the page background is used; if none has it, the first is made lighter or darker in the same hue until it does. On dark areas with light text, such as a dark top bar, the outline takes the light text colour. An outline: none on focus that leaves nothing in its place is removed from the theme’s rules; rules that hide the outline only for mouse clicks stay. A theme that already has a visible focus outline, and no rule that hides it, is left as it is.

A tabindex above 0 pulls an element to the front of the keyboard order. The recipe removes it from links, buttons and form fields, which 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. Only the template tag that renders the reported element is changed. A tabindex that PHP code prints or a script sets is left to a person.

Inside a cookie banner or a slideshow that is part of your theme, clickable <span>, <div>, <li> or <i> elements that only work with a mouse become real <button> elements. Every class and attribute stays, so the theme’s styles and scripts keep working, and Enter and Space now do what a click does. A short style reset for exactly those classes keeps their look. An icon-only button in the same banner or slideshow gets a name in English, as described under the icon names below. An element that no script listens to, one that the theme styles or scripts by its tag name, or an empty one whose purpose is unclear, is left as it is.

The recipe removes user-scalable=no and a maximum-scale below 2 from the viewport tag, in the header templates or in the PHP code that prints the tag, so visitors can pinch-zoom your shop again. For axe-core’s stricter rule meta-viewport-large, any maximum-scale below 5 is removed. The other viewport settings stay exactly as they were. A viewport tag whose content PHP computes, or one that a plugin prints, is left to a person.

Controls that the scan found smaller than 24 by 24 pixels, such as social icons, colour swatches or quantity buttons, get that minimum size. The recipe finds the stylesheet rules that give exactly those elements a fixed width or height below 24 pixels and raises it to 24 pixels; where the element lays out its icon with flexbox or grid, the icon is centred so it does not sit in a corner. A control whose size comes from padding or from its content cannot be measured from the stylesheets and is left to a person.

When text fails the contrast check and its colour is defined in one place in the theme’s stylesheets, as a CSS variable or as the colour of the rule that styles that text, that colour moves to the nearest lighter or darker shade of the same hue that reaches the contrast the scan measured as required, on every background it measured. A colour that is defined in several places, that would also change elements whose contrast the scan did not measure, or that the theme also uses for backgrounds or borders, is left to a person.

When a visitor’s device is set to reduce motion, a block at the end of the theme’s main stylesheet lets each animation run once, too briefly to see, so it stops in its final state; transitions become instant and smooth scrolling is turned off. Where the theme’s own scripts start a slideshow’s autoplay, with Slick, Swiper, Splide, Owl or Flickity, the autoplay starts only for visitors who have not asked for reduced motion. Motion that comes from a plugin or an inline script is not changed.

A slideshow in your theme’s templates that moves on its own gets a visible button to pause and play it, labelled “Pause slideshow” and “Play slideshow” in English. The button becomes the slideshow’s first element, so keyboard users reach it before the slides. A short script in the theme’s main script file connects the button to the slider’s own autoplay: a CSS animation of the theme, Slick, Swiper or Flickity. For visitors whose device asks for reduced motion, the slideshow starts paused. A slider that a plugin or an inline script drives is left to a person.

<blink> and <marquee> elements in the theme’s templates, and in PHP strings that print them, 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. The marquee’s scrolling settings are removed, so no text moves on its own. An element that the code opens and closes in different places is left to a person.

A video in the theme’s templates that plays on its own gets muted and playsinline, so it keeps playing silently and plays inside the page on iPhones instead of in full screen; where the video has controls, visitors can still turn the sound on. Audio that starts by itself no longer does. Media that a script starts are left to a person. In a Validiscan scan, sound that starts by itself is reported by Validiscan’s media check vs-media, which takes the place of the axe-core rule this recipe serves; vs-media is MANUAL (see the list further down), so on WooCommerce such a finding comes with guidance rather than with this change.

A form field whose label text is already in the template, but not connected to the field, gets connected: the <label> right before the field, or right after a checkbox or radio button, gets a for that points at the field, or a text element marked as a label is connected through aria-labelledby. Screen readers then read the label when the field gets focus, and clicking a connected <label> moves the focus to the field. A field that only has a placeholder is left to a person, because writing a label is a content decision.

Fields in the theme’s templates that ask for data about the customer, such as login, registration and checkout fields, get the autocomplete value for what they ask for, such as email, username, current or new password, first and last name, company, address, postal code, country or phone number. The value is worked out from the field’s type, name, id and label. A value that is missing, off or invalid is replaced; a valid one stays. WooCommerce’s own billing and shipping fields are printed by WooCommerce, not by the theme, so a filter in functions.php sets their values. It runs after the theme’s own filters for those fields, which can remove the values. Fields that ask for no personal data, such as search, coupon or quantity fields, are left as they are, and so is a field whose purpose the code does not show.

When a customer picks another size or colour, the area that shows the price and stock of the chosen variation is rewritten in place. That area becomes a live region, so screen readers announce the new price and stock without the customer having to move there. The cart link in the header is replaced as a whole when a product is added, so it cannot carry the announcement itself. Next to it the recipe adds a visually hidden status message, and a short block in the theme’s script writes “Product added to your cart.” or “Product removed from your cart.” into it when WooCommerce reports the change. Both messages are added in English. An area that already is or sits inside a live region, or that the theme’s own script replaces as a whole, is left as it is.

Buttons and links that show only an icon get a name that says what they do, where the code shows their purpose: from the icon’s own name, from the control’s class or id, or from where a link goes, such as the cart, the account page or a social network. Examples are Search, Cart, My account, Show password, Close and Menu. The name is visually hidden text inside the control, or an aria-label where the theme has no class for hidden text, and it is added in English. Social network names are brand names and stay as they are. A control whose purpose the code does not show 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, such as a logo next to the shop name, it is a small 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 announcing an unnamed graphic. 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 title in English that says what it shows. The recipe takes it from the title of an embedded file in the theme, from the provider in the frame’s address, or from words such as map or video in its class or id. A frame whose content the code does not show gets no generic title; it is left to a person.