Theme: Provide design-system token defaults without a runtime <ThemeProvider>

[ciampo]

Addresses B3 from #77462.

Note

An earlier revision also included a per-instance <style>-emission optimization (B2) and a crossesPortalBoundary prop. Both were dropped after benchmarking showed a negligible, unmeasurable real-world gain against meaningful added complexity (see discussion below). This PR is now delivery-model only.

What?

The design-system tokens ship as a prebuilt stylesheet that's always present where components render, and the legacy --wp-components-* aliases resolve to those tokens without a runtime <ThemeProvider>.

Why?

Components consuming --wpds-* (and the legacy --wp-components-*) need the token :root block to exist where they render — on plain admin pages and inside the editor iframe, where no <ThemeProvider> wraps them. Previously those defaults only appeared once a provider emitted them at runtime.

How?

• Stylesheet delivery — a new wp-theme PHP handle ships the prebuilt design-tokens.css on every admin page and inside the editor iframe, so the :root --wpds-* block is always present (wp-base-styles depends on it).
• Legacy fallbacks — the --wp-components-* fallbacks point directly at the design-system tokens (theme-variables.scss, mirrored in colors-values.js), so components get sensible defaults from the prebuilt stylesheet without a provider.
• Docs — document the delivery model (static stylesheet + <ThemeProvider>), the isRoot prop, and using <ThemeProvider> across documents (iframes and other portals).

No-regression notes

The --wp-components-* fallbacks now end in the design-system tokens rather than hard-coded values:

• Build-plugin consumers (postcss-ds-token-fallbacks, esbuild, Vite): no regression — --wpds-* references carry a build-time fallback ending in the brand default.
• --wp-components-* without a provider: covered — the fallbacks in theme-variables.scss (and their colors-values.js mirror) resolve to --wpds-* defaults from the prebuilt stylesheet.
• Editor iframe (<StyleProvider document={iframeDocument}> + <ThemeProvider>): wp-theme is enqueued inside the iframe, so --wpds-* are defined at the iframe :root.

Testing Instructions

1. Admin page — load any wp-admin screen and confirm the wp-theme design-tokens.css stylesheet is enqueued (before wp-base-styles), defining the --wpds-* block at :root.
2. Editor iframe — open the post editor; wp-theme loads inside the content iframe, --wpds-* resolve at the iframe :root, and components pick up the accent through their var( --wp-components-color-accent, var( --wp-admin-theme-color, #3858e9 ) ) chain. (--wp-components-color-accent is an override hook — intentionally undefined unless a provider sets it.)
3. Components without a provider — render a component that uses a legacy --wp-components-* color with no surrounding <ThemeProvider>; it resolves to the design-system token default from the prebuilt stylesheet (never empty).

Automated checks

• npx tsc --build packages/theme/tsconfig.json packages/ui/tsconfig.json — clean.
• ESLint / Stylelint on changed files — clean.
• npm run test:unit -- packages/theme packages/components/src/card packages/components/src/color-palette — passes, snapshots intact.
• npm i && npm run build — clean, produces build/styles/theme/design-tokens.css (+ .min + -rtl).

Testing Instructions for Keyboard

N/A — no UI changes.

Screenshots or screencast

N/A.

Use of AI Tools

This PR was prepared with the assistance of an AI coding assistant; all code, prebuilt CSS, and PR copy have been reviewed by the author before submission.

[github-actions]

Size Change: +10.5 kB (+0.12%)

Total Size: 8.6 MB

📦 View Changed

Filename	Size	Change
build/scripts/components/index.min.js	264 kB	+160 B (+0.06%)
build/styles/components/style-rtl.css	18.2 kB	+85 B (+0.47%)
build/styles/components/style-rtl.min.css	15.1 kB	+72 B (+0.48%)
build/styles/components/style.css	18.2 kB	+93 B (+0.51%)
build/styles/components/style.min.css	15.1 kB	+73 B (+0.48%)
build/styles/theme/design-tokens-rtl.css	3.39 kB	+3.39 kB (new file)	🆕
build/styles/theme/design-tokens-rtl.min.css	1.62 kB	+1.62 kB (new file)	🆕
build/styles/theme/design-tokens.css	3.39 kB	+3.39 kB (new file)	🆕
build/styles/theme/design-tokens.min.css	1.62 kB	+1.62 kB (new file)	🆕

_{compressed-size-action}

[mirka]

This makes sense overall. The one thing I want to highlight is the iframe case, which is perhaps a separate issue, but noting in case it affects the strategy taken in this PR.

Haven't actually verified in runtime, but I think:

// This didn't work on trunk to begin with
<ThemeProvider>
  <StyleProvider document={ iframeDocument }>
    // components here
  </StyleProvider>
</ThemeProvider>

// This used to work on trunk, but not anymore
<StyleProvider document={ iframeDocument }>
  <ThemeProvider>
    // components here
  </ThemeProvider>
</StyleProvider>

For example, the canvas iframe gets it's wp-components stylesheet like this:

gutenberg/lib/client-assets.php

Lines 181 to 192 in 834f7d2

	// Only add CONTENT styles here that should be enqueued in the iframe!
	$wp_edit_blocks_dependencies = array(
	'wp-components',
	// This need to be added before the block library styles,
	// The block library styles override the "reset" styles.
	'wp-reset-editor-styles',
	'wp-block-library',
	// Until #37466, we can't specifically add them as editor styles yet,
	// so we must hard-code it here as a dependency.
	'wp-block-editor-content',
	'wp-base-styles',
	);

We may want to decide whether to make design-tokens.css enqueuable with a wp- handle, or maybe consider whether it's possible to drop the design-tokens stylesheet and just rely on build time fallbacks, even for wp-components-color- variables.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[ciampo]

@mirka those are very good points. I considered a few options (leveraging the isRoot prop to emit the styles, checking the ownerDocument and comparing it to the parent ThemeProvider's equivalent to detect cross-frame boundaries, relying on runtime-generation only, ...), and I think that enqueuing the prebuilt styles is the best option:

In short, the idea is: static for defaults, runtime for diffs. It allows us to have the correct styles loaded pre-paint (no FUOC), it works for non-react (PHP) surfaces, it keeps the bundle size low (the alternative was to inline ~10kb of CSS via JavaScript), it caches better.

This is the first time I'm working on the PHP + stylesheets side of things, so please review that part with extra caution 😅 Also, I'll need some advice in understanding if and how to sync this with core.

[aduth]

Every one of those wrappers was running ramp computation and inserting <style> even when nothing had been customized.

This is largely memoized, right? Though I agree in general it feels more wasteful than it ought to be in a case where we're not customizing anything. But the alternative seems to be adding a lot of complexity that affects downstream usage.

[ciampo]

@aduth

This is largely memoized, right? Though I agree in general it feels more wasteful than it ought to be in a case where we're not customizing anything.

Yes, buildBgRamp / buildAccentRamp results are memoized.

What still fires per <ThemeProvider> mount is the colorTokensCSS flattening + the Object.fromEntries CSS-properties dictionary + React's reconciliation of the <style> node, on every wrapped portal. That's the bit this PR actually skips. I updated the PR description accordingly.

But the alternative seems to be adding a lot of complexity that affects downstream usage.

Yeah, this is why the change is internal to the hook + the truthy themeProviderStyles? check that already existed in theme-provider.tsx. The downstream API should not change

[ciampo]

While testing, I noticed a regression introduced by this PR in portalled overlays: these overlays use <ThemeProvider /> without props, which (with the changes from this PR) doesn't emit any CSS, and this causes the theme styles not to inherit to the portal as expected; the overlay would fall back to the default colors instead of the surrounding theme. The theme forwarding only kept working for root-level theming, which the browser propagates everywhere anyway, and this was masking the bug until I did some deeper final testing.

To fix it, I added a new crossesPortalBoundary prop on <ThemeProvider> (that forces the emission of the theme CSS), and applied it to all the @wordpress/ui overlay popups:

• Root-level theming is unaffected;
• Overlays now re-emit only when there's an actual non-default in-scope theme to carry across the portal;
• Unthemed overlays still emit nothing.

Added unit tests covering the behavior.

@mirka I'll wait for you to take a final look here, since this is a substantial addition to the PR

[mirka]

Reflecting on the overall shape of this, I want to check whether you share an impression I'm forming on the cost/benefit.

The delivery-model part (wp-theme stylesheet + pointing the legacy --wp-components-* fallbacks at the design system tokens) feels clearly worth it on its own. It fixes the iframe case and gives us sensible defaults before paint, and in non-React surfaces.

The skip optimization is the part I'm less sure about. The win looks fairly modest since the ramp computation was already memoized, and in exchange it adds real complexity: useThemeProviderStyles now juggles multiple baselines, semantic color comparisons, and edge cases like nested reset-to-default, plus a public crossesPortalBoundary prop that every overlay has to remember to set. That's a fair bit of permanent cognitive load. Do you have a sense of how much it would actually affect performance in practice?

If it's hard to measure, would it make sense to land the delivery changes on their own and revisit the optimization separately? Curious whether that matches your read.

[ciampo]

@mirka I'm glad you asked.

I had the same gut feeling, but didn't want to bias your judgment.

The gains in complexity don't feel like they currently offset the runtime performance improvements:

• As you mentioned, color ramp computation is already memoized, meaning that the remaining cost is mostly flattening + style reconciliation;
• There are few instances of ThemeProvider that would benefit from the optimization; most instances would need to emit styles anyway

I will simplify the PR and remove this optimization (including the crossesPortalBoundary prop). I don't think we should plan on landing it anytime soon; we should consider doing it only if runtime performance becomes a priority, and if we can find real meaningful gains in doing so.

[mirka]

Good that we're aligned here 👍