build(tsdown): replace Babel with tsdown across all gamut packages

[dreamwasp]

Overview

Replaces Babel with tsdown (rolldown) as the JS build for all seven publishable packages
(variance, gamut-styles, gamut, gamut-icons, gamut-patterns, gamut-illustrations,
gamut-tests), keeping tsc --emitDeclarationOnly for declarations — a hybrid build.

Declarations stay on tsc because tsdown's own bundled .d.ts produces 50× TS4023 in
downstream packages (a bundled declaration file doesn't re-export the names its dependents
need); keeping tsc also makes rolldown-plugin-dts#174 (directives leaking into .d.ts)
structurally unreachable, since declarations carry no statements to leak through.

Along the way this also fixes a live tree-shaking bug (three packages had no sideEffects
field at all — the most conservative possible value), adds strict exports maps where none
existed, and closes a correctness gap left by dropping @emotion/babel-plugin from the
production build (it stamps a target on every styled() call, which is what makes
component-selector interpolation work — one site needed it explicit, and there's now a lint
rule enforcing that going forward).

PR Checklist

• Related to designs: N/A
• Related to JIRA ticket: GMT-1741
• Version plan added/updated
• I have run this code to verify it works
• This PR includes unit tests for the code change (new eslint rule test; existing suites
  re-verified against the new build output)
• This PR includes testing instructions for the code change

Testing Instructions

1. yarn install
2. yarn build — full monorepo build via the new tsdown pipeline. Should complete cleanly for
   all 9 projects.
3. yarn test — full jest suite (1276 tests across gamut + siblings). Nothing here changes
   behaviorally; this confirms the new build didn't break anything the old one didn't.
4. yarn verify — typecheck pass, now with isolatedModules: true enforced repo-wide.
5. yarn nx run-many --target=verify-package --all — publint + attw against the real built
   packages. Should report 0 errors (warnings/suggestions about engines.node and the
   deliberate false-cjs tradeoff are expected and non-blocking).
6. node script/verify-exports.mjs — resolves every package's public surface from the repo
   root. Should print All export checks passed. with one flagged (not failing) lodash/ESM
   warning. You'll also see a wall of Node Warning: Accessing non-existent property ... inside circular dependency lines printed after the success message — that's a real,
   pre-existing circular import in gamut's Tip/shared/styles (composeVariantsUtils.ts
   ↔ styles.ts), surfaced because this script require()s the whole module graph.
   Confirmed benign (the values are only read inside function bodies, never captured at
   module-eval time, so the real values come back correct by call time) but noisy. Left as
   a follow-up rather than fixed here — either suppress it in the script or fix the actual
   circular import.
7. yarn build-storybook && npx nx run styleguide:storybook-test — full Storybook build +
   Playwright/a11y pass (493 tests). Confirms the Storybook-only alias fixes and the
   deep-import cleanups didn't break any story, including the icon galleries
   (Atoms/Icons/Mini, Atoms/Icons/Regular) and the typography-variant table
   (Typography/Text) that the new aliases specifically unblock.
8. Manual spot-check: open the BarChart story in Storybook and hover/focus a row — confirm
   the CategoryLabel underline still applies. This is the one change (the target fix) that
   nothing in the test suite can verify directly, since jest transforms src through Babel
   (which still runs @emotion/babel-plugin) and is structurally blind to a production-only
   regression here.

More info + other approaches

Results

Delivered: all seven publishable packages (variance, gamut-styles, gamut,
gamut-icons, gamut-patterns, gamut-illustrations, gamut-tests) off Babel entirely, on
a working tsdown + tsc hybrid build, verified end-to-end (yarn build/test/verify,
publint + attw on every package, a Node-resolver script, a 493-story Storybook pass —
all green from a cold cache).

Fixed, not just faster — three bugs that predate this PR and were live in production:

• Today's output isn't valid Node ESM. Babel emits export * from './core'-style
  extensionless relative imports with no exports map; Node's own resolver rejects that
  outright (ERR_MODULE_NOT_FOUND). It only ever worked because every consumer bundles. Fixed:
  real, extensioned relative imports, verified by loading the built output directly.
• Dead-code elimination was never possible on variance, gamut-styles, or gamut-tests.
  None of the three had a sideEffects field — the most conservative value there is — which
  blocks tree-shaking on the packages everything else in the ecosystem depends on. Fixed:
  sideEffects: false, verified safe (no module-level side effects in either package).
• A real regression was caught before it could ship. The first pass at this used tsdown's
  default single-bundle output; a single-component import measured 15x larger than the old
  Babel build (1.59MB vs 103KB) because nothing could be proven dead once every export shared
  one module scope. unbundle: true (tsdown emits one file per source file, same shape as
  today, still via the fast bundler) fixed it completely — 112KB, back at parity with today.
  Same fix, same order of magnitude, on gamut-icons (586KB → 73KB for a single icon import).

New automated safety net that didn't exist at all before this PR: publint + attw +
a resolver script now run in CI on every package, checking that the actual exports/main/
module/types fields resolve the way a real consumer would. This is what caught the
regression above, plus a stale files array and three missing types fields — all before
merge, with nothing in the existing test suite (which never touches built dist output at
all) capable of catching any of it.

Build speed — honest numbers, not the spike's

Per-package build is tsdown (JS) + tsc --emitDeclarationOnly (types, unchanged from
before). Measured directly on gamut (426 files, the largest package):

step	before (Babel)	after (tsdown)
JS layer alone	~4.9s	~0.6–0.9s
types (tsc, identical either way)	~10–12s	~10–12s
full package build	~15–17s	~11–13s

A consistent ~3x per-file cost tied to Emotion type density, not raw file count.

As components move off styled()'s deep generic types onto plain explicit prop
types, tsc's declaration cost per file should drop toward the gamut-icons end of that
range — and that's also the point where a genuinely fast, non-tsc declaration emitter
(anything built on TypeScript's isolatedDeclarations, e.g. a future rolldown-plugin-dts
isolated mode, oxc, or a tsgo-style checker) becomes realistic to adopt, since it needs far
fewer manual type annotations to satisfy.

Investigated and rejected for now: isolatedDeclarations. Enabling the flag doesn't make
tsc itself faster — measured directly on variance: 1.29s with the flag vs 1.51s without,
noise-level. It's a static check that qualifies code for a different, non-checking emitter;
the speed win only exists if you also swap tools. Even variance (zero Emotion) had 8
violations; gamut/gamut-styles export 100+ styled() results whose types are inferred
from Emotion's generics, not something safely hand-annotated without risking a silent type
narrowing that breaks a consumer relying on the wider inferred type. Worth revisiting once the
static-styles migration above has simplified enough of the exported surface to make that
annotation burden small and low-risk — not before.

Build migration

• packages/{variance,gamut-styles,gamut,gamut-icons,gamut-patterns,gamut-illustrations,gamut-tests}/tsdown.config.ts
  — new tsdown config per package. dts: false (tsc still owns declarations), unbundle: true
  (mirrors src/ file-by-file instead of concatenating into one file — a single bundled
  dist/index.mjs measured 15× larger for a single-component import, since nothing can be
  proven dead once everything shares one module scope), clean: false (declarations share
  dist/ with tsc's output).
• packages/*/project.json — build target commands swap babel ./src --out-dir ./dist for
  tsdown, keeping the existing tsc --emitDeclarationOnly / cpy steps around it. SVGR
  codegen steps (icon/pattern generation) are untouched.
• packages/*/package.json — real exports maps added (gamut, gamut-styles, and
  gamut-illustrations previously had no types field at all). main/module point at the
  real filenames tsdown produces (dist/index.js for CJS, dist/index.mjs for ESM — not
  .cjs/.mjs as an earlier draft assumed, since none of these packages set "type": "module").
  gamut-styles' files array dropped four entries (core, utils, core.scss, utils.scss)
  that don't exist on disk.
• tsconfig.base.json — isolatedModules: true, ratcheting against the type-only re-export
  debt rolldown can't see through (verified 0 errors across every affected package before
  enabling).
• package.json — adds tsdown, publint, @arethetypeswrong/cli as root devDependencies,
  all version-pinned exactly (not ^) — each is pre-1.0, and an unpinned minor bump could
  silently change tsdown's build output or add a new publint/attw check that flips CI red.
• Considered, tested, and rejected: setting "type": "module" (or "commonjs") on any of the
  seven package.jsons to remove the "Node may attempt to detect the package type" perf-hint
  publint suggests. Every package's root directory holds both an ESM tsdown.config.ts
  (import { defineConfig } from 'tsdown') and a CJS babel.config.js
  (module.exports = {...}, still needed for jest/Storybook). Node's "type" field applies to
  every extensionless .js/.ts file in that directory tree — setting either value breaks one
  of the two config files' loading. Verified directly: "type": "commonjs" broke tsdown's own
  config loading (Cannot use import statement outside a module); "type": "module" broke
  every jest suite the same way in the other direction (ReferenceError: module is not defined in ES module scope on babel.config.js). No "type" field is the only value compatible with
  both toolchains coexisting — and it costs nothing for real consumers, since the shipped
  dist/index.js / dist/index.mjs extensions already disambiguate module kind regardless of
  the package's own "type".

Tree-shaking fix

• variance, gamut-styles, gamut-tests — sideEffects: false added; none had the field at
  all, which is the most conservative possible value and blocked dead-code elimination on the
  packages everything else depends on.
• gamut's existing sideEffects glob reduced to ["**/*.css", "**/*.scss"] — the two
  dist/**/[A-Z]**/*.js globs (added in #932, a real 2020 fix for Emotion-10-era style-order
  drift) matched nothing once unbundle: true changed dist's shape. Re-verified the 2020 bug
  doesn't reproduce under Emotion 11: a 493-story Emotion-CSS diff across the glob on/off came
  back byte-identical, under real tree-shaking (not just structurally unreachable, actually
  exercised).

Emotion target correctness

• packages/gamut/src/BarChart/BarRow/elements.tsx — @emotion/babel-plugin stamps a target
  on every styled() call automatically; that's what makes the ${CategoryLabel}
  component-selector interpolation work. The plugin doesn't run through tsdown, so this is the
  one site (repo-wide) that needed an explicit target to avoid a silent .undefined fallback
  in production.
• packages/eslint-plugin-gamut/src/require-styled-target-for-selector.ts (new) — flags any
  future ${Component} style-selector interpolation whose styled() call has no explicit
  target. Added to recommended.ts. Verified zero violations across all five component
  packages' real source (--no-inline-config, ignoring existing disable comments).

Storybook fixes

packages/styleguide/.storybook/main.ts already aliases every bare @skillsoft/gamut*
specifier straight to that package's ../src — Storybook has never actually consumed any
package's built dist, independent of this migration. Adding strict exports maps broke the
handful of imports that carry an extra /src path segment and so don't match that alias:

• 7 files (GamutTheme.ts, GamutThemeProvider.tsx, TokenTable/elements.tsx,
  ColorScale.tsx, Layout.mdx, Alerts.mdx) were importing symbols that are already exported
  at the package root — fixed by dropping the /src suffix.
• 4 new Storybook-only webpack aliases added for genuinely internal groupings with no public
  equivalent (icon categories, raw typography-variant metadata, the full system-props registry)
  — each already carried an acknowledged // eslint-disable-next-line @skillsoft/gamut/import-paths
  comment, pre-existing debt this surfaced rather than introduced. Keeps every package's
  exports map an honest description of its published surface instead of growing it to fit
  docs tooling.

Packaging verification

Why both tools, and why now: before this branch, none of these seven
packages had an exports map or dual ESM+CJS output — there was nothing for either tool to
meaningfully check. This migration is exactly what introduces the class of bug both exist to
catch, and nothing else in the repo's own tooling catches it — tsc only validates imports
inside the compile, not what a downstream require()/import would resolve to, and jest
transforms src directly through Babel, never touching dist. publint and attw check two
different, non-overlapping things:

• publint checks the packaging contract: do main/module/types/exports/files in
  package.json actually match what's on disk? It caught real bugs in this migration before
  attw even ran — gamut-styles' files array listed four entries (core, utils,
  core.scss, utils.scss) that don't exist on disk, and gamut, gamut-styles, and
  gamut-illustrations had no types field at all.
• attw checks that the type declarations match the JS a consumer actually gets, across the
  different resolution strategies a consumer's own tsconfig might use (node10, node16 from
  CJS, node16 from ESM, bundler). It's what surfaced the false-cjs finding below —
  publint only flags that as an ambiguity warning, attw treats it as an outright resolution
  failure under the node16-from-ESM profile.

Since this repo currently has zero real consumers to catch a broken exports map in the wild
(see the "not published" note further down), these two are the substitute for that missing
feedback loop.

• packages/*/project.json — new verify-package target (publint . +
  attw --pack . --ignore-rules false-cjs) on every publishable package.
  false-cjs is suppressed deliberately: it flags the hybrid's one accepted tradeoff (a single
  shared dist/index.d.ts serving both import/require conditions), which only affects
  moduleResolution: node16/nodenext consumers importing via ESM — this repo's own
  tsconfig.base.json uses legacy moduleResolution: "node", and the bundler profile (the real
  consumption path) is unaffected.
• script/verify-exports.mjs (new) — resolves every package's exports map from the repo root
  the way a real consumer would: asserts the root subpath resolves and loads via both
  require() and import(), and asserts old deep dist/* paths are correctly blocked with
  ERR_PACKAGE_PATH_NOT_EXPORTED. Flags (doesn't fail on) one pre-existing gap: variance
  imports lodash via extensionless deep subpaths (lodash/get), which lodash's own lack of an
  exports map makes unresolvable under native Node ESM — bundlers handle it fine. Scoped out
  as a fast-follow rather than blocking here.
• .github/workflows/test.yml — wires verify-package and verify-exports.mjs into the
  storybook-test job, ahead of the Storybook build.

Babel config cleanup

Babel is still load-bearing for two things this PR doesn't touch — babel-jest (every
package's jest.config.ts) and Storybook's Vite pipeline (packages/styleguide/.storybook/main.ts,
which adds @vitejs/plugin-react with @emotion/babel-plugin configured, since Storybook's
react-vite framework transpiles JSX with esbuild by default and doesn't add this itself).
With the library build off Babel entirely, the seven per-package babel.config.js files were
carrying duplicated dead weight: each declared the same presets array byte-for-byte,
differing only in whether @emotion/babel-plugin was added.

• babel.defaults.js — now also exports the shared presets array (previously duplicated
  in all seven packages/*/babel.config.js). Verified Babel's extends merges arrays rather
  than overriding them (tested directly via @babel/core.transformFileSync), so moving the
  array up doesn't change behavior for any package.
• packages/*/babel.config.js (all seven) — now just { extends: '../../babel.defaults.js' }
  plus, for the five packages that need it (variance, gamut-styles, gamut,
  gamut-illustrations, gamut-tests), the @emotion/babel-plugin block. gamut-icons and
  gamut-patterns need neither Emotion nor any other override.
• packages/styleguide/.babelrc.json — deleted. Storybook's Vite migration means nothing
  reads it anymore; confirmed orphaned before removing it.
• Verified via full yarn build/yarn test/yarn verify and a no-cache jest run (117
  suites, 1,563 tests) — all unchanged and passing, plus a direct
  @babel/core.transformFileSync check confirming both the JSX/TS transform and the
  Emotion target/label stamping still work identically per package.

A follow-up spike for removing Storybook's remaining Babel dependency entirely (swap
@vitejs/plugin-react for @vitejs/plugin-react-swc + @swc/plugin-emotion) is to be completed
separately: GMT-1795.

[aresnik11]

Running yarn build gives me a failure for building variance

Error: Failed to import module "unrun". Please ensure it is installed.

This is what the robot said:

Root cause: The build packages (gamut, gamut-styles, variance, etc.) build with tsdown, and each has a TypeScript config file (tsdown.config.ts). To load a .ts config, tsdown needs a TypeScript loader. Its configLoader: "auto" logic is:

const nativeTS = process.features.typescript || process.versions.deno;
const autoLoader = isBun || nativeTS && isSupported ? "native" : "unrun";

This machine is on Node v22.14.0, where process.features.typescript is false (native TS type-stripping was only unflagged in Node 22.18.0). Since it's not Bun/Deno and native TS isn't available, tsdown falls back to the "unrun" loader — an optional peer dependency that isn't installed. Hence Failed to import module "unrun".

[aresnik11]

i got rid of this Video, it was causing me issues so i just rendered the animating RadialProgress

[aresnik11]

this is a real package? lol