Dependency modernization: Node 24, Vite, and Storybook 10

[spaceninja]

Dependency modernization: Node 24, Vite, and Storybook 10

Our dependency backlog isn't a queue of independent updates — it's one blocked chain plus a set of genuinely independent upgrades. This issue records what's actually blocking what, and the PR sequence we're using to unwind it.

The core finding: webpack is a dead end for our Storybook

@storybook/html-webpack5 stops at 8.6.14 — there is no stable 9 or 10 release. Storybook 10 for HTML is Vite-only.

This inverts how we've been reading the backlog. The closed PRs for css-loader v7, style-loader v4, mini-css-extract-plugin v2, postcss-loader v8, babel-loader v10, and sass-loader v17 are not blocked work waiting on a webpack 5 upgrade. On the Vite path those packages are deleted, not upgraded. Roughly ten dependencies leave package.json entirely.

We should not spend effort upgrading to webpack 5.

Spike results

A full spike (Storybook 10.5.9 + Vite 8 + Twing 7) builds and renders real Twig output. Findings:

• The Twig source preview works, including syntax highlighting. This is the issue that killed [Review carefully] Update storybook monorepo to v6.5.16 #2006 — Storybook 10 exposes SyntaxHighlighter.registerLanguage, so registering the Twig Prism grammar is a supported hook rather than the fragile react-syntax-highlighter reach-in that broke between 6.5.9 and 6.5.16.
• Twing 7 still renders synchronously via createSynchronousEnvironment. Stories stay () => template(args) — no async migration needed.
• We must import twing/light. The full Twing build pulls in locutus → safe-buffer, which crashes under Vite (Cannot read properties of undefined (reading 'prototype')) because Vite does not polyfill Node builtins the way webpack 4 did. All 24 Twig filters our templates use were tested against light — no regressions.
• The Vite plugin is simpler than what it replaces. twing-loader + source-inputs-loader + val-loader + virtual-bundled-environment collapse into roughly 60 lines. The source preview no longer needs the brittle string-replace against twing-loader's generated return template.render(context); we own the render wrapper, so path and args are recorded directly.
• ~~The custom Sass glob importer must be rewritten to Sass's modern canonicalize/load API (~40 lines). It's shared with gulp-sass, so gulp-sass v6 moves at the same time.~~ Superseded: the importer was deleted, not rewritten. A modern importer owns a URL namespace — everything reached through it comes back to it to resolve, with no fallback to Sass's own loader — so expanding one glob made us responsible for reimplementing Sass's _partial and index lookup rules by hand. All 57 stylesheets are committed source files, so src/index.scss now lists them explicitly and neither Vite nor gulp-sass needs any Sass configuration. gulp-sass v6 still moved at the same time.

Main cost: all 84 .stories.mdx files must migrate to CSF3 + .mdx. Storybook 10 has no indexer for .stories.mdx at all (No matching indexer found). button.stories.mdx also uses webpack's !!raw-loader! syntax, which becomes ?raw.

Node is separately unblockable

Twing 3's only incompatibility with modern Node is util.isNullOrUndefined, removed in Node 22. With a small shim, both the full test suite and the existing Storybook 6.5 + webpack 4 build pass on Node 24. That decouples the Node upgrade — and roughly 20 rate-limited updates behind it — from the Storybook project.

PR sequence

Revised. The original list was a risk ordering, not a dependency chain — only the Node
bump actually unblocked anything. We reprioritised to take Storybook 10 + Vite early,
since it deletes a large part of the backlog rather than upgrading it. Items 4–6 were
independent of each other and of the work already shipped, so they could land in any
order. Only item 6 is left.

• 1. Node 16 → 24 — Upgrade CI and local development to Node 24 #2392. Shipped.
• 2. Storybook 10 + Vite + Twing 7 — Upgrade to Storybook 10 + Vite, and Twing 7 #2405. Shipped. Twing 7, a Vite Twig plugin,
  Storybook 6.5 → 10, React 17 → 19, gulp-sass 6, the 84-file MDX migration, and
  deletion of the webpack toolchain (~10 dependencies removed, not upgraded).
• 3. Library build — Upgrade the library build to Rollup 4 and TypeScript 5 #2406. Shipped. rollup 2→4, rollup-plugin-dts 6,
  @rollup/plugin-terser 1, @rollup/plugin-babel 7, @rollup/plugin-node-resolve 16,
  TypeScript 5. Touched neither Storybook nor Twig. Landing this first let Upgrade to Storybook 10 + Vite, and Twing 7 #2405
  drop the temporary @types/node override instead of carrying it.
• 4. Lint & format — Upgrade the lint and format toolchain: Prettier 3, ESLint 9, Stylelint 16 #2416. Shipped. Prettier 3, ESLint 8 → 9 via a
  migration from @cloudfour/eslint-plugin to its successor
  @cloudfour/eslint-config (flat config), eslint-plugin-mdx 3, Stylelint 16,
  and @whitespace/storybook-addon-html restored at v9. Two targets in this line
  were wrong: stylelint stops at 16, not 17, and ESLint stops at 9, not 10 —
  both capped by our own shared configs rather than upstream. Prettier 3 did not
  unblock formatting *.mdx; that turned out to be a still-open Prettier bug, so
  the .prettierignore rule stays. See the status comment below.
• Replace Pleasantest — Replace Pleasantest with Vitest browser mode #2421, filed as Replace Pleasantest in the component test suite #2417. Shipped. Not numbered in this
  sequence, but taken before item 5 because Jest 30 was in it. Jest, Pleasantest,
  Puppeteer, @types/jest, test-utils.ts and jest.setup.js are all gone; the
  suite runs on Vitest 4, split across a jsdom project and a Chromium one. The CI
  test job is off its ubuntu-22.04 pin. See the status comment below.
• 5. Misc toolchain — Upgrade the misc toolchain: Style Dictionary 5, cssnano 8, sass, js-yaml 5, npm-run-all2 9 #2422. Shipped. style-dictionary 5, cssnano 8, js-yaml 5,
  npm-run-all2 9, sass 1.103. Jest 30 was dropped from this item by Replace Pleasantest with Vitest browser mode #2421, which
  removed Jest rather than upgrading it. Style Dictionary 4 turned out to be a
  migration rather than a bump, and two of its changes were silent rather than
  loud — color/css stopped matching our CTI tokens and normalised nothing while
  the build stayed green. See the status comment below.
  Let design token tables size their own columns #2424 followed, fixing an unrelated defect the token pages had all along.
• 6. Remove Gulp — 280 lines across 5 tasks and 6 gulp packages, and
  it is thinner than it looks: build-tokens.js is a 5-line wrapper that shells out
  to npm run preprocess:tokens, and build-scripts.js is already plain Rollup API.
  Deliberately kept out of the Storybook PR to keep that reviewable. One constraint
  to carry across: buildTypes generates an entry that resolves ./src/… relative
  to ts-dist, so whatever replaces it has to keep emitting declarations under
  ts-dist/src. That layout is pinned by rootDir as of Replace Pleasantest with Vitest browser mode #2421 — see the status
  comment below for why it was an accident before.
  Two things to fix rather than port verbatim while rewriting these tasks:
  .svgo.yml uses the old plugin-config format (- removeXMLNS: true), which is
  what produces the not part of preset warning listed below — it travels with the
  svgToTwig task rather than being fixed by dropping gulp; and build-scripts.js
  has the entry-glob bug in Storybook demo args are published as part of the public API #2427, which a faithful port would carry across.

Changes forced by the Storybook work

• @types/node is pinned to 20.19.9 via overrides. Resolved — never landed.
  Webpack 4's dependency tree was holding it at 12.20.6; removing webpack let it float to
  26.2.0, which TypeScript 4.9 could not parse (syntax errors in ffi.d.ts, and
  skipLibCheck does not suppress parse errors). Pinning was the cheaper option at the
  time, but Upgrade the library build to Rollup 4 and TypeScript 5 #2406 landed TypeScript 5.9 first, so Upgrade to Storybook 10 + Vite, and Twing 7 #2405 was rebased onto it and dropped
  the override. There is no overrides block in package.json on main.
• @babel/preset-typescript is now a direct dependency. babel.config.js used it,
  but it was only present transitively via the Storybook 6 packages.
• eslint-plugin-mdx 3 moved out of the Storybook PR. It was blocked because MDX 1
  allowed arbitrary top-level JS and .stories.mdx relied on it. Now that the 84 files
  are MDX 3, the upgrade should be straightforward, so it belongs with the lint work.
• src/**/*.stories.js is excluded from tsconfig. Converting MDX to JS brought
  250+ story functions under checkJs for the first time — 269 errors. Stories are demo
  code, are not published, and were not type-checked as MDX either, so excluding them
  preserves existing coverage rather than expanding the PR. Type-checking stories would
  be a real improvement, but it is its own piece of work.

The PR 5 split idea did not pan out

The earlier note suggested extracting CSF from MDX while still on Storybook 6, to split
the migration in two. Both halves of that turned out to be dead ends:

• Storybook's own mdx-to-csf codemod cannot read our files. It parses with MDX 3,
  which rejects MDX 1's top-level const declarations — the exact thing every one of
  our story files used. The Storybook 10 CLI has also dropped the codemod entirely; it
  only survives in @storybook/codemod@8. Worth recording so nobody retries this.
• Migrating the files therefore needed a purpose-written transformer, which was going to
  be the bulk of the work either way. Splitting would have added a throwaway
  intermediate state without reducing the total effort.

Addon decisions needed in PR 5

• storybook-addon-outline — flagged deprecated with no replacement; outlines are built into Storybook core now, so this can likely just be dropped.
• storybook-mobile and @whitespace/storybook-addon-html — already commented out in .storybook/main.js "until they are fixed upstream". Drop them, or restore at v9.
• @storybook/addon-essentials and @storybook/addon-postcss — both removed/obsolete in Storybook 10.
• @etchteam/storybook-addon-status — needs v8.

Housekeeping

We run both Renovate and Dependabot, which is generating duplicate PRs for the same upgrades (lodash in #2368 and postcss in #2373 both duplicated Renovate security PRs at older versions, which is why they conflicted). Renovate is also configured with :automergeMinor, but branch protection requires an approving review, so its automerge can never fire. Aligning these would keep the backlog from rebuilding.

Split out as #2430, so it outlives this issue. One detail found while filing it: there is no .github/dependabot.yml, so Dependabot is enabled through repository settings rather than config — which is part of why it is easy to forget it is running.

Smaller items noticed along the way

• gulp-svgmin v4 emits a warning: You are trying to enable removeXMLNS which is not part of preset. The SVGO plugin config needs updating. Folded into item 6 as an explicit deliverable — .svgo.yml uses the old plugin-config format, so it travels with the svgToTwig rewrite rather than being fixed by it.
• package.json still declares engines.node: ">=12.16.3". This describes what consumers of the published package need, not our dev environment, so it deliberately wasn't changed in PR 1 — but it's stale and deserves its own decision. Split out as Decide what engines.node is for, or remove it #2423, and the framing above was wrong: the field started life in Change how renovate handles node versions #689 as an exact pin of the development Node version, so nobody has actually decided it describes consumers. Raising it is also a breaking change rather than housekeeping — pnpm and Yarn Berry fail installs on an engines mismatch, and nothing we publish runs on Node — so the real options are removing it or leaving it, not bumping it.

Storybook 6 → 10 API moves (for reference)

Collected while doing the migration:

Storybook 6	Storybook 10
docs.transformSource	docs.source.transform
docs.inlineStories	docs.story.inline
docs.prepareForInline	not needed — the HTML renderer inlines natively
viewport.viewports	viewport.options
@storybook/client-api	storybook/preview-api
@storybook/addons	storybook/manager-api
@storybook/theming/create	storybook/theming/create
@storybook/addon-viewport	storybook/viewport
<Description>{markdown}	<Markdown>{markdown} — Description now takes of={}
<ArgsTable>	<Controls>
ReactSyntaxHighlighter.registerLanguage	SyntaxHighlighter.registerLanguage from storybook/internal/components
require.context	import.meta.glob
!!raw-loader!x	x?raw
@svgr/webpack inline loader	vite-plugin-svgr with ?react

Two Twing 7 changes worth knowing: the filesystem loader is built from an injected fs
rather than a path, and path namespaces now include the sigil (@cloudfour, not
cloudfour). Rendering can still be synchronous via createSynchronousEnvironment, so
story functions keep returning strings.

The browser build must import twing/light. The full build pulls in locutus, which
needs Node's Buffer; webpack 4 shimmed that automatically and Vite does not, so the
bundle dies on load. All 24 filters our templates use work in light.

[spaceninja]

PR 1 of the sequence is open: #2392 (Node 16 → 24).

[spaceninja]

Found while verifying PR #2392: @svgr/webpack v8 (merged in #2386) is incompatible with webpack 4 — it calls this.getOptions(), which only exists on webpack 5's loader context. All 48 icons fail to compile, and because webpack 4 downgrades a failed loader to a warning, CI stayed green while Design → Icons rendered blank.

Fix is up as #2395 (pin back to v5). Adding to the notes above: this is a second reason not to invest in webpack 5 — @svgr/webpack is dropped entirely on the Vite path.

[spaceninja]

Reordered the plan above. To be explicit about what changed and why:

Nothing is invalidated. The original numbering read like a dependency chain, but only the Node bump actually unblocked anything — the library-build, lint, and misc-toolchain PRs were always independent of Storybook and Twig, and still are. They can land before or after the Storybook work in any order.

We moved Storybook 10 + Vite to the front because it deletes around ten dependencies rather than upgrading them, so it shrinks the backlog instead of working through it.

Three things the Storybook work changed for the other PRs:

• The library-build PR picks up one extra task: removing the temporary @types/node override. Webpack 4's tree was pinning that package at 12.20.6, and removing webpack let it float to a version TypeScript 4.9 can't parse.
• eslint-plugin-mdx 3 moved out of the Storybook PR and into the lint PR. It was blocked by MDX 1; now that the story files are MDX 3 it should be straightforward.
• Prettier 3 gained a second benefit — it unblocks restoring @whitespace/storybook-addon-html at v9.

Also recorded above: the suggested "split PR 5" approach is a dead end (Storybook's own mdx-to-csf codemod can't parse MDX 1 input, and Storybook 10 dropped the codemod entirely), plus a reference table of the Storybook 6 → 10 API moves so the next person doesn't have to rediscover them.

[spaceninja]

Handoff / current state

Recording where things stand so this can be picked up cold.

Shipped

• Upgrade CI and local development to Node 24 #2392 — Node 16 → 24. Merged. Added a temporary util shim for Twing 3, since removed.
• Revert @svgr/webpack to v5 for webpack 4 compatibility #2395 — revert @svgr/webpack to v5. Merged. v8 uses the webpack 5 loader API, so all 48 icons silently failed to compile on webpack 4 and the Icons page rendered blank. Superseded by Upgrade to Storybook 10 + Vite, and Twing 7 #2405, which drops the package entirely.

In review

#2405 — Storybook 10 + Vite + Twing 7. Three commits, all CI green. Awaiting review, then Gerardo.

Verified: lint:check, type, build, test (9 suites / 25 tests / 20 snapshots), build-storybook, and a headless sweep of all 253 stories and 84 docs pages — no empty or failed renders. Twig source previews show {% include %} snippets with syntax highlighting.

Three defects were found by eyeballing the deploy preview after the automated sweep passed, and are fixed in the last commit — worth noting because they show the limits of the sweep, which only checks that something rendered, not that it rendered correctly:

• Modular Scale table showed steps -60, -61 and sizes 0em. Token values are strings, so minimumStep + index concatenated. The for loop it replaced got away with it because i++ coerces.
• Fonts 404ed. Fixed by making the font path a configurable Sass variable — see the PR body.
• Sky Nav rendered open with no toggle after navigating between stories: useEffect(fn, []) runs once per preview session, and the template's no-js class is cleared by an inline <script> that never runs when markup is injected as a string.

Remaining work, in no required order

Only the Node bump ever unblocked anything; these are independent.

• Library build — rollup 2→4, rollup-plugin-dts 6, @rollup/plugin-terser 1, @rollup/plugin-babel 7, @rollup/plugin-node-resolve 16, TypeScript 5. Also removes the @types/node override added in Upgrade to Storybook 10 + Vite, and Twing 7 #2405 (overrides in package.json, pinned to 20.19.9). Webpack 4's tree held that package at 12.20.6; removing webpack let it float to 26.2.0, which TypeScript 4.9 cannot parse — and skipLibCheck does not suppress parse errors. TS 5 forces rollup-plugin-dts 6, which forces rollup 4, which is why these travel together.
• Lint & format — prettier 3, eslint, stylelint 17 + configs, and eslint-plugin-mdx 3. Two things unblock once Prettier is on 3:
  • *.mdx can come out of .prettierignore. Prettier 2 corrupts MDX 3 files: it rewrites the required {/* … */} comments into {/_ … _/} (reading the asterisks as markdown emphasis) and glues self-closing JSX onto the following markdown block.
  • @whitespace/storybook-addon-html v9 can be restored; it supports Storybook 10 but requires Prettier ^3.7.1.
• Misc toolchain — jest 30, style-dictionary 5, cssnano 8, js-yaml 5, npm-run-all2 9, sass.
• Remove Gulp — 286 lines across 5 tasks, 6 gulp-* dependencies. Thinner than it looks: gulpfile.js/tasks/build-tokens.js is a 5-line wrapper that shells out to npm run preprocess:tokens (delete outright), and build-scripts.js is already plain Rollup API.

Smaller follow-ups discovered along the way

• Type-check story files. src/**/*.stories.js is excluded in tsconfig.json. Converting MDX to JS brought 250+ story functions under checkJs for the first time — 269 errors. Excluding preserved the previous coverage (they were never checked as MDX) rather than widening Upgrade to Storybook 10 + Vite, and Twing 7 #2405. Worth doing properly.
• Revisit the docs.story.inline: false workarounds. Several stories disable inline rendering, and the comments blame html-to-react, which Upgrade to Storybook 10 + Vite, and Twing 7 #2405 removes — Storybook 10's HTML renderer inlines natively. They may be unnecessary now. Left alone deliberately, since changing them alters rendering behaviour.
• gulp-svgmin v4 warning. You are trying to enable removeXMLNS which is not part of preset — that optimisation is silently not applied to generated Twig SVGs. The SVGO plugin config needs updating.
• engines.node is still >=12.16.3. Deliberately untouched: it describes what consumers of the published package need, not our dev environment, so raising it is a consumer-facing change needing a changeset. Stale, but its own decision.

Notes for whoever picks this up

• Use Node 24.19.0 (nvm use, or .nvmrc). The machine's default Node is newer than CI's, and npm install under it will float @types/node and produce a different lockfile.
• The lockfile is lockfileVersion: 2. Regenerate with npm 8 (Node 16/24 era) rather than npm 11, or the whole file rewrites to v3.
• Don't trust --fix blindly here. Three autofixers actively introduced bugs during Upgrade to Storybook 10 + Vite, and Twing 7 #2405: Prettier 2 on MDX (above), and ESLint's n/file-extension-in-import appending extensions to package export subpaths (storybook/preview-api → .js) and after Vite query suffixes (x.twig?raw → ?raw.twig). That rule is now disabled for *.mdx, *.stories.js and .storybook/** for exactly this reason.
• A green build-storybook does not mean the stories work. It reported success while 47 stories rendered blank and while every icon silently failed to compile. The check that actually caught things was loading each story ID in headless Chrome and asserting #storybook-root had content and no error banner — worth rebuilding if more Storybook work is coming.
• Renovate/Dependabot churn is expected and should be left alone. Closing PRs just makes more from the backlog; a lot of it evaporates as these upgrades land.

[spaceninja]

Status update: library build shipped, Storybook PR rebased

Shipped

#2406 — Library build. Merged. rollup 2 → 4, rollup-plugin-dts 4 → 6, @rollup/plugin-terser 0.4 → 1, @rollup/plugin-babel 6 → 7, @rollup/plugin-node-resolve 13 → 16, TypeScript 4.9 → 5.9.

No build code changed — build-scripts.js was already on the plain Rollup JS API with the modern scoped plugins, so all six majors were drop-in. The diff was 12 lines of package.json plus the lockfile.

One thing worth recording, because it was not expected: the published UMD bundles shrank about 5×. sky-nav.ts imports the generated token module for three values, and rollup 2 emitted all 97KB of it; rollup 4 tree-shakes the object down to the reachable leaves. dist/cloudfour-patterns.js went 116KB → 21KB and .min.js 37KB → 7.8KB, with identical exports. dist/cloudfour-patterns.mjs is byte-for-byte unchanged, which explains the asymmetry: terser's module: true pass was already doing this elimination on the ESM output, so only the UMD builds — which terser cannot treat as a module — were carrying the dead tokens. That was latent bloat in main/unpkg specifically, not something the upgrade introduced.

In review

#2405 — Storybook 10 + Vite + Twing 7. Rebased onto main after #2406, all CI green, still awaiting review.

Only the first of its four commits conflicted, and only in package.json / package-lock.json — resolved as this branch's Storybook/Vite packages plus main's upgraded rollup toolchain. For the lockfile, main's version was taken as the base and npm 8 re-applied the branch's package.json on top, so the diff reads against the new main rather than as a merge artifact.

Two corrections to the plan above

The @types/node override removal did not happen in #2406. The plan listed it there, but that overrides block only ever existed on #2405's branch — main had no override at all, because webpack 4's tree was still pinning @types/node to 12.20.6. So it became a rebase-time step for whichever PR merged second, and it landed with the #2405 rebase instead. It works: with the override gone, @types/node floats to 26.2.0 and npm run type passes under TypeScript 5.9. The distinction the notes drew held up exactly — skipLibCheck covers the residual Buffer/Uint8Array check errors, and TypeScript 5 no longer produces the parse errors that skipLibCheck could not suppress.

"TypeScript 5" should be read as a ceiling, not a starting point. TypeScript's current release is 7.0.2, and rollup-plugin-dts 6 happily accepts ^4.5 || ^5 || ^6 || ^7 — so it is not the constraint anyone would guess. The real limit is @typescript-eslint, held at 5.17 by @cloudfour/eslint-plugin, which peers on ESLint 8. TypeScript 6 also removes moduleResolution: "node", which tsconfig.json still uses, and 7 is the Go-based native compiler rewrite. Going past TypeScript 5 is gated on the lint PR, and is worth treating as its own piece of work rather than a version bump. TypeScript 5.9 does not warn about moduleResolution: "node", so tsconfig.json was left alone.

A note on changesets, since the sequence has now hit both cases

PRs 1 and 2 correctly had none — they changed only dev tooling. The test that actually decides it is whether the PR changes a file we publish, per the files array in package.json:

• Upgrade the library build to Rollup 4 and TypeScript 5 #2406 got a patch changeset for the UMD size reduction, since it changes dist.
• Upgrade to Storybook 10 + Vite, and Twing 7 #2405 got three (net minor), because three of its fixes are in published files rather than tooling: base/fonts gaining a configurable $dir (a new public Sass API — minor), footnote-link.twig moving off the spaceless tag Twig 3 removed (patch), and initSkyNav clearing no-js (patch). dist/standalone.css is byte-for-byte identical, which is what makes the $dir change additive rather than a breaking path change.

Two published files needed no entry: src/index.scss is excluded from files, and src/index-with-dependencies.scss imports from node_modules and documents itself as Storybook-only, so no consumer can use it.

Related: #2405's body never actually documented the font fix, despite the handoff comment above pointing readers to it. It does now.

Remaining work, still in no required order

• Lint & format — prettier 3, eslint, stylelint 17 + configs, eslint-plugin-mdx 3. Unchanged, except that it now also gates any move past TypeScript 5 (above). Still unblocks taking *.mdx out of .prettierignore and restoring @whitespace/storybook-addon-html at v9.
• Misc toolchain — jest 30, style-dictionary 5, cssnano 8, js-yaml 5, npm-run-all2 9, sass.
• Remove Gulp — 286 lines across 5 tasks, 6 gulp-* dependencies.

Smaller follow-ups

Carrying forward, unchanged: type-checking src/**/*.stories.js; revisiting the docs.story.inline: false workarounds; the gulp-svgmin removeXMLNS warning; and the stale engines.node: ">=12.16.3".

One new one:

• Storybook demo args leak into the published types. dist/cloudfour-patterns.d.ts exports defaultArgs and defaultArgTypes, which come from src/components/*/*-args.js being caught by the rollup entry glob in build-scripts.js. Same class of bug Upgrade to Storybook 10 + Vite, and Twing 7 #2405 fixed for .stories.js, just for the args files. Pre-existing and unrelated to either upgrade, but now visible in the type output.

One more environment note

Worth adding to the notes above: when rebasing between these branches, rollup deduped to a single copy. #2405 previously carried rollup 2.80 as a devDependency alongside the 4.x copy Vite 8 pulls in, and npm silently nested both. Aligning the devDependency with what Vite already requires collapsed it to one 4.62.5. It only shows up in the lockfile, not the build output, so it is easy to miss.

[spaceninja]

Status update: Storybook 10 + Vite shipped — half the sequence is done

#2405 is merged (96fd86e1). With #2392, #2395 and #2406, items 1–3 of the sequence are complete and checked off above. The webpack toolchain is gone from package.json entirely — the only match for webpack|loader|svgr on main is now vite-plugin-svgr, which is the Vite replacement.

Two entries in the plan above were corrected rather than checked off, since both spike predictions turned out to be wrong in ways worth recording:

• The Sass glob importer was deleted, not rewritten. The spike estimated ~40 lines to port it to Sass's modern canonicalize/load API. A modern importer owns a URL namespace, so everything reached through it comes back to it to resolve with no fallback to Sass's own loader — expanding one glob made us responsible for reimplementing Sass's _partial and index lookup rules by hand. All 57 stylesheets are committed source files, so src/index.scss lists them explicitly and no Sass configuration is needed anywhere.
• The @types/node override never landed. Sequencing Upgrade the library build to Rollup 4 and TypeScript 5 #2406 first meant Upgrade to Storybook 10 + Vite, and Twing 7 #2405 could rebase onto TypeScript 5.9 and drop the pin. There is no overrides block on main.

What's left

Verified against main rather than from the plan, with current npm latest for comparison:

Item	Package	On main	Latest
4. Lint & format	prettier	2.8.8	3.9.6
	eslint	8.33.0	10.8.1
	stylelint	14.16.1	17.14.1
	eslint-plugin-mdx	1.17.1	3.8.1
	stylelint-config-cloudfour	6.1.0	10.0.0
5. Misc toolchain	jest	28.1.3	30.4.2
	style-dictionary	3.9.2	5.5.2
	cssnano	5.1.15	8.0.7
	js-yaml	4.3.1	5.3.0
	npm-run-all2	8.0.4	9.0.3
6. Remove Gulp	gulp + 5 gulp-*	—	282 lines across 5 tasks

Item 4 is the one with knock-on value: Prettier 3 unblocks restoring @whitespace/storybook-addon-html at v9, and it lets us drop the *.mdx line from .prettierignore that #2405 had to add — Prettier 2 corrupts MDX 3 files by rewriting {/* ... */} comments into {/_ ... _/}.

Release pending

main is at 17.1.0 with four unreleased changesets — three patch (Sky Nav string injection, Footnote Link spaceless, UMD bundle shrink) and one minor (base/fonts $dir), so the next release is 17.2.0.

Still open, unchanged

• engines.node is still ">=12.16.3". It describes what consumers need rather than our dev environment, so it was deliberately left alone — but it's stale and wants its own decision.
• gulp-svgmin v4 still warns You are trying to enable removeXMLNS which is not part of preset.
• We still run both Renovate and Dependabot, and Renovate's :automergeMinor still can't fire because branch protection requires an approving review.

[spaceninja]

Status update: lint & format is up for review

#2416 is open and CI is green (lint, type, build, build-storybook, test), with a
working deploy preview. Six commits, ordered so the mechanical churn is separable: the
Prettier bump, the repo-wide reformat it causes, then each linter.

Package	Was	Now
prettier	2.8.8	3.9.6
@cloudfour/eslint-plugin	21.1.0	removed
@cloudfour/eslint-config	—	25.0.1
eslint	8.33.0	9.39.5
eslint-plugin-mdx	1.17.1	3.8.1
stylelint	14.16.1	16.26.1
stylelint-config-cloudfour	6.1.0	10.0.0
stylelint-scss	4.7.0	7.2.0
stylelint-use-logical-spec	4.1.0	5.0.1
stylelint-config-prettier	9.0.5	removed
@whitespace/storybook-addon-html	—	9.0.0 (restored)

Three corrections to the plan above

@cloudfour/eslint-plugin is superseded by @cloudfour/eslint-config, and switching
lifts the TypeScript ceiling. The notes above record that going past TypeScript 5 was
gated on @typescript-eslint being held at 5.17 by the plugin, which peers on
eslint: ^8.0.0 even at its latest release. The config peers on >= 9 and bundles
typescript-eslint 8, so that specific blocker no longer exists. What remains is
narrower and unrelated to lint: TypeScript 6 removes moduleResolution: "node", which
tsconfig.json still uses, and 7 is the Go-based rewrite. Switching also means flat
config — .eslintrc.js and .eslintignore became eslint.config.mjs — and the plugins
the config wraps jump several majors (unicorn 47 → 63, jsdoc 46 → 62, n 17).

Neither linter reaches the version the plan listed, and in both cases the cap is one of
our own shared configs rather than anything upstream.

• ESLint stops at 9, not 10. eslint-plugin-react supplies the jsx-uses-vars rule
  the MDX files rely on, and it peers at ^9.7 with no 10 release (latest is 7.37.5).
• Stylelint stops at 16, not 17. stylelint-config-cloudfour 10 and
  stylelint-use-logical-spec both cap at 16 independently, so 17 would mean running our
  own shared config unsupported.

Prettier 3 does not fix the MDX corruption, so *.mdx is still in .prettierignore.
This was listed above as one of the two things Prettier 3 unblocks; it turned out to be
wrong, and is worth recording so nobody retries it. Prettier 3 has no MDX 3 support either
(prettier/prettier#12209) and still mangles multi-line {/* … */} comments into
{/_ … _/} (prettier/prettier#15163, open since 2023) — output that is not valid MDX, so
Storybook fails to index the file with Could not parse expression with acorn.

There is no per-file opt out. {/* prettier-ignore */} has no effect, and
<!-- prettier-ignore --> does silence Prettier but is not valid MDX 3 — Storybook's own
error tells you to use {/* … */} instead. The only syntax Prettier honours is the one
MDX rejects. Only multi-line comments are affected, which is why 71 of 84 files were
already clean, so the other 80 were formatted once by hand and the ignore rule reinstated
with the real reason recorded in the file.

The other Prettier 3 benefit did hold: @whitespace/storybook-addon-html is back at v9,
verified rendering markup in the panel on the deploy preview. storybook-mobile stays
dropped — still 1.0.1, peering on React ^17 while Storybook 10 is on 19.

Two things found along the way

eslint-plugin-mdx v1 was setting eslint-mdx as the parser for every file, not just
Markdown. One root cause, three symptoms: the "eslint isn't merging the overrides as
expected" workaround in .eslintrc.js, unicorn/no-empty-file falsely reporting four
token files whose only statement is module.exports, and a stale
mdx/no-unused-expressions disable in sky-nav.ts. All three are gone now that v3 scopes
its parser correctly.

n/no-unsupported-features/* reads engines.node. With the newer eslint-plugin-n
this produced ten errors, all in files we never publish — the gulpfile, Storybook config
and tests were being checked against Node 12.16.3. The PR sets settings.n.version to our
development Node instead, deliberately leaving engines.node alone since it is
consumer-facing and listed below as its own decision. Worth knowing that the stale field
now has a second consequence beyond being merely inaccurate.

A note on autofixers, since this PR was almost entirely autofixers

The warning in the handoff notes earned its keep three more times. Beyond the two MDX
cases, unicorn/prefer-global-this rewrote window.setTimeout to
globalThis.setTimeout in subscribe.ts. Same function at runtime, but TypeScript
resolves the two to different overloads — DOM returns number, Node returns Timeout —
so it introduced a type error that lint reported clean and only tsc caught. The rule
is off for src, where window is both correct and better typed.

Published output

Verified rather than assumed: the Prettier reformat leaves dist byte-for-byte
identical, and after the globalThis revert so do the ESLint fixes —
cloudfour-patterns.mjs and .min.js are unchanged, and the only differences in the
unminified UMD bundle are comment text. Stylelint surfaced three genuine findings, of
which only a collapsible place-self pair changes published CSS, and only into an
equivalent declaration. That one carries a patch changeset, bringing the pending release
to five changesets.

The headless story sweep described in the notes was rebuilt and re-run: all 337 entries
(253 stories, 84 docs) render with content and zero page errors.

Remaining work

Item	Package	On main	Latest
5. Misc toolchain	jest	28.1.3	30.4.2
	style-dictionary	3.9.2	5.5.2
	cssnano	5.1.15	8.0.7
	js-yaml	4.3.1	5.3.0
	npm-run-all2	8.0.4	9.0.3
	sass	1.102.0	1.103.1
6. Remove Gulp	gulp + 5 gulp-*	—	282 lines across 5 tasks

Both are independent of each other and of everything shipped. One note for item 6 from
working in these files: build-scripts.js is now 115 of those 282 lines and is plain
Rollup API, build-tokens.js is still a 5-line shell-out to npm run preprocess:tokens,
and watch-preprocess.js is 9 lines.

Still open, unchanged

• engines.node is still ">=12.16.3" — see above for its new second consequence.
• gulp-svgmin v4 still warns You are trying to enable removeXMLNS which is not part of preset.
• We still run both Renovate and Dependabot, and Renovate's :automergeMinor still cannot
  fire because branch protection requires an approving review.

New follow-up

• Storybook globs a nonexistent src/welcome.mdx #2415 — .storybook/main.mjs globs ../src/welcome.mdx, which has not existed
  since Leverage markdown docs #1220 deleted it. Upgrade to Storybook 10 + Vite, and Twing 7 #2405 renamed the dangling pattern along with every other
  .stories.mdx; Storybook 10 reports unmatched patterns, so it now warns on every build.