@wordpress/theme: overall API and architecture assessment

[ciampo]

Stabilization review of @wordpress/theme, aggregating the original assessment with a fresh validation pass against the current source (v0.13.0). Items shipped since the first pass are listed as done.

Done

• I4 — Refactor color-space registration to avoid module-level side effects (#77653).
• A6 (parsing) — Throw a clear error when the seed color is unparseable (#77653).
• T-M1 — Add --wpds-motion-duration-* and --wpds-motion-easing-* tokens (#76097).

Bugs

• B3 — Static legacy overrides can move out of the provider. legacyWpComponentsOverridesCSS contains only var(...) references; emit it once at :root in the prebuilt CSS. legacyWpAdminThemeOverridesCSS should only be emitted when color.primary is user-provided (WP Core already provides the defaults). Theme: Provide design-system token defaults without a runtime <ThemeProvider> #78664
• B4 — Deduplicate addFallbackToVar between postcss-plugins/add-fallback-to-var.ts and postcss-plugins/ds-token-fallbacks.mjs. @wordpress/theme: deduplicate addFallbackToVar helper #78666

API design

• A1 + A2 — Make ThemeProvider a public runtime export. Drop the type-only re-export from index.ts, remove ThemeProvider from privateApis, and migrate consumers in packages/boot and packages/ui/**/popup.tsx off unlock( themePrivateApis ).ThemeProvider. useThemeProviderStyles can remain private. Theme: Promote ThemeProvider to stable API #78958
• A5 — Asymmetric tone coverage: caution only has surface* / fgSurface* entries while other status tones have stroke* entries. Either add --wpds-color-stroke-surface-caution(-strong) or document the intentional asymmetry. Theme: Add stroke-surface tokens for the caution tone #79198
• A6 (contract) — Tighten the documented input contract for color.primary / color.bg (currently "hex, rgb(...), or CSS color keyword") to match the runtime, or relax the docs. Today the runtime accepts anything parseable in sRGB. Theme: Enforce sRGB seed-color input contract for ThemeProvider #79148
• A7 — Review React peer dep range (react: ^18.0.0) for React 19 compatibility before stabilizing. (Update: @wordpress/theme: overall API and architecture assessment #77462 (comment))
• ThemeProvider: Rename color.bg to color.background theme/ThemeProvider: rename color.bg prop to color.background #79007

Architecture and implementation

• I2 — Set custom properties via inline style on the wrapper instead of injecting a per-instance <style> element. Removes the doubled-class specificity hack, removes the <style> element in the common case, and removes one DOM node per provider. For isRoot, write to document.documentElement.style in a useLayoutEffect with cleanup — no need for :root:has(...). Theme: apply ThemeProvider styles inline (I2) #78678
• I3 — Don't serialize data-wpds-root-provider=\"false\" on every non-root provider. Use data-wpds-root-provider={ isRoot || undefined } (or drop the attribute altogether after I2). Theme: Skip serializing data-wpds-root-provider="false" on non-root providers #79253
• I5 — Document the memoization contract for getCachedBgRamp / getCachedAccentRamp. buildAccentRamp(seed, bgRamp) keys on both arguments and relies on the upstream bgRamp memo to keep references stable. Worth a comment near the cache declarations. Theme: Document ramp memoization contract #79459

Testing

• T1 — Add tests for ThemeProvider / useThemeProviderStyles: defaults, inheritance for color / cursor / density (after B1), nested providers, and the isRoot selector. Theme: Add tests for ThemeProvider and useThemeProviderStyles #79126
• T2 — Switch the stylelint plugin tests from child_process.exec to the stylelint Node API for speed and reliability. Theme: Run stylelint plugin tests via the Node API #79199
• T3 — Add a drift test asserting src/prebuilt/css/design-tokens.css matches what the build would produce, to catch stale generated files. (Update: Already exists as of Theme: Ensure build artifacts are synced in version control #73894)
• Improve module loading (see conversation) Automated Testing: Add babel-plugin-transform-import-meta to emulate import.meta.dirname #79362

Tokens

Naming and structure:

• T-N1 — Drop --wpds-dimension-base from the public surface (or keep it private). It is a primitive and shouldn't be exposed (see earlier discussion).
  • Partially started with Components, DataViews: Adopt --wpds-dimension-size-* tokens #79093
  • Completed in Theme: Drop --wpds-dimension-base from the public token surface #79254
• T-N3 — Rename --wpds-color-stroke-focus-brand → --wpds-color-stroke-focus. Drop the -brand segment unless other focus variants are introduced (breaking). Theme: Rename --wpds-color-stroke-focus-brand token to --wpds-color-stroke-focus #79125
• T-M5 — Add missing disabled variants for brand and error backgrounds/strokes (e.g. stroke-interactive-brand-disabled, bg-interactive-brand-strong-disabled) for parity with neutral. Theme: Add disabled variants for brand and error interactive color tokens #79124
• Rename bg to background and fg to foreground in tokens theme: rename bg/fg design token groups to background/foreground #79098
• Theme: Some color token values that should differ do not #77153

Values and content:

• T-X3 — Stabilize density (how it works, documentation) or remove it for now (@wordpress/theme: approach to dimension tokens and density #74556) — Theme: drop density support from @wordpress/theme #78741

Priorities

• Block stabilization: B1, B2, B5, A1+A2.
• High priority: A3, A8, B3, B4, I2, I3, T-N1, T-N3.
• Medium: T1, T2, A5, A6, A7, I5, T-M5, T-M7.
• Low / token cleanup: T-D1, T-D4, T-V1, T-V4, T-X3, T3.

---

Original detailed assessment (April 2026)

The first iteration of this review lives in the issue's revision history and discussion thread above. It contained additional commentary on items that have since been resolved (color-space registration, motion tokens, seed parsing) plus lower-priority token-level observations not repeated here.

[ciampo]

cc @WordPress/gutenberg-components — I dumped an early iteration of an AI-assisted assessment of the package.

We can refine and later work on follow-ups as needed.

[aduth]

There's some good stuff in there, but most crucially I don't really see anything about the public API as it exists today that would create pause to stabilizing ThemeProvider itself as a public API.

For the tokens, one big question for me is if we want to drop --wpds-dimension-base. To me, this feels like a primitive token that should be excluded in the same way we exclude primitive color tokens.

I4. Alternative to side-effect color-space registration

Coincidentally I arrived at this independently in #77653 😄

[ciampo]

I don't really see anything about the public API as it exists today that would create pause to stabilizing ThemeProvider itself as a public API.

@aduth correct; from this initial round, at least, nothing necessarily about ThemeProvider. At most about the DS token themselves.

one big question for me is if we want to drop --wpds-dimension-base. To me, this feels like a primitive token that should be excluded in the same way we exclude primitive color tokens.

I think so, too — probably we can do this as soon as we feel like we've added a comprehensive set of dimension tokens (we're currently still missing component sizing, not sure if there's more to add?")