Accessibility fixes in your Shopware theme’s code

The <html> element of the storefront’s base layout gets a valid lang attribute, so screen readers pronounce the page in the right language. Where the attribute is missing, the recipe adds the code of the shop’s active language, for example de-DE, the value Shopware’s own base template prints. Where the theme prints a locale code such as en_GB, which is not a valid language tag, the template now turns it into en-GB. A page whose content is written in another language than the shop’s, such as a German legal text in an English shop, is left to you: the language of that content is set in the Administration or marked in the text itself.

Depending on what the scan found, the recipe adds a skip link, marks the main content or names the navigation areas. The skip link becomes the first element a keyboard user reaches on each page. It stays hidden until it receives focus and jumps to the main content. Where no template marks the main content as <main>, the content area of the base layout becomes the page’s <main> area. The link’s text is the snippet general.skipToContent, in English “Skip to main content”. An existing skip link is pointed at the main content. Navigation areas without a name get one, taken from their heading or from their purpose, such as Main navigation, Service navigation or Breadcrumb. A navigation area whose purpose is unclear, or that would share its name with another one, is left to a person.

Where the theme’s layout writes only the page’s meta title into the <title>, categories and CMS pages without a meta title get an empty title. The recipe keeps the theme’s own title and gives it a fallback: the shop name, taken from where the theme already prints it or, if it does not, from the shop name in Shopware’s basic settings. No page then has an empty title. A title that is only the shop name still does not say what the page is, so those pages need a meta title in the Administration. Titles that already have a fallback or fixed text are left alone.

A heading that skips a level, such as an h3 right after an h1, moves up to the next level, and the other headings of the same template at that level or a deeper one move with it, so the template’s own outline stays intact. Where the template sets the heading’s tag in a variable, the variable is changed. Classes stay, and where no class sets the size, a Bootstrap heading class keeps the old look. A page without a main heading gets the element that already titles it in its own template turned into the h1, with its look kept. If a page has no such element, the recipe adds no heading, because a new heading needs wording.

The main stylesheet gets one outline for keyboard focus: 2 pixels, solid, 2 pixels away from the element, in the theme’s brand colour. Where that colour is too light, the nearest shade of the same hue that has a contrast of at least 3:1 against the page background is used. Theme rules that remove the outline on focus now apply only to focus by mouse: a click keeps the theme’s look, and keyboard focus shows the outline. Rules that show focus in another way are kept. On dark areas, such as a top bar, the outline 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 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 template’s code writes is left to a person. A scan reports such a forced order twice: through the axe-core rule tabindex, whose findings get this change, and through Validiscan’s check vs-focus-order, whose tier is MANUAL, so its findings come with guidance.

The recipe removes user-scalable=no and any maximum-scale below 2 from the viewport tag of the storefront templates, usually in layout/meta.html.twig, so visitors can enlarge text to at least 200 % on a phone. For the best-practice rule meta-viewport-large the limit is 5. The other viewport settings stay as they were. If the lock was there to stop iOS from zooming into form fields, a font size of at least 16 pixels for the fields does that without blocking zoom.

Buttons and links that the scan found smaller than 24 by 24 pixels, such as header icons, quantity buttons or swatches, get a minimum size of 24 by 24 pixels. The minimum is added to the theme’s own style rule that made the control small, next to the declaration that shrank it, so the order of the theme’s styles stays the same and the icons inside keep their size. A control that is small without such a rule gets a minimum size for its class in the main stylesheet. A control the recipe cannot identify by its class is left to a person.

When a visitor’s device is set to reduce motion, a block in the main stylesheet makes animations and transitions end at once and turns smooth scrolling off. The block applies to every element of the page, so it also covers animations that other stylesheets define, including those of plugins. Where the theme’s storefront script starts a timer, such as a slideshow’s autoplay, only when an autoplay option is set, that condition now also checks the visitor’s setting. Other motion that a script starts is listed for the reviewer, not guessed at.

Shopware’s base slider, the slider behind the image slider of the CMS, gets a visible, translated button to pause and play it, next to its previous and next arrows. A block of code in the theme’s storefront script connects the button to the slider’s autoplay through Shopware’s own slider plugin. Where the theme runs the autoplay with its own timer, that timer gets one line that skips a step while the slider is paused. The button stays hidden until the script has connected it, so it never appears without an autoplay to pause. For visitors whose device asks for reduced motion, the slider starts paused. Sliders built with other libraries are left to a person.

<blink> and <marquee> elements in the Twig templates 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 similar text element. 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 plays inside the page in Safari on phones instead of opening the full-screen player. Audio that starts by itself no longer does; visitors start it themselves. Autoplay that template code or a script sets, and players embedded in frames, 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 no-autoplay-audio. vs-media, which also covers captions and transcripts, is MANUAL, so on Shopware such a finding comes with guidance rather than with this change.

A form field whose label text is already on the page, right before the field, gets connected to that text. A <label> without a for gets one that points at the field. A text element that the theme marks as a title or label by its class, such as the name of a variant group on a product page, becomes the field’s <label>, keeping its classes and its own line. 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.

Fields that ask for the customer’s own data, such as those of the registration, address, login, contact and newsletter forms, get the autocomplete value for what they ask for, such as email, first and last name, postal code, phone number or password. The value is worked out from the field’s type, name, id, label and placeholder. Passwords get new-password in registration forms and current-password elsewhere. Search, voucher, quantity, captcha and message fields are left as they are, and a value that template code writes is left to a person. Browsers can then fill the fields in, and assistive technology can tell what each one is for.

The parts of a page that the storefront script updates in place, such as the price after a customer picks a variant, the availability or the cart totals, become polite live regions. Screen readers then read the new value once, in full, without interrupting. Where a script replaces the element itself instead of its content, a live region would not work, so the recipe leaves that element to a person.

An embedded frame without a title, such as a map or a YouTube or Vimeo video, gets a translated title from the theme’s snippet files that says what it shows. The recipe reads what the frame shows from its address, its class and name, or the template around it. A frame whose content the code does not reveal gets no title from the recipe, because an invented title is worse than none.

When text fails the contrast check and its colour is defined in exactly one place in the theme, that place changes to the nearest shade of the same hue that reaches the required contrast, so the design stays recognisable. One place can be a colour field in theme.json together with the SCSS variable that repeats it, an SCSS variable or custom property used only for text, or a single color declaration. A colour that is used in several places or also as a background or border, and Shopware’s core colour fields for the brand, borders, backgrounds, status messages and the buy button, are left to a person. A colour saved in the Administration’s theme settings overrides theme.json: if it was changed there, it has to be changed there too. The rule color-contrast has the tier ASSISTED, so in a project a contrast finding takes the ASSISTED way and this recipe is not applied to it.

An image is marked as decorative only when the template proves it adds nothing: it sits in a link or button that is named another way, it is an icon next to its own text label, or it is a spacer or divider. An <img> gets an empty alt, an image printed with Shopware’s sw_thumbnails tag gets an empty alt in its attributes, and SVG icons get aria-hidden="true", so screen readers skip them instead of reading out a file name. Every other image is content, such as the payment logos in a footer, and its text alternative needs words a person chooses. The rules this recipe serves have the tier ASSISTED, so in a project their findings take the ASSISTED way and this recipe is not applied to them.

Clickable <div>, <span>, <i> and <li> elements in sliders and cookie banners, and links without an address, that only react to a mouse become real buttons. Classes, data attributes and ids stay, so the theme’s script finds them as before, and Enter and Space now do what a click does. A list item keeps its place in the list and gets the button inside it. A control without text gets a translated name from its purpose, such as “Show slide 2”, and a small style reset keeps its look. A control without text whose purpose is unclear, or whose styling depends on its tag or its position, is left to a person. In a project this recipe is tried on slideshow findings of vs-carousel; findings of the cookie banner check vs-cookie-banner have the tier ASSISTED and take the ASSISTED way.

Buttons and links that show only an icon, such as search, cart, account, the logo link, slider arrows, quantity buttons and cookie choices, get a translated aria-label that says what they do. The purpose is read from the control’s classes, its link target, the icon inside it and the component around it. A control whose purpose the code does not reveal, such as a social link whose network is stored as data, is left to a person, because an invented name is worse than none. In a project this recipe is tried on the slideshow controls that vs-carousel reports; other icon-only controls are reported by rules of tier ASSISTED and take the ASSISTED way.