Register wp-theme design tokens stylesheet

[mirka]

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]

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]

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.

[ciampo]

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.

[aduth]

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.

[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.

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

Props 0mirka00.

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

[ciampo]

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.