Accessibility fixes in your Magento theme’s code

Magento sets the language of a page from the locale of its store view, for example en for the locale en_US, and prints it through its root template. Where your theme overrides that template and prints its own lang, typically the locale code en_US, which is not a valid language tag, or no lang at all, the template prints Magento’s own attributes again, so every page gets a valid lang. A lang set in layout XML in the locale form, such as de_DE, becomes de-DE. A page whose content is in another language than its store view, such as a German legal page in an English store, is left to you: serve it from a store view in that language, or mark the language in the content itself.

Magento’s Luma theme has a “Skip to Content” link at the top of each page that jumps to the start of the main content, and that content is the page’s <main> area. A theme can lose both. Where the theme removed the link in its layout XML, the recipe takes the removal out. Where the theme’s own header template never prints the link, the recipe adds it there with Luma’s classes; if the theme’s stylesheets would leave it unstyled, the recipe adds styles that keep it hidden until it receives keyboard focus. Where layout XML renders the main content as another element, such as a <div>, it becomes <main> again. Navigation areas without a name get one that says what they hold, such as Main menu, Footer links or Breadcrumbs; one whose purpose the code does not show, or that would share its name with another, is left to a person. Content outside the header, main area and footer, such as a promotion bar, is not moved: moving it is a change to your layout that your developer makes in layout XML.

Magento gives every page a title of its own, such as the name of the product or category, or “Search results for:” and the search term, with the prefix or suffix set for your store. A theme can override it with an empty <title> in layout XML, and the page then has no title. The recipe removes such empty titles, so Magento’s own title applies again. Titles with text are your wording and stay as they are. If no layout file of the theme empties the title, the recipe changes nothing: the title then comes from the page itself and from the HTML Head settings in the Magento Admin.

A heading that skips a level, such as an h4 right after an h2, moves up to the next level, and the headings that follow it in the same template at its level or deeper move up with it. Classes stay, so styles that the theme sets by class still apply; your developer checks styles that the theme sets by the heading’s tag. Where the level of the heading before it can be read neither from the scan nor from the same template, the heading is left to a person. Magento prints each page’s title as its h1. A theme that hides the title on a page with display: none removes the page’s only h1, so the recipe hides it visually instead, the way Magento’s own styles hide text, and the h1 stays in the outline that screen readers use. A title removed in layout XML is left to a person, because bringing it back would change the page’s look.

The theme’s stylesheet gets one outline for keyboard focus: 2 pixels, solid, 2 pixels away from the element, in the theme’s brand colour. The colour comes from a brand or primary colour variable, else from the primary button, else from the link colour, and is adjusted until it has a contrast of at least 3:1 against the page background. Areas with a background of their own, such as a dark top bar, get an outline colour that has that contrast there. Theme rules that remove the outline from links, buttons and other controls on focus are taken out, unless they show focus in another way, such as a border or a shadow.

A tabindex above 0 pulls an element to the front of the keyboard order. Such values only work relative to each other across the whole page, so once a reported element is shown to carry one in the theme’s templates, the recipe removes every fixed positive tabindex in the theme’s templates, also on elements the finding did not list. Links, buttons and form fields lose the attribute; other elements get tabindex="0", so they stay reachable while the Tab key follows the order of the page. A tabindex that PHP code computes is left to a person. Validiscan’s check vs-focus-order also reports focus that jumps around the page for other reasons, such as content placed elsewhere by its styles; it is MANUAL, so its findings come with guidance, not with this change.

The recipe removes user-scalable=no and any maximum-scale below 2 from the viewport tag in the theme’s layout XML, such as default_head_blocks.xml, where Luma declares it, or in its templates, so visitors can zoom the page on a phone. For the best-practice rule meta-viewport-large the limit is 5. The other viewport settings stay as they were. A viewport value that PHP code computes is listed for your developer to check. If the tag that blocks zoom does not come from the theme, for example from the HTML Head settings in the Magento Admin or from a module, the recipe changes nothing.

Buttons and links that the scan found too small, such as social media icons or quantity buttons, get a minimum size of 24 by 24 pixels in a block at the end of the theme’s stylesheet. The block reuses the selectors with which the theme made them small, or their own classes, and sets a minimum width and height, which wins over a smaller width or height. The icons inside and the layout around them stay as they are. A link or other inline element without a display rule becomes inline-flex, because inline elements ignore a minimum size. A control without a class the stylesheet can address is left to a person.

When a visitor’s device is set to reduce motion, a block at the end of each theme stylesheet switches off the animations, the transitions of 5 seconds or more and the smooth scrolling that this stylesheet starts, selector by selector. Where the theme’s own scripts in web/js start a slider with autoplay switched on, the slider starts without autoplay for those visitors. A rule nested inside another LESS rule is listed for your developer. Animations from Magento’s own code or from extensions are not in the theme’s files and need their own guard.

On Magento this recipe adds no pause button. The Page Builder slider runs on Magento’s own scripts, and a theme cannot give it a pause button without overriding Magento’s code. The recipe uses the slider’s own setting instead: on every autoplaying Page Builder slider in the theme’s files, autoplay is switched off, as the Autoplay switch in Page Builder does, and arrows are switched on where the slider would otherwise have no way to move between slides. Endless CSS animations that move a slider by themselves are removed. The slides then change only when the visitor uses the dots or arrows: nothing moves on its own, so there is nothing to pause. A slider stored in the Magento database is not a file of the theme: you switch off its autoplay with the Autoplay setting in Page Builder. A slider that the theme’s own scripts start with autoplay, such as a Slick or Swiper slider, needs a pause button wired into that script, which is left to a person.

<blink> and <marquee> elements in the theme’s templates become static elements with the same content, classes and ids: a <span> for blink, a <div> for marquee. The marquee’s own attributes, such as its scrolling speed and direction, are removed, and so is the style text-decoration: blink in the theme’s stylesheets, so no text moves or blinks on its own.

A video in the theme’s templates that plays on its own gets muted and playsinline, so it keeps playing silently and inside the page on phones. Audio no longer starts by itself. Embedded YouTube and Vimeo players that start on their own are set to start muted. Autoplay that PHP code switches on is 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, which also covers captions and transcripts, is MANUAL, so on Magento such a finding comes with guidance rather than with this change.

A form field whose label text is already on the page, before the field, gets connected to that text. A <label> without a for gets one that points at the field. A label text in a <span> or <strong>, such as a “Sort By” text with Luma’s sorter-label class next to the sort menu of a category page, becomes a <label> with the same classes. A label text in a block element, such as <div class="label">, keeps its tag and is connected through aria-labelledby. The text must sit in a container with no other field, so it cannot belong to another one. 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 in the theme’s templates that ask for the customer’s own data, in address, account, login, contact and newsletter forms, get the autocomplete value for what they ask for, such as email, name, phone number, street address, postal code or password. The value is worked out from the field’s type, name, id, label, placeholder and title, by the same rules as Validiscan’s form check, and billing and shipping fields get their section, as in shipping given-name. Once one field of a form is reported, every field of that form is handled. Passwords get new-password in registration and reset forms and in forms with more than one password field, and current-password elsewhere. Coupon, search, gift recipient, comment, quantity and CAPTCHA fields never get a value. A value that template code writes, or a valid value that looks wrong for the field, is left to a person.

Magento’s own scripts rewrite the text inside fixed containers when a customer picks a size or colour or adds a product to the cart. The recipe turns those containers in the theme’s templates into live regions, so screen readers read the new value without the customer having to move there. The price box and the mini cart counter are read in full when they change; the stock message and the page messages, such as the note that a product was added to the cart, get role="status". The scripts themselves are not changed. Where the theme marks the whole page as a live region, which makes screen readers read out every change, that is removed. Where an extension’s script adds it while the page runs, it is left to a person.

An embedded frame without a title, such as a map, a YouTube or Vimeo video, a calendar, a form or a reviews widget, gets a translatable title that says what it shows. The recipe reads what the frame shows from its address, including the fixed parts of an address that PHP code builds, and from its classes, id and name. A frame whose content the code does not reveal gets no title from the recipe and is left to a person.

When text fails the contrast check and its colour is defined in exactly one place in the theme, that place changes to the nearest colour of the same hue that reaches the required contrast against every background the scan measured for it. One place can be a LESS variable or CSS custom property used only for text colour, or a single color rule. Where the theme ships a compiled styles-m.css, it gets the same change. A colour that is used in several places, also as a background or border, or in rules whose background the scan did not measure, is left to a person.

An image is marked as decorative only when the template proves it adds nothing: it sits in a link or button that already has text or a name, such as a promotion tile with its own heading; it is an icon, at most 48 pixels in size or with an icon class or file name, 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. Every other image is treated as content, and its text alternative needs words a person chooses.

Clickable <div> and <span> elements in sliders and cookie banners become real buttons. The recipe counts an element as a control only when the code says so: it has role="button", a click handler or a Knockout click binding, or a class or data attribute that the theme’s script selects to handle clicks. Classes, data attributes and ARIA attributes stay, so the theme’s styles and scripts find the control as before, and Enter and Space now do what a click does. A small style reset at the end of the theme’s stylesheet keeps its look, also on hover and focus, and focus outlines are not touched. A control that holds blocks, links or fields, or that has no class, is left to a person.

Buttons and links that show only an icon, such as search, mini cart, account, wish list, compare, menu, close, previous and next, and the choices of a cookie banner, get an aria-label that says what they do, in the wording of Magento’s Luma theme where Luma has one, such as “Search”, “My Cart” or “Allow Cookies”. The purpose is read from the control’s classes, id, data attributes and link target, from its icon and from the form or cookie banner around it. A control whose purpose the code does not reveal, such as a social media link built in a loop from an address stored as data, or a link whose only content is a product photo, is left to a person, because its name depends on your content.