Skip to content

perf(theme): theme/tokens no longer loads the theme builder - #12949

Draft
vjeux wants to merge 2 commits into
meta:mainfrom
vjeux:perf/theme-tokens-skip-defineTheme
Draft

vjeux wants to merge 2 commits into
meta:mainfrom
vjeux:perf/theme-tokens-skip-defineTheme

Conversation

@vjeux

@vjeux vjeux commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

User impact

An app can import only @astryxdesign/core/theme/tokens, for example to resolve token values on a server. When its build keeps whole modules, that app loads the theme builder on first load. The builder is defineTheme and the modules that only it loads, such as resolveThemeValues, themeAdaptations, localTokens and themeRegistry. With this change that app loads about 11.7 kB gzip (35 kB minified) less JavaScript. A build that removes unused code statement by statement already leaves most of it out. Its output shrinks by 1 B minified and grows by 16 B gzip.

Problem and solution fit

  • Why does the app load the builder? tokens.ts imports tokenDefaults from defineTheme.ts. A bundler that keeps a module's own code then keeps all of defineTheme.ts and what it imports.
  • Why is that code not needed? Token resolution reads only the defaults map. That map lives in tokenDefaults.ts, which imports only token data, and defineTheme.ts already re-exports it.
  • Why does it matter? First-load JavaScript delays the first interaction, and the builder runs only when an app defines a theme.

Expected behavior and authority

architecture:theme-tokens makes tokens.ts the owner of server-safe references and resolution, and keeps defineTheme.ts as the authoring aggregate. The token import tests already keep the theme-rule generator out of token resolution. This change keeps the builder out as well.

Smallest restoration

tokens.ts imports tokenDefaults from ./tokenDefaults and takes DefinedTheme and TokenName as a type-only import from ./defineTheme. No other source changes. defineTheme still exports tokenDefaults, so every caller and every resolved token stays the same.

Evidence

  • Reproduction before the change: the new theme/tokens cases fail on main. Both walks list defineTheme, resolveThemeValues, themeAdaptations, localTokens and themeRegistry.
  • Result after the change: both cases pass. Their controls still find those modules from defineTheme and from the theme entry.
  • Representative unchanged path: the theme unit tests pass, 1,945 tests in 36 files.
  • Regression test or other mutation-sensitive proof: the new cases in tokensImports.test.ts and tokensImports.dist.test.mjs.

Scope

Components: theme (tokens)

  • One defect is restored.
  • Separable contradictory or unsettled tagalongs were removed or split.
  • No new public API, visual representation, default, or interaction model is hidden under the bug-fix label.
  • Public text and artifacts contain no internal Meta context.

Testing

  • pnpm exec vitest run packages/core/src/theme/tokensImports.test.ts packages/core/src/theme/tokensImports.dist.test.mjs: 2 of 18 tests fail on main; all 18 pass with this change.
  • pnpm exec vitest run packages/core/src/theme: 1,945 tests in 36 files pass.
  • After Merge main, pnpm preflight --quick passes: review:pre, typecheck, lint, changed tests, knowledge and changesets.
  • The full pnpm preflight ran on the branch before that merge. Its review:pre, build, typecheck, lint, knowledge and changesets passed.
  • Its Node run failed 117 tests in 56 files under a load average near 45, and 50 of those failures were timeouts.
  • Run again at low load, each of those 56 files gives the same result on main and here. 54 pass on both.
  • theme-cut-short.test.mjs (4 tests) and theme-pictures-broken-words.test.mjs (1 test) fail on both sides with the same assertions.
  • Its jsdom run passed all 26,531 tests but raised one unhandled timer error from Switch/useSwitchTouch.test.ts.
  • The full jsdom run was repeated three times on main and four more times here. Two flakes show on both sides.
  • semanticFence.shared.test.tsx timed out at 30 s in 2 of 3 runs on main and in 4 of 5 runs here.
  • The useSwitchTouch timer error appeared in 1 of 3 runs on main and in 3 of 5 runs here.
  • Run alone, each of those two files passed three times on each side.
  • First-load bytes, measured locally. A one-line app, import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens', is bundled with esbuild 0.28.2 (minified, ESM, browser) against Core's built dist. Gzip is level 9.
Build main This change
Whole modules (treeShaking: false) 78,606 B, 23,865 B gzip, 31 modules 43,490 B, 12,144 B gzip, 14 modules
Tree-shaken (esbuild default) 32,252 B, 10,360 B gzip 32,251 B, 10,376 B gzip

tokens.ts imported tokenDefaults from defineTheme, the theme builder.
A build that keeps whole modules then loaded defineTheme and the 16
modules that only it loads, such as resolveThemeValues,
themeAdaptations, localTokens and themeRegistry. tokens.ts now imports
tokenDefaults from its own module and takes the defineTheme types as a
type-only import.

The token import tests get a theme/tokens case in the source walk and
in the compiled-entry walk. Each has a control that finds the builder
modules from defineTheme or from the theme entry.
@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 19, 2026 5:13pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 19, 2026
@astracat-bot

astracat-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 19, 2026, 5:12 PM UTC

@cixzhang cixzhang added ci:run A maintainer lets this outside contributor's pull request run CI (AST-030 FR17) ci:run-a11y Run the accessibility suite on this PR; write access, next push (AST-030 FR12) labels Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@cixzhang

Copy link
Copy Markdown
Contributor

/approve-spec 518b109

@astracat-bot astracat-bot Bot 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.

Approved pending CI: CI has not run on this head yet. The pull request is a draft, and it already has the ci:run label, so CI runs once it is marked ready for review.

theme/tokens.ts now reads tokenDefaults from its own module, so a tokens-only app whose build keeps whole modules no longer loads defineTheme and the modules it brings in. Resolved tokens and the public API are unchanged, and the two new boundary tests fail on main and pass on this head.

Claims and files checked

Review mode: full; reason: no-earlier-review

  • Claims
    • Title and changeset: a tokens-only app no longer loads the theme builder when its build keeps whole modules. Verified: the new source-walk and compiled-walk cases fail on main and pass here, and a whole-module bundle drops from 31 to 14 modules.
    • Changeset: token resolution reads the defaults from their own module. Verified: tokens.ts:27.
    • Changeset: every resolved token stays the same. Verified: defineTheme.ts:720 re-exports the same binding, and the theme suite passes 1,922 tests in 36 files.
    • Changeset and description: no API changes. Verified: Core's and the seven themes' API surfaces are identical with this change.
    • Description: about 11.7 kB gzip (35 kB minified) less for whole-module builds. Verified: 78,581 to 43,465 B minified and 23,846 to 12,128 B gzip, with react treated as external, which the table assumes but does not state.
    • Description: a tree-shaken build changes by 1 B less minified and 16 B more gzip. Verified within a byte (1 B less, 17 B more).
    • Description: tokens.ts imported the defaults from defineTheme.ts, which already re-exports them from a module that holds only token data. Verified: tokens.ts:25 on main, defineTheme.ts:720, tokenDefaults.ts:11-26.
    • Description: the token architecture record makes tokens.ts the server-safe resolver and defineTheme.ts the authoring aggregate. Verified.
    • Description: the existing tests already keep the theme-rule generator out of token resolution. Verified: those cases pass on main.
    • Description: no other source changes. Verified: the diff touches one source file.
    • Description: 2 of 18 tests fail on main, both list the same five modules, and all 18 pass here. Verified.
    • Description: preflight passes, and the full Node and jsdom runs show the same failures and flakes on both sides. Not reproduced (local runs, and CI has not run on this head); the verdict does not depend on them.
    • Commit message: the builder brings in 16 modules besides itself. Verified: 31 modules on main, 14 here.
  • Files
    • .changeset/theme-tokens-no-builder.md: clear.
    • packages/core/src/theme/tokens.ts: clear.
    • packages/core/src/theme/tokensImports.test.ts: clear.
    • packages/core/src/theme/tokensImports.dist.test.mjs: clear; it names the same five modules as the source test.

Automated review (maintainer link)

@cixzhang

Copy link
Copy Markdown
Contributor

/approve-spec 35c9c5f

@astracat-bot astracat-bot Bot 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.

Approved pending CI: CI has not run on this head yet. The pull request is a draft and already has the ci:run label, so CI runs once it is marked ready for review.

theme/tokens.ts now reads tokenDefaults from its own module, so a tokens-only app whose build keeps whole modules no longer loads defineTheme and the modules it brings in. The merge of main leaves the change itself untouched, resolved tokens and the public API stay the same, and the two new boundary tests pass on this head.

Claims and files checked

Review mode: carry-forward; reason: none

  • Claims
    • Title and changeset: a tokens-only app no longer loads the theme builder when its build keeps whole modules. Verified: the new source-walk and compiled-walk cases fail on main and pass here, and a whole-module bundle drops from 31 to 14 modules.
    • Changeset: token resolution reads the defaults from their own module. Verified: tokens.ts:27.
    • Changeset: every resolved token stays the same. Verified: defineTheme.ts:720 re-exports the same binding, and the theme suite passes 1,945 tests in 36 files.
    • Changeset and description: no API changes. Verified: Core's and the seven themes' API surfaces are identical with this change.
    • Description: about 11.7 kB gzip (35 kB minified) less for whole-module builds. Verified: 35,116 B minified and 11,718 B gzip less with react treated as external; the table's absolute sizes sit 25 B above that build on every row, and its differences match within 3 B.
    • Description: a tree-shaken build changes by 1 B less minified and 16 B more gzip. Verified within a byte (1 B less, 17 B more).
    • Description: tokens.ts imported the defaults from defineTheme.ts, which already re-exports them from a module that holds only token data. Verified: tokens.ts:25 on main, defineTheme.ts:720, tokenDefaults.ts:11-26.
    • Description: the token architecture record makes tokens.ts the server-safe resolver and defineTheme.ts the authoring aggregate. Verified.
    • Description: the existing tests already keep the theme-rule generator out of token resolution. Verified: those cases pass on main and here.
    • Description: no other source changes, and defineTheme still exports tokenDefaults. Verified: the diff touches one source file; defineTheme.ts:720.
    • Description: 2 of 18 tests fail on main, both walks list the same five modules, their controls still find them, and all 18 pass here. Verified.
    • Description: after the merge of main, the quick preflight passes, and the full Node and jsdom runs show the same failures and flakes on both sides. Not reproduced (local runs, and CI has not run on this head); the verdict does not depend on them.
    • Commit message: the builder brings in 16 modules besides itself. Verified: 31 modules on main, 14 here.
  • Files
    • .changeset/theme-tokens-no-builder.md: clear.
    • packages/core/src/theme/tokens.ts: clear.
    • packages/core/src/theme/tokensImports.test.ts: clear.
    • packages/core/src/theme/tokensImports.dist.test.mjs: clear; it names the same five modules as the source test.

Automated review (maintainer link)

This branch was successfully deployed

1 active deployment
Preview — 35c9c5fd Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:run A maintainer lets this outside contributor's pull request run CI (AST-030 FR17) ci:run-a11y Run the accessibility suite on this PR; write access, next push (AST-030 FR12) CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants