Visitar URL original
USWDS - Storybook: Update Storybook to v8.6 by ericsorenson · Pull Request #6697 · uswds/uswds · GitHub
Skip to content

USWDS - Storybook: Update Storybook to v8.6 - #6697

Merged
ethangardner merged 9 commits into
uswds:developfrom
ericsorenson:upgrade-storybook-8
Jun 15, 2026
Merged

USWDS - Storybook: Update Storybook to v8.6#6697
ethangardner merged 9 commits into
uswds:developfrom
ericsorenson:upgrade-storybook-8

Conversation

@ericsorenson

@ericsorenson ericsorenson commented Jun 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

Updated Storybook from 7.6.24 to 8.6.18. Upgraded all Storybook packages to the latest stable v8 release, upgraded React to 18.x (required by Storybook 8's manager UI), migrated deprecated argTypes.defaultValue to args across 12 story files, removed unused @storybook/addon-links, and cleaned up deprecated config options.

Breaking change

This is not a breaking change.

Related issue

closes #5239

Supersedes #6447 — this PR goes further by upgrading to 8.6.18 (vs 8.6.7), migrating all deprecated argTypes.defaultValue usages, removing dead config, and fixing the options placement in Button stories.

Problem statement

Storybook 7.x is no longer receiving feature updates and has known security vulnerabilities in its dependency tree. The project needed to upgrade to stay secure and access the latest Storybook features. Additionally, 38 stories used the deprecated argTypes.defaultValue pattern which silently breaks in Storybook 8 (controls render with undefined defaults).

Solution

  • Upgraded all @storybook/* packages from 7.6.24 to 8.6.18
  • Upgraded react and react-dom to 18.x (Storybook 8 requirement for its internal UI — not used in component code)
  • Upgraded @chanzuckerberg/axe-storybook-testing from 7.2.0 to 8.2.3
  • Removed @storybook/addon-links (confirmed unused — zero imports in any story file)
  • Removed deprecated argTypesRegex from preview.js
  • Removed dead .stories.mdx glob and docs.autodocs from main.js
  • Migrated 38 argTypes.defaultValue usages to args across 12 story files
  • Fixed options placement inside control object in Button stories (deprecated in SB8)
  • Cleaned up dead #root CSS selectors in preview-head.html (Storybook uses #storybook-root since v7)
  • Bump Node.js to 24.16.0 (current LTS)

Dependency updates

Dependency Previous New
storybook 7.6.24 8.6.18
@storybook/html-webpack5 7.6.24 8.6.18
@storybook/addon-a11y 7.6.24 8.6.18
@storybook/addon-essentials 7.6.24 8.6.18
@storybook/addon-links 7.6.24 Removed
@chanzuckerberg/axe-storybook-testing 7.2.0 8.2.3
react 17.0.2 18.3.1
react-dom 17.0.2 18.3.1

How to test

  1. npm install
  2. npm run start:storybook — verify Storybook launches at localhost:6006
  3. Spot-check these components:
    • Accordion: expand/collapse panels (tests JS decorator timing)
    • Date Picker > Default Date: verify default date "03/06/1995" appears (tests args migration)
    • Button: open Controls panel, enable "Add icon", verify Icon Name dropdown shows options (tests options fix)
    • Range: verify min=0, max=100, step=10 defaults (tests args migration)
    • Modal: open/close, verify focus trap
    • Banner: renders USA banner correctly
  4. npm run build:storybook — verify production build succeeds
  5. npm run test:a11y — verify accessibility tests pass

Known technical debt (out of scope, tracked separately)

  • Storybook 9 will drop @storybook/html-webpack5 in favor of @storybook/html-vite — a separate Vite migration will be needed
  • Stories use CSF 2 (.bind({}) pattern) — still supported in SB8, no migration needed now
  • No explicit compiler addon added — SB8's built-in fallback works; add @storybook/addon-webpack5-compiler-babel before SB9

@ericsorenson
Upgrade Storybook to v8 and update configs
e49a128 
Migrate Storybook config and deps to v8: update package.json and package-lock (storybook, addons, react/react-dom and related packages), simplify .storybook/main.js (condense stories glob, remove addon-links and docs.autodocs), adjust preview.js (remove actions argTypesRegex), and change global box-sizing in preview-head.html to apply to *, *:before, *:after. Also update many individual story files to align with the new config/compatibility.
@ericsorenson
Increase Storybook axe timeout to 10s
ced3b0c 
Set axe.timeout to 10000 in .storybook/preview.js to allow longer time (10 seconds) for accessibility scans during Storybook runs. This helps prevent timeouts and false failures for slower accessibility checks.
@ericsorenson
Merge remote-tracking branch 'upstream/develop' into upgrade-storybook-8
47ea5b3
@ericsorenson
Bump Node.js to 24.16.0
6c646c9 
Update CircleCI image and local tool version to Node.js 24.16.0. Replaces cimg/node:20.19.0-browsers with cimg/node:24.16.0-browsers in .circleci/config.yml and updates .tool-versions to keep CI and developer environments in sync.
@ericsorenson
ericsorenson marked this pull request as ready for review June 5, 2026 20:50
@ericsorenson
Merge branch 'develop' into upgrade-storybook-8
2020e7b
@ericsorenson
Update preview.js
386240b
@ericsorenson
Add Storybook test-runner and a11y setup
df497d5 
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
ethangardner suggested changes Jun 10, 2026
View reviewed changes

@ethangardner ethangardner left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ericsorenson - There were a few very minor things and questions. Otherwise, this looks great. Thanks for the contribution.

Comment thread packages/usa-radio/src/usa-radio.stories.js
Comment thread packages/usa-checkbox/src/usa-checkbox.stories.js Outdated
Comment thread .storybook/preview.js
@github-project-automation github-project-automation Bot moved this from Triage to In progress in USWDS Core Project Data Jun 10, 2026
@olsonap

olsonap commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

Can I suggest using PR #6693 which predates this PR and includes many of these changes?
The deprecation of argTypes.defaultValue happened in the switch from Storybook 6 -> 7, not 7 -> 8.
PR #6693 would handle the deprecation from 6->7 and this PR can be focused on the 7->8 upgrade.

@ericsorenson
Add disabled_state arg; rename indeterminate key
ffa47ce 
Add a default disabled_state arg to both usa-checkbox and usa-radio stories and standardize the indeterminate prop name to indeterminate_state in the checkbox story's argTypes. This keeps story args consistent across form input components and ensures the indeterminate arg is referenced with the new suffix.
@ethangardner

ethangardner commented Jun 13, 2026

Copy link
Copy Markdown
Contributor

@olsonap - Fair point. One of the challenges we're facing right now is managing overlapping PR submissions. I'm doing my best to review and offer feedback on changes that move the design system forward.

In this case, I had a direct conversation with the submitter of this PR who agreed to take this work on, which is why I jumped on this review when I saw it come in. I acknowledge that the scope between upgrading to v8.6 and fixing issues from our recent v7 upgrade got a bit nebulous. I can definitely see how both interpretations were valid.

At this point, I've reviewed this PR, which is very close to merge-able, and I regrettably haven't started on a review for the one you submitted. I see that you've been submitting PRs for other issues both in this repo and on uswds-site that I owe you reviews on. I'll try to be better at leaving comments to acknowledge the time and effort that people put forth to submit PRs, even if the PRs can't be reviewed right away. The contributions and support we're getting truly is appreciated. Thanks for understanding.

ethangardner
ethangardner approved these changes Jun 15, 2026
View reviewed changes

@ethangardner ethangardner left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good to go! Thanks for the contribution!

@ethangardner
ethangardner merged commit 495ba75 into uswds:develop Jun 15, 2026
5 checks passed
@github-project-automation github-project-automation Bot moved this from In progress to Fed Final Review in USWDS Core Project Data Jun 15, 2026
This was referenced Jun 16, 2026
Closed
Closed
Closed
@chandracarney chandracarney moved this from Fed Final Review to Done in USWDS Core Project Data Jun 26, 2026
@chandracarney chandracarney added the Storybook Work on component stories, previews, or the Storybook development environment. label Jun 30, 2026
@ethangardner ethangardner added this to the uswds 3.14.0 - Aug 2026 milestone Aug 4, 2026
This was referenced Aug 11, 2026
Closed
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer
@ethangardner ethangardner ethangardner approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

Storybook Work on component stories, previews, or the Storybook development environment.

Projects

No open projects
USWDS Core Project Data
Status: Done

Milestone

uswds 3.14.0 - Aug 2026

Development

Successfully merging this pull request may close these issues.

USWDS: Update storybook

4 participants

@ericsorenson @olsonap @ethangardner @chandracarney