@storyblok/accessibility-checker

The @storyblok/accessibility-checker package allows content editors to run axe-core tests in Storyblok’s Visual Editor.

Once enabled, the package sends the check results to the Accessibility checker, available in the A11y tab of the Visual Editor.

Note

Part of Deque’s Axe platform, axe-core is an open source accessibility testing engine for HTML-based projects.

Requirements

• Node.js LTS
• The latest versions of Chrome, Edge, Firefox, and Safari

@storyblok/accessibility-checker works with any JavaScript-based framework.

Installation

To add the package to a project, run this command in the terminal:

npm install @storyblok/accessibility-checker

Usage

Create a checker and enable it in code that runs in the browser:

import { createAccessibilityChecker } from "@storyblok/accessibility-checker";

const accessibilityChecker = createAccessibilityChecker();
accessibilityChecker.enable();

// Later, for example when a component unmounts:
accessibilityChecker.disable();

The enable() method starts the checker only inside the Visual Editor. axe-core ships as a separate file that loads when the Visual Editor requests the first check.

Repeated calls to enable() or disable() have no effect. Calling enable() disables any other checker on the page, and disable() removes the message listener.

Options

Option	Default	Description
allowedOrigins	[]	Additional origins that can request checks, such as a development server. Use exact strings (for example, "https://localhost:3000") or regular expressions that match the whole origin.
ruleTags	wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22a, wcag22aa, best-practice	A list of axe tags that determine which rules to run, such as WCAG levels. Include at least one tag.

A rule runs if it has at least one of the listed tags, so add a tag for every level that you need. If none of the listed tags match a rule, the check fails with the error code check-failed.

Results

The result groups findings by category, and splits each category into violations, warnings (results that need a manual review), and passed.

Each finding describes one element on the page. If the element is inside a block, the finding includes the block’s blockUid and componentName. The package extracts both from the data-blok-c attribute, set by storyblokEditable().

Tip

To learn more, check the Manage the Visual Editor concept.

ruleTags lists which axe tags the check used, so the Visual Editor shows which guidelines applied.

totalChecks is the sum of violations, warnings, and passed findings. Each finding is one rule applied to one element.

The following is an example of a violations finding:

{
  "id": "violations-image-alt-0",
  "ruleId": "image-alt",
  "title": "Images must have alternative text",
  "description": "Ensure <img> elements have alternative text or a role of none or presentation",
  "helpUrl": "https://dequeuniversity.com/rules/axe/4.14/image-alt?application=axeAPI",
  "severity": "critical",
  "element": {
    "html": "<img src=\"https://a.storyblok.com/f/1/hero.jpg\">",
    "blockUid": "abc",
    "componentName": "hero"
  }
}