ethangardner · Jun 15, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -6,7 +6,7 @@ orbs:
 references:
   container: &container
     docker:
-      - image: cimg/node:20.19.0-browsers
+      - image: cimg/node:24.16.0-browsers
         environment:
           CHROME_PATH: $(which google-chrome-stable)
 

diff --git a/.storybook/main.js b/.storybook/main.js
@@ -32,19 +32,9 @@ module.exports = {
     name: "@storybook/html-webpack5",
     options: {},
   },
-  stories: [
-    "../packages/**/*.stories.mdx",
-    "../packages/**/**/*.stories.@(js|jsx|ts|tsx)",
-  ],
-  addons: [
-    "@storybook/addon-links",
-    "@storybook/addon-essentials",
-    "@storybook/addon-a11y",
-  ],
+  stories: ["../packages/**/**/*.stories.@(js|jsx|ts|tsx)"],
+  addons: ["@storybook/addon-essentials", "@storybook/addon-a11y"],
   staticDirs: ["../dist"],
-  docs: {
-    autodocs: "tag",
-  },
   webpackFinal: async (config, { configType }) => {
     // `configType` has a value of 'DEVELOPMENT' or 'PRODUCTION'
     // You can change the configuration based on that.
@@ -118,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-head.html b/.storybook/preview-head.html
@@ -3,23 +3,12 @@
 
 <!-- Global styles -->
 <style>
-  #root {
-    box-sizing: border-box;
-  }
-
-  #root * {
+  *,
+  *:before,
+  *:after {
     box-sizing: border-box !important;
   }
 
-  * {
-    box-sizing: border-box !important;
-  }
-
-  #root *:before,
-  #root *:after {
-    box-sizing: inherit;
-  }
-
   html,
   body {
     font-size: 16px;

diff --git a/.storybook/preview.js b/.storybook/preview.js
@@ -4,7 +4,10 @@ import "../packages/uswds-core/src/js/start";
 /** @type { import('@storybook/html').Preview } */
 const preview = {
   parameters: {
-    actions: { argTypesRegex: "^on[A-Z].*" },
+    a11y: {
+      // Disable automatic a11y scanning in the browser — handled by test-runner instead
+      manual: true,
+    },
     controls: {
       matchers: {
         color: /(background|color)$/i,

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,
+    });
+  },
+};
diff --git a/.tool-versions b/.tool-versions
@@ -1 +1 @@
-nodejs 20.19.0
+nodejs 24.16.0