Custom Shopware themes: keep accessibility intact

Since Shopware 6.7, the accessibility improvements in the standard storefront are no longer a switch but the baseline: with the major version 6.7.0, all of these changes became the default (Shopware). A custom Shopware theme or a plugin that overrides Twig blocks can, however, quietly roll this work back. Anyone who replaces a block instead of extending it ships the markup that was in the core at the time of copying. This post shows where Shopware rebuilt the storefront markup for accessibility, how theme and plugin overrides sit on top of these changes and how an override audit with three checkpoints per layer – focus, list markup, keyboard – finds the gaps. We handle the audit and the implementation as part of our accessibility optimization for shops.

What Shopware 6.7 rebuilt in the storefront

According to Shopware, the company is committed to fulfilling the WCAG 2.1 guidelines at level AA and the German Barrier-Free Information Technology Regulation (BITV 2.0) in the storefront (Shopware). The first improvements arrived with the 6.6 series, and 6.7 added further enhancements (Shopware). They are shipped continuously in regular minor versions, like other improvements (Shopware).

What matters for custom themes: accessibility can require changes to the HTML and Twig structure or the CSS, and according to Shopware this can cause unintended behavior in an extension that modifies the affected area (Shopware). That is why such changes in the 6.6 series sat behind the feature flag ACCESSIBILITY_TWEAKS and were switched off by default. With the major version 6.7.0 they became the default (Shopware).

With the major version v6.7.0, all accessibility improvements will become the default.

Shopware Developer Documentation, Accessibility in the Storefront

The release notes for 6.7.0.0 list the concrete changes and link them to the European Accessibility Act (Shopware). For themes these points matter most because they affect frequently overridden templates:

The base font size of the storefront was raised to the browser standard of 1rem, i.e. 16 px (Shopware). The upgrade notes state that $font-size-base changed from 0.875rem to 1rem (Shopware). A theme that pins the old size as a variable takes this improvement back. Unlike the technical breaks when migrating Shopware plugins to 6.7, this difference causes no build error and stays silent in the HTML.

How theme and plugins sit on top of the core markup

A Shopware theme defines in its theme.json file the order in which templates are assembled. The views section typically lists @Storefront, @Plugins and the theme itself. When a view is rendered, the storefront template is used as the basis (Shopware). The extensions of the installed plugins are applied to it (Shopware), followed by the changes of the themes in the given order.

Every storefront page is therefore built from three layers. The bottom one comes from Shopware itself. The middle one comes from plugins, for example for payment methods or reviews, the top one is the theme. Each layer can extend or replace a Twig block. If it replaces it, everything below is without effect for that block – including every improvement Shopware ships in the core later on.

Technically, this happens through sw_extends and block overrides. The developer documentation shows the principle with the logo: a custom template extends the original file, takes over the block with the same name and replaces its content (Shopware). Anyone who only wants to append something instead of replacing it calls parent() inside the block. This difference decides whether a theme grows with the core; in our Shopware development it is the first question for every override. An example of the risky variant:

{% sw_extends '@Storefront/storefront/component/product/card/box-standard.html.twig' %}

{# Replaces the whole block. Shopware 6.7 removed the link around the
   product image, this copy from an older theme brings it back. #}
{% block component_product_box_image %}
    <div class="product-image-wrapper">
        <a href="{{ seoUrl('frontend.detail.page', { productId: id }) }}"
           class="product-image-link">
            {% sw_thumbnails 'product-image-thumbnails' with { media: cover } %}
        </a>
    </div>
{% endblock %}

In Shopware 6.7, the product name in the card carries the class stretched-link and makes the whole card clickable; the separate link around the image was removed (Shopware). A theme that copies the image block from an older template brings the second link back. Visually nothing changes, but keyboard users get two tab stops per product with the same target. The extending variant avoids this:

{% sw_extends '@Storefront/storefront/component/product/card/box-standard.html.twig' %}

{# Extends the block: the core markup is kept and
   grows with every update. #}
{% block component_product_box_image %}
    {{ parent() }}
    <span class="custom-badge">New in store</span>
{% endblock %}

Six patterns through which overrides roll back accessibility

A few patterns recur in theme and plugin overrides, mostly unintentionally – a template was copied when the core still built it differently:

None of these patterns can be reliably covered afterwards with an injected script. We have described separately why overlay widgets do not solve the accessibility risk. The same applies to overrides: the fix belongs in the template or SCSS file that causes the error.

Plugins: the layer between core and theme

Theme overrides live in your own project, plugin overrides attract less attention. A plugin for a payment method, a product configurator, reviews or shipping options often extends exactly the templates that Shopware rebuilt for accessibility: cart line items, checkout, product cards, header.

Shopware explains the problem itself with an example: if a list of div elements is changed to ul and li and an extension still inserts a div with the class list-item into the block, the result is likely incorrect HTML (Shopware). The release notes for 6.7.0.0 name exactly this change for the order overview and cart line items (Shopware). A plugin that renders its own line item types in the cart therefore has to change its root element to li. Otherwise the delivered HTML contains a div inside a list.

For extensions from the Shopware Store: developers can self-certify an extension as accessible (Shopware). A review by Shopware quality assurance may be required for listing in the store (Shopware). A store listing therefore does not replace a look at how things interact in your own shop.

The checkout deserves particularly careful testing. The German ordinance under the Accessibility Act requires for e-commerce services that identification, authentication, security and payment functions, where they are provided as part of the service, are perceivable, operable, understandable and robust (BFSGV). Precisely these areas – login, address entry, payment selection – are extended by plugins in many shops.

What the German Accessibility Act requires and why the theme is part of it

According to Section 1 (3), the German Accessibility Strengthening Act (BFSG) applies, among other things, to e-commerce services provided to consumers after 28 June 2025 (BFSG). Under Section 3 (1), they are accessible if people with disabilities can find, access and use them in the generally customary way, without particular difficulty and in principle without outside help (BFSG). The concrete requirements are set out in the ordinance to the act.

For the question of overrides, Section 14 (3) is the key sentence: the service provider ensures that the requirements are met on an ongoing basis whenever it offers or provides the service (BFSG). In doing so, it has to take due account of changes in the way the service is provided (BFSG). A new theme, a plugin update or a Shopware update is exactly such a change. Accessibility is therefore not a state you establish once but one that has to survive every change to the shop.

If an offering complies with harmonized standards whose references have been published in the Official Journal of the European Union, Section 4 presumes that it meets the requirements of the ordinance, insofar as the standards cover them (BFSG). Independently of this, WCAG 2.1 at level AA, which Shopware also targets, is a widely used technical benchmark for testing.

• Fines: Anyone who intentionally or negligently offers or provides a service contrary to Section 14 (1) commits an administrative offense; the fine can be up to 100,000 euros (BFSG).
• Micro-enterprises: Under Section 3 (3), the requirements for services do not apply to micro-enterprises that offer or provide services (BFSG).
• Third-party content: Section 1 (4) excludes content from third parties that the provider neither finances nor develops nor controls (BFSG). A plugin that the operator selects, installs and configures is usually under the operator's control.

The legislator does not distinguish whether a barrier comes from the core, a plugin or the theme. The obligations lie with the service provider, i.e. the shop operator. They include information on accessibility; we describe separately what an accessibility statement with a feedback mechanism looks like in a shop. Our deadline calendar for online shops shows which further obligations and key dates 2027 brings for online shops.

What measurement data says about typical errors

The WebAIM Million 2026 shows how widespread the errors are that originate in templates. WebAIM automatically tested the home pages of the one million most visited websites (WebAIM); the results are from February 2026 (WebAIM). 95.9 percent of these home pages had detected WCAG 2 failures (WebAIM). On average there were 56.1 detected errors per page (WebAIM). Home pages in the shopping category averaged 71.0 errors, 26.6 percent above this mean (WebAIM).

Together, these six error types account for 96 percent of all detected errors (WebAIM). Many of them arise in markup and colors, i.e. where theme and plugins intervene. Two further findings fit the picture: home pages with ARIA attributes had 59.1 detected errors on average, pages without ARIA 42 (WebAIM). WebAIM stresses that ARIA did not necessarily cause these errors, as the pages were also more complex (WebAIM). And one in ten skip links was broken because it was hidden in an inaccessible way or its target was missing from the page (WebAIM).

Two limitations belong to these numbers. They refer to home pages, not to category, product or checkout pages, where shops carry many of their overrides. And they only capture automatically detectable errors: a page without detected errors is not yet accessible or conformant (WebAIM). We have summarized the success criteria added with WCAG 2.2 in our post on the new WCAG 2.2 criteria for online shops.

Colors and fonts: what the theme configuration affects

Not every barrier is created in Twig. Through its theme.json file and the configuration in the Administration, a theme also defines colors, for example the primary color via the field sw-color-brand-primary (Shopware). For variables from Shopware or Bootstrap, the overrides.scss file is intended, which is included before the default styles (Shopware). This avoids copies of templates but shifts the responsibility to the values entered.

According to WCAG 2.1, text needs a contrast ratio of at least 4.5:1 (W3C), large text at least 3:1 (W3C). A brand color that works well as a button background can fall clearly below that as a text color for links or prices on a light background. In the WebAIM Million, low contrast is the most common detected error type, found on 83.9 percent of home pages (WebAIM). We therefore check every color of the theme configuration in every role: as text, background, border and focus color.

Three checkpoints per layer: focus, lists, keyboard

An override audit needs a fixed benchmark. We check each layer – core, plugins, theme – and the delivered result against three checkpoints that can be traced directly to WCAG 2.1 success criteria:

Criterion 2.4.7 requires that any keyboard operable user interface has a mode of operation where the keyboard focus indicator is visible (W3C). Criterion 1.3.1 requires that information, structure and relationships conveyed through presentation can be programmatically determined or are available in text (W3C) – a list must therefore be a list in the code, not just look like one. Under criterion 2.1.1, all functionality must be operable through a keyboard interface (W3C).

As a fourth point we add name and role, because the change to sw_icon applies exactly there: under criterion 4.1.2, the name and role of all user interface components must be programmatically determinable (W3C). A button that only contains a hidden icon has no name. The graphic at the top of this post shows the principle with an example: there, the core meets all checkpoints, a plugin loses the list markup, the theme loses the focus – and the delivered HTML inherits both losses.

The override audit step by step

Our post on the accessibility audit for online shops describes the general approach to an audit under the Accessibility Act. For Shopware there is an additional step beforehand that general audits often lack: the inventory of overrides.

1. Create an inventory: record all template files under Resources/views in theme and plugins, with path, extended original and overridden blocks.
2. Separate replacing from extending: every block without parent() replaces the original completely. These blocks form the first checklist.
3. Compare with the core: for every replaced block, put the current version in the storefront next to it. In 6.6 templates, notes such as @deprecated tag:v6.7.0 mark the places Shopware rebuilt for 6.7.
4. Check the SCSS as well: go through variable overrides in overrides.scss and rules in base.scss for outline, font sizes and color values.
5. Measure in the browser: test the checkpoints on the home page, category, product, cart, checkout and customer account – with the keyboard alone, with a screen reader and additionally with automated checks.
6. Assign findings to a layer: every error gets the layer it comes from. Only then can you decide whether the theme, a plugin or an update carries the fix.

The search only returns candidates: even a block with parent() can wrap markup around the original that breaks the semantics. The measurement is therefore taken on the result in the browser. A staging environment with realistic but anonymized data is suitable for this audit; how to set one up is described in our post on Shopware staging with test data and no customer data.

Shops on 6.6: test in advance with ACCESSIBILITY_TWEAKS

If you are still on Shopware 6.6, you can test the changes in advance. The feature flag ACCESSIBILITY_TWEAKS is set in the project's .env; all available accessibility improvements are then active, and it becomes visible whether the project or extensions are affected (Shopware). After enabling it, the theme has to be recompiled so that style changes such as the adjusted font sizes take effect (Shopware). On a staging environment this looks like this:

Individual breaking changes already arrived behind this flag in the 6.6 series, for example the switch of the pagination to links in version 6.6.6.0 (Shopware). Anyone who only notices the flag when moving to 6.7 receives all changes at once – together with the other breaks of the major version. How the timeline up to the next major version fits in is described in our posts on preparing for Shopware 6.8 and on the end of security updates for Shopware 6.5.

Writing overrides that updates do not undermine

A good override is small, justified and verifiable:

• Choose the smallest block: the deeper the overridden block, the less foreign markup sits in your own file.
• Extend with parent(): if you append instead of replacing, you receive core improvements with every update.
• Configuration before copying: colors, fonts and spacing belong in the theme configuration and SCSS variables, not in copied templates.
• Style focus, do not remove it: if the default focus does not fit the design, define your own clearly visible focus style.
• Document overrides: record for each file why the block is overridden and against which Shopware version it was last compared.
• Compare with every minor update: because Shopware ships accessibility improvements continuously in minor versions (Shopware), comparing the overrides belongs in every maintenance round.

For new building blocks, Shopware has offered a component system since version 6.7.11.0 that lets you compose atomic template components in a reusable way throughout the storefront (Shopware). What this means for storefront development is covered in our post on the Vite dev server and Twig UX in Shopware 6.7.11. We take care of regularly comparing overrides as part of our Shopware maintenance, together with core and plugin updates in a staging environment.

Keeping accessibility in the theme secure for the long term

With 6.7, Shopware improved the foundation; whether it reaches customers depends on theme and plugins. We support you in three steps:

Our shop check gives a first overview and looks at accessibility alongside loading time and SEO basics. For the complete audit and implementation, our accessibility optimization is available.