Accessibility

Online stores should be accessible to all users, including those with temporary or permanent limitations who use assistive technologies (AT).

Hyvä Theme (v1.3.0 and later) implements accessibility (a11y) features compliant with WCAG (Web Content Accessibility Guideline) 2.1 Level AA requirements.

Supported accessibility features:

• Keyboard support
• Support for Assistive Technologies
• Colors, spacing, and fonts
• Responsiveness – the page adjusts for different devices and various screen widths
• Alternative content

Working with Accessibility in Hyvä

When customizing Hyvä, ensure you don't degrade accessibility. This applies to both installed extensions and theme-related changes.

To ensure your store remains accessible, implement and maintain a11y features within your theme customizations.

Here are some useful tips:

Use semantic HTML

Avoid using only div and span for your frontend. Instead, use semantic HTML elements like landmarks, properly ordered headings, buttons and links (rather than divs or spans with `onclick` events), lists, paragraphs, and tables. These tags inherently convey an element's role and function without additional code.

Label Buttons and Links Without Visible Text

For buttons and links with image or icon content but no visible text, provide a textual label using aria-label, aria-labelledby, or visually hidden text (via the sr-only Tailwind class). Remember to translate these labels.

Focus management

Ensure all focusable elements have a visible outline to indicate their focus state, and maintain a logical, consistent focus order. For modals, move focus inside upon opening and back to the trigger upon closing. The Hyvä modal library handles this automatically, but custom modals (e.g., sliders) require manual implementation.

Since v1.2.6, Hyvä includes the JavaScript methods hyva.trapFocus and hyva.releaseFocus for this purpose.

Aria-expanded for collapsible elements

When content in a collapsible component is displayed, use the aria-expanded attribute on the trigger element to indicate its collapsed or expanded state. For reference, see the template Magento_Customer/templates/header/customer-menu.phtml in the default theme.

Live region

When a section updates dynamically on the client side (without page reload), use the aria-live attribute on the container to announce changes to AT users. An example is the price of bundled products; refer to the template Magento_Bundle/templates/catalog/product/view/price.phtml for an example.

How to test the accessibility of your Store?

Basic Accessibility Testing During Development:

• Check your store using automatic tests in your browser with the axe devtools browser plugin.
• Shop on the site using only your keyboard – verify new or customized features work without a mouse or trackpad.
• Review your code in DevTools – check the accessibility tree and generated properties.

More advanced tests:

• Test with a screen reader – VoiceOver for Mac, NVDA for Windows, or ChromeVox as a browser plugin.
• Use ANDI Accessibility Testing tools to manually check accessibility features in your browser.

Does a Hyvä Store Fully Comply with WCAG 2.1 Level AA?

Not entirely. While Hyvä Theme provides an accessible frontend template, this is only one part of a fully accessible store. You must also ensure all content is accessible (e.g., simple language, alternative text for images, audio transcription, and video captions). Additionally, all template customizations, both design and functionality, should be tested for accessibility.