docs: upgrade to Storybook 10 & add accessibility testing by sh0ji · Pull Request #3295 · Codecademy/gamut

sh0ji · 2026-03-19T20:57:34Z

While reviewing Datepicker for accessibility issues, I was wishing we had some basic accessibility tests, so I worked with Cursor to upgrade to Storybook 10 and add their built-in accessibility testing, which runs off Playwright. While working on this, I also upgraded husky & lint-staged because my IDE wasn't using them to lint/format files.

The overall diff is pretty big because it includes a bunch of little changes to stories like changing the import names of the new packages, but individual commit diffs should be pretty legible if you want a more chunked view of the changes.

Changelog description

Upgrades the Styleguide to Storybook 10 (preview, addon-docs, and MDX).
Adds Storybook’s built-in accessibility testing, with a dedicated CI job and Nx target so a11y checks run in the pipeline.

PR Checklist

Related to JIRA ticket: GMT-1465 GMT-153
I have run this code to verify it works
This PR includes testing instructions tests for the code change

Testing Instructions

update deps and build storybook: yarn && yarn build && yarn build-storybook
run the new tests: yarn playwright install chromium then yarn test:storybook
run storybook in dev mode (yarn start:storybook) and then spot-check docs, toolbars, and the new a11y panel

…dule paths

skip-automated-commits either explicitly exits with 0 or exits without any code, which is a 0 exit, so it never actually skips anything

nx-cloud · 2026-03-19T20:59:19Z

View your CI Pipeline Execution ↗ for commit 6e746e7

☁️ Nx Cloud last updated this comment at 2026-03-20 21:45:08 UTC

codecov · 2026-03-19T21:08:02Z

⚠️ JUnit XML file not found

The CLI was unable to find any JUnit XML files to upload.
For more help, visit our troubleshooting guide.

in storybook 10, the default undefined option is responsive so we don't need this

these were added during this branch's explorations and I'm just now removing them

codecademydev · 2026-03-20T21:45:35Z

📬 Published Alpha Packages:

@codecademy/styleguide@79.2.4-alpha.ee1acd.0

sh0ji · 2026-03-20T21:46:52Z

.github/workflows/test.yml

-      - name: Skip build from automated commit
-        uses: ./.github/actions/skip-automated-commits
-        if: github.event_name == 'pull_request'
-        with:
-          ignore-commit-message: ${{ env.IGNORE_COMMIT_MESSAGE }}


dc8dadd describes my rationale for removing this:

skip-automated-commits either explicitly exits with 0 or exits without any code, which is a 0 exit, so it never actually skips anything

github-actions · 2026-03-20T21:48:20Z

🚀 Styleguide deploy preview ready!

Preview URL: https://69bdc09e28081ed92ba4ddf1--gamut-preview.netlify.app
Deploy Logs: https://app.netlify.com/projects/gamut-preview/deploys/69bdc09e28081ed92ba4ddf1

sh0ji · 2026-03-20T21:48:31Z

.husky/pre-commit

-. "$(dirname -- "$0")/_/husky.sh"
-
-npx lint-staged --relative
+npx lint-staged


Lint-staged wasn't running on pre-commit for me, so I updated the tooling and I verified that it's working for my environment now. The latest Husky simplified this a bit.

sh0ji · 2026-03-20T21:50:38Z

packages/styleguide/.storybook/preview.ts

 const preview: Preview = {
  parameters: {
+    a11y: {
+      test: 'todo',


There are quite a few a11y errors in our stories, but it was outside of the scope of this PR to fix them so I'm leaving this as todo for now. I'm going to open a separate ticket to fix them, after which we should switch this to error so that CI fails if we have a11y issues in a story.

sh0ji · 2026-03-20T21:53:49Z

package.json

-    "eslint-plugin-gamut": "^2.0.0",
+    "eslint-plugin-gamut": "workspace:*",


Small tweak because my eslint wasn't recognizing this package. This tells yarn to resolve it to the latest workspace directory, which I think is a better approach for local dependencies.

sh0ji · 2026-03-20T22:00:13Z

packages/styleguide/project.json

+      "options": {
+        "cwd": "{workspaceRoot}",
+        "forwardAllArgs": false,
+        "command": "start-server-and-test \"http-server dist/storybook/styleguide -p 6007 --silent\" http://127.0.0.1:6007 \"test-storybook --url http://127.0.0.1:6007 --config-dir packages/styleguide/.storybook\""


This was one of the things I spent the most time on because it's such an annoyingly complex command: it serves the Storybook build and runs the Storybook test runner against it, and the start-server-and-test wrapper ensures that the server closes when tests are complete.

Storybook's recommended way to handle this is with Vitest, which would use the waaay simpler

vitest --project=styleguide

I looked into what that would take a bit and concluded it should be a follow-up, not part of this PR, so consider this gnarly command to be a stop-gap. That follow-up will require us to switch to the Vite React builder (from our current webpack5 one), which feels worthwhile for other reasons and we may want to just switch the entire Gamut build process to Vite at the same time.

sh0ji · 2026-03-20T22:02:15Z

package.json

    "format:verify": "yarn prettier --check",
    "lint": "eslint --ignore-path .eslintignore \"./**/*.{mdx,js,ts,tsx,json}\" --max-warnings 0",
    "lint:fix": "yarn lint --fix",
+    "prepare": "husky",


Added automatically by husky init.

sh0ji · 2026-03-20T22:03:50Z

babel.config.js

+  presets: [
+    [require.resolve('@babel/preset-typescript'), { allowDeclareFields: true }],
+    [require.resolve('@babel/preset-react'), { runtime: 'automatic' }],
+  ],


This was done by Storybook's automatic migration process. I'm realizing now that I don't 100% know why...I'll look into it but maybe one of you intrepid reviewers knows?

sh0ji added 6 commits March 19, 2026 16:09

chore(styleguide): upgrade Storybook to 10.x

427352c

chore(styleguide): update Storybook preview and docs theming for SB10

a6d7c0f

chore(styleguide): update docs blocks and stories for Storybook 10 mo…

94a1f67

…dule paths

chore(styleguide): migrate MDX for Storybook 10 addon-docs

6c48124

ci: add dedicated Storybook test-runner job and nx target

773e491

chore: cleanup no-op action

dc8dadd

skip-automated-commits either explicitly exits with 0 or exits without any code, which is a 0 exit, so it never actually skips anything

chore: remove the migration summary now that it's done

635d74f

sh0ji added 11 commits March 19, 2026 17:22

chore: prettier --write

dc1ef19

chore: fix storybook test command

ae87e06

chore: update lint-staged & husky

87db0d6

chore: use the workspace eslint plugin, not semver

2a7fbc1

chore: yarn lint:fix

6de05cb

chore: yarn dedupe

2ace81a

chore: add missing start-server-and-test package

42c68e5

fix: remove responsive viewport option

27378f9

in storybook 10, the default undefined option is responsive so we don't need this

fix: consistent title casing

de25bb3

ci: don't forward jest flags to this task

3b23501

ci: don't include storybook tests in main test suite yet

1f729f9

sh0ji changed the title ~~WIP: Storybook 10 & accessibility testing~~ docs: upgrade to Storybook 10 & add accessibility testing Mar 20, 2026

sh0ji added 5 commits March 20, 2026 17:16

chore: simplify config

6e34aef

chore: use correct nx script

e3113a1

chore: storybook 10 changed this to option to "disable"

825b5da

chore: remove unused dependencies

802c98c

these were added during this branch's explorations and I'm just now removing them

Merge branch 'main' into evan-storybook-10

6e746e7

sh0ji marked this pull request as ready for review March 20, 2026 21:42

sh0ji requested a review from a team as a code owner March 20, 2026 21:42

sh0ji requested review from LinKCoding and aresnik11 March 20, 2026 21:42

sh0ji commented Mar 20, 2026

View reviewed changes

sh0ji requested a review from dreamwasp March 20, 2026 22:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: upgrade to Storybook 10 & add accessibility testing#3295

docs: upgrade to Storybook 10 & add accessibility testing#3295
sh0ji wants to merge 23 commits intomainfrom
evan-storybook-10

sh0ji commented Mar 19, 2026 •

edited

Loading

Uh oh!

nx-cloud bot commented Mar 19, 2026 •

edited

Loading

Uh oh!

codecov bot commented Mar 19, 2026 •

edited

Loading

Uh oh!

codecademydev commented Mar 20, 2026

Uh oh!

sh0ji Mar 20, 2026

Uh oh!

github-actions bot commented Mar 20, 2026

Uh oh!

sh0ji Mar 20, 2026

Uh oh!

sh0ji Mar 20, 2026

Uh oh!

sh0ji Mar 20, 2026

Uh oh!

sh0ji Mar 20, 2026 •

edited

Loading

Uh oh!

sh0ji Mar 20, 2026

Uh oh!

sh0ji Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		"eslint-plugin-gamut": "^2.0.0",
		"eslint-plugin-gamut": "workspace:*",

Conversation

sh0ji commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog description

PR Checklist

Testing Instructions

Uh oh!

nx-cloud bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ JUnit XML file not found

Uh oh!

codecademydev commented Mar 20, 2026

Uh oh!

sh0ji Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 20, 2026

Uh oh!

sh0ji Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

sh0ji Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

sh0ji Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

sh0ji Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sh0ji Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

sh0ji Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sh0ji commented Mar 19, 2026 •

edited

Loading

nx-cloud bot commented Mar 19, 2026 •

edited

Loading

codecov bot commented Mar 19, 2026 •

edited

Loading

sh0ji Mar 20, 2026 •

edited

Loading