Register wp-theme design tokens stylesheet by mirka · Pull Request #12560 · WordPress/wordpress-develop

mirka · 2026-07-16T15:32:43Z

Register the wp-theme design tokens stylesheet in Core so --wpds-* custom properties are available without the Gutenberg plugin.

Trac ticket: https://core.trac.wordpress.org/ticket/65646

Changes

Register wp-theme in wp_default_styles() at /wp-includes/css/dist/theme/design-tokens$suffix.css.
Add wp-theme first in $wp_edit_blocks_dependencies for the editor iframe.
Add wp-theme as a dependency of wp-components.
Add wp-theme to the RTL styles list (mostly a formality, since it doesn't really have separate RTL styles).
Add PHPUnit coverage for registration and dependency wiring.

We also try to match this Core style dependency behavior as closely as possible with some tweaks in WordPress/gutenberg#80362.

Test plan

PHPUnit: test_wp_theme_style_is_registered, test_wp_components_depends_on_wp_theme, test_wp_edit_blocks_depends_on_wp_theme_first
Local admin and block editor without Gutenberg plugin: should be loading the design-tokens stylesheet
Verified with SCRIPT_DEBUG on and off

Use of AI Tools

AI assistance: Yes
Tool(s): Cursor
Used for: Implementation exploration, dependency analysis, test scaffolding, and PR description drafting; changes were reviewed and tested locally by me.

github-actions · 2026-07-16T15:36:09Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

mirka · 2026-07-16T16:19:52Z

+		'theme'                => array(),
 		'base-styles'          => array(),
-		'components'           => array(),
+		'components'           => array( 'wp-theme' ),


Technically, any stylesheet that uses design tokens directly should have wp-theme declared as a dependency. But I'm not sure how realistic that expectation is, given that more and more packages on the Gutenberg side will increasingly start to do so. Not many people even know about this script-loader mechanism, and that it differs from the client-assets mechanism in the Gutenberg plugin.

In real life, I've found that the minimal setup proposed in this PR basically covers everything, given the prevalence of wp-components. This may someday cease to be true, if the migration to @wordpress/ui progresses and the wp-components dependency is dropped from certain package styles. But that's unlikely to happen very soon.

Mhh, that's a true concern, but with a low probability of being an actual issue.

In the currently pinned Gutenberg build, wp-block-directory is the only Core-registered package stylesheet I found that consumes --wpds-* tokens without reaching wp-theme through either wp-components or wp-edit-blocks.

Its generated CSS currently includes token fallbacks, and Core enqueues it in the block-editor context where wp-components is already present. A direct wp-theme dependency would be cleaner ownership, but the current narrower graph is not a correctness bug today. This should be revisited when a package drops its wp-components style dependency during the @wordpress/ui migration.

I feel like @wordpress/build should have something similar to what it does with its automated *.asset.php dependency resolution for JavaScript dependencies, having some equivalent for stylesheets so we can manage dependencies dynamically rather than making this something that anyone has to think about.

Obviously not something we can do right away, but maybe to consider in the future to mitigate the impact.

having some equivalent for stylesheets so we can manage dependencies dynamically

wp-build does have a basic form of style dep inference actually. It won't quite work with wp-theme, mostly because a consumer has no need to declare @wordpress/theme as a script dependency if they're just using the tokens in their stylesheets.

github-actions · 2026-07-16T16:31:38Z

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.

Core Committers: Use this line as a base for the props when committing in SVN:

Props 0mirka00, mciampini, aduth, mukesh27.

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

ciampo · 2026-07-16T16:47:56Z

+		'theme'                => array(),
 		'base-styles'          => array(),
-		'components'           => array(),
+		'components'           => array( 'wp-theme' ),


Mhh, that's a true concern, but with a low probability of being an actual issue.

In the currently pinned Gutenberg build, wp-block-directory is the only Core-registered package stylesheet I found that consumes --wpds-* tokens without reaching wp-theme through either wp-components or wp-edit-blocks.

Its generated CSS currently includes token fallbacks, and Core enqueues it in the block-editor context where wp-components is already present. A direct wp-theme dependency would be cleaner ownership, but the current narrower graph is not a correctness bug today. This should be revisited when a package drops its wp-components style dependency during the @wordpress/ui migration.

mukeshpanchal27 · 2026-07-17T04:21:27Z

 		'block-editor'         => array( 'wp-components', 'wp-preferences' ),
 		'block-library'        => array(),
 		'block-directory'      => array(),
+		'theme'                => array(),


Why theme?

The package name where the stylesheet originates is @wordpress/theme.

mukeshpanchal27 · 2026-07-17T04:22:18Z

+	/**
+	 * Tests that the design tokens stylesheet is registered in core.
+	 *
+	 * @covers ::wp_default_styles


Suggested change

* @covers ::wp_default_styles

* @ticket 65646

*

* @covers ::wp_default_styles

Add @ticket annotation in new tests

mukeshpanchal27 · 2026-07-17T04:22:37Z

+	/**
+	 * Tests that wp-components depends on wp-theme so tokens load before component styles.
+	 *
+	 * @covers ::wp_default_styles


Suggested change

* @covers ::wp_default_styles

* @ticket 65646

*

* @covers ::wp_default_styles

mukeshpanchal27 · 2026-07-17T04:23:11Z

+	/**
+	 * Tests that wp-edit-blocks loads design tokens before other editor styles.
+	 *
+	 * @covers ::wp_default_styles


Suggested change

* @covers ::wp_default_styles

* @ticket 65646

*

* @covers ::wp_default_styles

Register the wp-theme stylesheet in the script loader so design tokens are available to wp-components and the block editor dependency chain. Developed in: #12560 Reviewed by aduth, ciampo, mukesh27. Fixes #65646. git-svn-id: https://develop.svn.wordpress.org/trunk@62767 602fd350-edb4-49c9-b593-d223f7449a82

github-actions · 2026-07-17T09:09:15Z

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 62767
GitHub commit: 81b2b5b

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.

Register the wp-theme stylesheet in the script loader so design tokens are available to wp-components and the block editor dependency chain. Developed in: WordPress/wordpress-develop#12560 Reviewed by aduth, ciampo, mukesh27. Fixes #65646. Built from https://develop.svn.wordpress.org/trunk@62767 git-svn-id: http://core.svn.wordpress.org/trunk@62051 1a063a9b-81f0-0310-95a4-ce76da25c4cd

Register wp-theme stylesheet in script loader

e407a97

mirka self-assigned this Jul 16, 2026

Remove wp-theme dependency from block-directory

0f3608e

mirka added the bug label Jul 16, 2026

mirka commented Jul 16, 2026

View reviewed changes

mirka mentioned this pull request Jul 16, 2026

Add wp-theme as a style dependency of wp-components WordPress/gutenberg#80362

Merged

mirka marked this pull request as ready for review July 16, 2026 16:31

mirka requested review from aduth and ciampo July 16, 2026 16:32

ciampo approved these changes Jul 16, 2026

View reviewed changes

mukeshpanchal27 reviewed Jul 17, 2026

View reviewed changes

Add @ticket annotations to wp-theme style tests.

8b4e065

github-actions Bot closed this Jul 17, 2026

Uh oh!

Conversation

mirka commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Test plan

Use of AI Tools

Uh oh!

github-actions Bot commented Jul 16, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mirka commented Jul 16, 2026 •

edited

Loading

github-actions Bot commented Jul 16, 2026 •

edited

Loading