Integrating axe-core Into the Developer Workflow

1. axe-core as a library: the engine behind many testing tools

At its core, axe-core is a JavaScript library that checks a rendered page against a fixed set of rules and returns a structured result for every match, including the affected element, the rule that was violated and the related WCAG success criterion. This engine is not reinvented every time a new tool appears. It is maintained centrally by Deque Systems and pulled in as a dependency by third-party tools, which is why axe DevTools in the browser, Lighthouse in Chrome and jest-axe in a unit test suite generally report the same underlying findings.

For a development team this matters because understanding how axe-core works as a library means understanding a large part of automated accessibility testing across the whole ecosystem, regardless of whether the specific surface is a browser extension, a command line runner or a Storybook addon. That makes it far easier to build one shared understanding of the rules across the team instead of maintaining a separate interpretation for every tool.

2. The limits of automated detection: only 30 to 40 percent of WCAG criteria

Deque itself states that axe-core can reliably automate checks for roughly 30 to 40 percent of WCAG success criteria, because many criteria require contextual or content judgment that a machine simply cannot make. Whether alt text meaningfully describes an image, whether an error message is actually understandable, or whether the tab order of a complex form page makes logical sense: axe-core cannot evaluate any of that. It can only detect whether an alt attribute exists, not whether its content is any good.

Knowing this boundary matters, because it stops a team from mistaking a clean axe-core run for full accessibility. A page with zero axe-core violations can still be unusable for screen reader users, for example because a live region is missing, focus order jumps in an illogical way, or an interaction behaves correctly only visually but not semantically. Automated tools like axe-core are a safety net against obvious technical mistakes, not a substitute for manual review and real user testing.

3. The axe DevTools browser extension in daily use

The axe DevTools extension for Chrome and Firefox wires axe-core straight into the browser's developer tools and lets a developer run a full page scan with a single click, without writing a line of code or triggering a build step. For someone working on a product detail page or a form in the Hyvä theme, this scan is the fastest way to check right after a change whether new violations around contrast, missing labels or invalid ARIA attributes have crept in.

Beyond the plain automated scan, the extension also offers Intelligent Guided Tests, which turn criteria axe-core cannot check automatically into a structured checklist with concrete questions, for example whether an image description actually matches the image. These guided tests close part of the gap between the 30 to 40 percent of automated coverage and a genuinely complete manual review, without needing a separate tool for it.

4. Integrating axe-core into Storybook: checking components in isolation

Storybook is a particularly good fit for axe-core because every component renders there in an isolated, controlled state, independent of page context or the loading state of a real Magento page. The official @storybook/addon-a11y addon wires axe-core directly into every story and shows violations in a dedicated panel next to the component, so a new button or form field design can be checked long before it is ever wired into a real page.

The key difference from a CI pipeline is timing. A CI check only kicks in on push or merge request, while the Storybook addon reports violations while the component itself is being built, in real time, as the story sits open in the browser. That shortens the feedback loop from minutes or hours down to seconds and turns accessibility into part of component design instead of an afterthought correction step.

// .storybook/main.js
export default {
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y', // renders axe-core results in the Accessibility panel
  ],
};

// .storybook/preview.js
export const parameters = {
  a11y: {
    // limit the ruleset to WCAG 2.1 AA, matching the shop-wide standard
    config: {
      runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21aa'] },
    },
  },
};

5. Using axe-core directly in local development

Beyond Storybook, axe-core can also be run without any extra tooling at all, straight from the browser console against a locally running Magento or Hyvä page, by loading the script once and calling axe.run(). This route works well for a fast ad hoc check while working on a single page, for example right after saving a .phtml file and reloading the page in the browser.

For a slightly more permanent local setup, a small bookmarklet or an npm script that runs axe-core against a running development instance and prints the result straight to the terminal is worth setting up, without ever needing to open the browser extension. That keeps the check as close as possible to the actual development flow and avoids adding friction that would tempt a developer into simply skipping the step.

6. Distinction from the CI pipeline: developer feedback, not a merge gate

An automated axe-core check in the CI pipeline, covered in a separate article in this series, serves a fundamentally different purpose than using axe-core in the developer workflow. It is a gate that blocks a merge request on known, clearly defined regressions, and it runs after the actual development work, often minutes or hours after the last code change. The developer workflow with Storybook, the browser extension and local checks instead delivers feedback at the moment a component is being built, and stops a bug from ever reaching a commit in the first place.

Both layers complement each other rather than replacing one another. The CI pipeline is the safety net for cases where a bug slips through despite local checks, or a developer skipped the local check under time pressure, while the local workflow reduces how many issues ever reach the CI stage in the first place. A team relying solely on the CI pipeline pushes accessibility to the end of the process, where a fix is more expensive than it would have been at the start.

7. Configuring the ruleset and tags deliberately

axe-core organizes its rules through tags such as wcag2a, wcag2aa, wcag21aa or best-practice, which lets a check be scoped precisely to the conformance level actually targeted, instead of running every available rule against every component regardless of relevance. A store that has defined WCAG 2.1 AA as its target should set this tag filter consistently across Storybook, the browser extension configuration and the CI pipeline, so all three layers check against the same baseline and never produce contradictory results.

For individual, deliberately accepted exceptions, such as a third-party widget whose markup cannot be changed, axe-core supports targeted exclusions by selector or rule ID, so a known, unfixable issue does not show up as noise on every single run. Such exclusions need to be documented and reviewed regularly, so they never quietly turn into a permanent excuse to ignore real bugs.

8. From finding to fix: establishing a team workflow

An axe-core finding that surfaces locally during development should get fixed in the same session the component is being built, because the context is still fully present and the fix usually takes just a few minutes. If the finding gets ignored and only picked back up later, for instance during a separate accessibility audit, a different person often has to get back up to speed on the code, which noticeably slows the whole process down.

For that immediate-fix reflex to actually take hold across a team, a clear, shared rule helps: every new component runs through at least one Storybook scan or extension check before the first commit, and a deliberately accepted, unfixed finding is never quietly waved through but explicitly logged as a ticket with a reason. That keeps the decision traceable instead of leaving it stuck in one person's head.

9. Practical example: checking a Hyvä component with axe-core

Take a mini cart dropdown in the Hyvä theme as a concrete example of how all three layers work together. While the component is being built, the axe DevTools extension immediately flags that the open button has no accessible label, because it only contains an SVG icon with no text. Fixing this with an aria-label directly in the Alpine.js template takes less than a minute and gets re-checked right away in the browser, instead of only surfacing hours later in a CI report.

The same check can then be baked into a Storybook story for the component as an automated regression guard, so every future change to the mini cart gets checked against the same rule automatically, without any manual step required.

<!-- before the fix: button without an accessible label -->
<button @click="miniCartOpen = true" class="relative">
  <svg class="w-6 h-6" aria-hidden="true"><!-- cart icon --></svg>
</button>

<!-- after the fix: axe-core no longer reports a violation -->
<button
  @click="miniCartOpen = true"
  class="relative"
  :aria-label="`Cart, ${cartCount} items`"
>
  <svg class="w-6 h-6" aria-hidden="true"><!-- cart icon --></svg>
</button>

10. Summary

11. FAQ: axe-core in the Developer Workflow: Key Takeaways