Upgrade to Storybook 10 + Vite, and Twing 7

[spaceninja]

Overview

Moves the pattern library from Storybook 6.5 + webpack 4 to Storybook 10 + Vite, and Twing 3 to Twing 7.

The reason this is a replacement rather than an upgrade: there is no webpack framework for HTML at Storybook 9 or 10.@storybook/html-webpack5 stops at 8.6.14, with no stable 9 or 10 release — Storybook 10 for HTML is Vite-only. So webpack and its loaders are deleted rather than upgraded, which also settles a chunk of the dependency backlog: css-loader, style-loader, postcss-loader, sass-loader, mini-css-extract-plugin, babel-loader, raw-loader, val-loader, @svgr/webpack and twing-loader all leave package.json. Vite handles Sass, PostCSS and asset URLs natively, so the ~70-line custom webpack config in .storybook/main.js is gone too.

This also fixes the problem that kept us on 6.5.9 specifically. #2006 was closed because Twig source-preview syntax highlighting broke on a 6.5.16 patch bump, and that was never resolved upstream. Storybook 10 exposes SyntaxHighlighter.registerLanguage as a supported hook, so registering the Twig grammar is a one-liner rather than a reach into react-syntax-highlighter's internals. The previews work, with highlighting.

Why the Sass @use lines needed custom JavaScript

Worth explaining, because the premise looks wrong at first glance — @use is stock Sass and has never been a problem.

Globs in @use are not a Sass feature. Sass has never supported glob patterns in @use, @forward or @import, and that is a deliberate design decision, not an oversight. So this, in src/index.scss:

@use'./components/*/*.scss'ascomponents;

was never Sass doing anything. It only worked because glob-sass-importer.js intercepted the pattern and synthesised the file list in JavaScript. Two other details were tells that we were working against the grain: the as components aliases existed only because Sass cannot derive a namespace from a glob pattern, and nothing in the codebase ever referenced those namespaces — zero usages across every .scss file. The importer's entire job was producing 57 @forward lines that are identical on every build.

The cost of that jumped sharply here. Sass has two importer APIs, and Vite and gulp-sass 6 both use the modern one. A legacy importer returned {contents} and Sass resolved nested imports relative to the importing file. A modern importer instead owns a URL namespace: everything reached through your importer comes back to your importer to resolve, and Sass never falls back to its own filesystem loader. Expanding one glob therefore made us responsible for resolving the entire subtree beneath it — I had a working version, and it required reimplementing Sass's own _partial and index lookup rules by hand.

Since all 57 stylesheets are committed source files with nothing generated among them, there was no reason for that list to be computed at build time at all. src/index.scss now lists them explicitly. glob-sass-importer.js is deleted, neither Vite nor gulp-sass needs any Sass configuration, and every @use/@forward line in the repo is now plain Sass. Adding a stylesheet means adding a line, and load order becomes an intentional choice rather than a side effect of alphabetical globbing.

Story files

Storybook 8 removed .stories.mdx, so all 84 files split into a .stories.js (the story definitions) plus a .mdx (the prose). 253 stories and 84 docs pages, matching what was there before.

Storybook's own mdx-to-csf codemod could not do this: it parses with MDX 3, which rejects the top-level const declarations MDX 1 allowed — and every one of these files used them. Storybook 10 has also dropped the codemod from its CLI. The conversion used a purpose-written transformer plus manual fixes for the files it could not handle.

Decisions a reviewer might question

• No @types/node override, following the rebase onto Upgrade the library build to Rollup 4 and TypeScript 5 #2406. This branch previously pinned @types/node to 20.19.9. Webpack 4's dependency tree had been holding it at 12.20.6, and removing webpack let it float to 26.2.0, which TypeScript 4.9 cannot parse — pinning was the cheaper option than dragging the whole library-build upgrade in here. Now that Upgrade the library build to Rollup 4 and TypeScript 5 #2406 has landed TypeScript 5.9 on main, the pin is unnecessary: @types/node floats to 26.2.0 and npm run type passes. Rebasing also deduplicated rollup — this branch previously carried 2.80 as a devDependency alongside the 4.x copy Vite 8 pulls in, and there is now a single 4.62.5.
• Prettier no longer formats .mdx. Prettier 2 predates MDX 2/3 and actively corrupts these files: it rewrites the {/* ... */} comments MDX 3 requires into {/_ ... _/}, reading the asterisks as markdown emphasis, and glues self-closing JSX onto the following markdown block. The Prettier 3 upgrade should remove the exclusion.
• n/file-extension-in-import is disabled for stories, docs and .storybook. Its autofix appends extensions to things that are not file paths — package export subpaths (storybook/preview-api → .js) and Vite query suffixes (x.twig?raw → ?raw.twig) — so the fix introduces the bug. Disabling beat annotating ~120 imports.
• src/**/*.stories.js is excluded from type checking. Converting MDX to JS brought 250+ story functions under checkJs for the first time, producing 269 errors. Stories are demo code, are not published, and were not type-checked as MDX either, so this keeps the previous coverage rather than widening this PR. Type-checking them is a worthwhile follow-up.
• Three addons dropped.storybook-addon-outline and storybook-mobile are React 17-only with no Storybook 10 release; outlines are built into Storybook core now, and the other two were already commented out in main.js as broken upstream. @whitespace/storybook-addon-html has a v9 that supports Storybook 10 but needs Prettier 3, so it should come back with that upgrade. @etchteam/storybook-addon-status is upgraded and kept.
• twing/light, not twing. The full build pulls in locutus, which needs Node's Buffer. Webpack 4 shimmed that automatically; Vite does not, and the bundle dies on load. All 24 filters our templates use behave identically in light.
• Gulp is untouched here. Removing it is worth doing and is tracked in Dependency modernization: Node 24, Vite, and Storybook 10 #2391, but folding it into this PR would make it much harder to review.

Two decorators were also reaching for #root, which Storybook renamed to #storybook-root in v7, and were silently doing nothing. Fixed.

What this changes for consumers

Mostly nothing — the webpack-to-Vite swap is invisible outside the repo. But three fixes landed in files we publish, so there are changesets for them, adding up to a minor bump.

base/fonts gains a $dir variable (minor). Fonts 404ed in Storybook. src/base/_fonts.scss pointed at ../src/assets/fonts/…, which is correct for the published package — dist/standalone.css ships alongside the src/assets directory — but does not resolve relative to the stylesheet, so Vite left the URL alone and the browser resolved it against the emitted CSS. Rather than hardcode a second path, the directory is now a configurable $dir, defaulting to the value consumers need, with Storybook's own entry point overriding it. That default means dist/standalone.css is byte-for-byte identical to main; the only difference is that consumers can now override the location.

Footnote Link renders under Twig 3 again (patch). It used the spaceless tag, which Twig 3 removed, so the template could not render at all. It now uses the spaceless filter, supported since Twig 2.9. Output is unchanged.

Sky Nav works when its markup is injected as a string (patch). The template's no-js class is cleared by an inline <script>, which only runs when the browser parses the markup. Anything injecting the template as a string skipped it, leaving the menu permanently open with no toggle button. initSkyNav now clears the class itself, since that function running is proof JS is available.

Two published files changed without needing a changelog entry: src/index.scss is excluded from the package's files, and src/index-with-dependencies.scss — which sets the $dir override — imports from node_modules and documents itself as Storybook-only, so no consumer can use it.

Screenshots

Testing

Every story and docs page was checked in a headless browser — all 337 render, with no console errors. That leaves the things a machine cannot judge: whether pages look right, and whether the interactive bits still work.

Start with the deploy preview:

• Open the preview and confirm the sidebar looks normal — sections in the usual order, starting with Introduction
• Open Introduction, Contributing and Changelog and confirm each shows its full text rather than a blank page
• Open Design → Icons and confirm you see a grid of icons with names beneath them, plus a Third-Party Brands grid lower down
• Open Design → Illustrations and confirm the fallback feature images, the responsive fallback image, and both avatars appear
• Open Design → Modular Scale and confirm the table shows a row per step with a bar that grows down the page
• Open a few token pages under Design → Tokens (Color, Font, Size) and confirm the tables are populated rather than empty

Then the Twig source previews, which are what broke last time:

• On Components → Badge, expand Show code under any example
• Confirm it shows a Twig snippet starting {% include '@cloudfour/…' %} — not raw rendered HTML
• Confirm that snippet is syntax-highlighted (coloured tags and strings, not one flat block)
• Change a control (for example Badge's label) and confirm the snippet updates to match

Then interactivity and layout, since these use decorators that this PR touched:

• On Components → Sky Nav, narrow the window and confirm the menu button opens and closes the navigation
• Still on Sky Nav, navigate to another component and back, then confirm the menu button is still there and still works — it used to disappear, leaving the menu stuck open
• On Components → Input, type into the textarea example and confirm it grows as you type
• On Objects → Page, confirm the example fills the frame edge to edge with no scrollbar or stray gap
• On Components → Cloud Cover, check the Full Height story fills the frame
• On Components → Card, use the Theme toolbar control and confirm Light, Dark and the Alt variants all change the page
• Use the Text flow toolbar control and confirm the right-to-left option flips the layout

Fonts are worth a look of their own, since the path handling changed:

• On any text-heavy page (Sky Nav is fine), confirm the body text is in the Source Sans typeface rather than a system fallback like Times or Arial
• Open Design → Defaults and confirm the heading and paragraph samples use that same typeface, at the expected weights — a fallback tends to show up as heavier, wider headings

Finally, a check on the published package, since the build changed:

• Run npm run build, then confirm dist/standalone.css is roughly 470KB and contains component styles (grep -c c-badge dist/standalone.css should be non-zero)
• Confirm the published font paths did not move — grep -o 'url([^)]*fonts[^)]*)' dist/standalone.css | sort -u | head -1 should still show a path beginning ../src/assets/fonts/
• Confirm dist/cloudfour-patterns.mjs contains no story code (grep -c stories dist/cloudfour-patterns.mjs should be 0)

---

• Refs Dependency modernization: Node 24, Vite, and Storybook 10 #2391

[changeset-bot]

🦋 Changeset detected

Latest commit: 120b284

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cloudfour/patterns	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for cloudfour-patterns ready!

Name	Link
🔨 Latest commit	120b284
🔍 Latest deploy log	https://app.netlify.com/projects/cloudfour-patterns/deploys/6a878ad83bdd4500082ec452
😎 Deploy Preview	https://deploy-preview-2405--cloudfour-patterns.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[gerardo-rodriguez]

@spaceninja Is it expected that spacing is missing above the heading?

[spaceninja]

Good catch — it's a real change, though not from the MDX conversion (the markdown around that heading is identical to main).

Storybook's docs CSS zeroes the top margin on the first heading of each level in a page, to tighten up the heading that opens it. But it matches on type rather than position (h2:first-of-type), so a mid-page section heading that happens to be the only h2 loses its spacing too. That rule is the same on production — what changed is the block above it. In Storybook 6.5 IconGallery was a flex layout with margin: 0 10px 30px 0 on each item, so the last row left 30px hanging below it. Storybook 7 rewrote it as a gap-based grid with no item margins, which removed that trailing space and left the heading sitting directly on the icons.

I scripted a check across all 84 docs pages and it affects 15 of them, so thank you for spotting it — my initial read was that Icons was the only one. The rest are mostly the Design → Tokens pages, where an h2 follows a code block, plus a few where the first h2/h3/h4 directly follows the heading above it.

Fixed in 120b284 with a one-rule override in .storybook/preview.scss that restores the margin on headings that aren't genuinely first. Pages where a <Canvas> already supplies a larger bottom margin are unaffected, since adjacent margins collapse. All 84 pages verified after the change.

[gerardo-rodriguez]

@spaceninja Is it expected that the URL no longer updates?

[spaceninja]

Sorry, I wasn't able to reproduce this — I tried the deploy preview in Firefox and the URL updated as expected on each sidebar click.

One thing that did change and might be related: Storybook 8 renamed the auto-generated docs entry, so ?path=/story/design-icons--page is now ?path=/docs/design-icons--docs. The param still tracks navigation, but older deep links won't resolve.

If it's still happening for you, let me know your Firefox version and I'll dig further.

[gerardo-rodriguez]

On any text-heavy page (Introduction is fine), confirm the body text is in the Source Sans typeface rather than a system fallback like Times or Arial

I'm seeing the following in dev tools when I inspect a heading or paragraph:

 font-family: "Nunito Sans", -apple-system, ".SFNSText-Regular", "San Francisco", BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Arial, sans-serif;

[spaceninja]

To clarify - the examples rendered with our styles should use our font. The Storybook UI does not.

[spaceninja]

Ah, apologies, I just noticed the testing instructions are wrong - they pointed you at a page entirely rendered with Storybook UI. A better example is the Sky Nav

[gerardo-rodriguez]

Seems good to me overall. But I didn't review every file. 🙃