Add Storybook test-runner and a11y setup

Add a Playwright-based Storybook test runner (.storybook/test-runner.js) that injects axe and runs accessibility checks via axe-playwright. Disable automatic in-browser a11y scans in preview.js (use manual scanning instead) and make a small loader comment cleanup in main.js. Update package.json to include Storybook test-runner and axe-playwright (and related tooling) to support the new test runner.
ethangardner · Jun 15, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
commit df497d507ef7f4bae25bb0cee21f0f2e796cc1a1
diff --git a/.storybook/main.js b/.storybook/main.js
@@ -108,7 +108,6 @@ module.exports = {
           loader: "file-loader",
           options: {
             name: "[name].[ext]",
-            //outputPath: "../dist/img",
           },
         },
         include: path.resolve(__dirname, "../packages"),

diff --git a/.storybook/preview.js b/.storybook/preview.js
@@ -4,8 +4,9 @@ import "../packages/uswds-core/src/js/start";
 /** @type { import('@storybook/html').Preview } */
 const preview = {
   parameters: {
-    axe: {
-      timeout: 30000,
+    a11y: {
+      // Disable automatic a11y scanning in the browser — handled by test-runner instead
+      manual: true,
     },
     controls: {
       matchers: {

diff --git a/.storybook/test-runner.js b/.storybook/test-runner.js
@@ -0,0 +1,34 @@
+const { getStoryContext } = require("@storybook/test-runner");
+const { injectAxe, checkA11y } = require("axe-playwright");
+
+/**
+ * @type {import('@storybook/test-runner').TestRunnerConfig}
+ */
+module.exports = {
+  async preVisit(page) {
+    await injectAxe(page);
+  },
+  async postVisit(page, context) {
+    const storyContext = await getStoryContext(page, context);
+
+    // Skip stories that opt out of a11y testing
+    if (
+      storyContext.parameters?.a11y?.disable ||
+      storyContext.parameters?.axe?.mode === "off" ||
+      storyContext.parameters?.axe?.skip === true
+    ) {
+      return;
+    }
+
+    // Wait for any animations/transitions to settle
+    await page.waitForTimeout(200);
+
+    await checkA11y(page, "#storybook-root", {
+      detailedReport: true,
+      detailedReportOptions: {
+        html: true,
+      },
+      axeOptions: storyContext.parameters?.a11y?.options,
+    });
+  },
+};