Skip to content

Register wp-theme design tokens stylesheet #12560

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mirka wants to merge 3 commits into from
+57 −1
Closed

Register wp-theme design tokens stylesheet #12560

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e407a97
Register wp-theme stylesheet in script loader
mirka Jul 16, 2026
0f3608e
Remove wp-theme dependency from block-directory
mirka Jul 16, 2026
8b4e065
Add @ticket annotations to wp-theme style tests.
mirka Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion src/wp-includes/script-loader.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1721,6 +1721,7 @@ function wp_default_styles( $styles ) {

// Only add CONTENT styles here that should be enqueued in the iframe!
$wp_edit_blocks_dependencies = array(
'wp-theme',
'wp-base-styles',
'wp-components',
/*
Expand Down Expand Up @@ -1761,8 +1762,9 @@ function wp_default_styles( $styles ) {
'block-editor' => array( 'wp-components', 'wp-preferences' ),
'block-library' => array(),
'block-directory' => array(),
'theme' => array(),

@mukeshpanchal27 mukeshpanchal27 Jul 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why theme?

@mirka mirka Jul 17, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

@mirka mirka Jul 16, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ciampo Jul 16, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 aduth Jul 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@mirka mirka Jul 17, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

'commands' => array( 'wp-components' ),
'edit-post' => array(
'wp-components',
Expand Down Expand Up @@ -1829,6 +1831,10 @@ function wp_default_styles( $styles ) {
$path = "/wp-includes/css/dist/base-styles/admin-schemes$suffix.css";
}

if ( 'theme' === $package ) {
$path = "/wp-includes/css/dist/theme/design-tokens$suffix.css";
}

$styles->add( $handle, $path, $dependencies );
$styles->add_data( $handle, 'path', ABSPATH . $path );
}
Expand Down Expand Up @@ -1872,6 +1878,7 @@ function wp_default_styles( $styles ) {
'wp-reset-editor-styles',
'wp-editor-classic-layout-styles',
'wp-block-library-theme',
'wp-theme',
'wp-edit-blocks',
'wp-block-editor',
'wp-block-library',
Expand Down
49 changes: 49 additions & 0 deletions tests/phpunit/tests/dependencies/styles.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -557,6 +557,55 @@ public function test_block_styles_for_viewing_with_split_styles() {
);
}

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

@mukeshpanchal27 mukeshpanchal27 Jul 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* @covers ::wp_default_styles
* @ticket 65646
*
* @covers ::wp_default_styles

Add @ticket annotation in new tests

*/
public function test_wp_theme_style_is_registered() {
wp_default_styles( $GLOBALS['wp_styles'] );

$this->assertArrayHasKey( 'wp-theme', $GLOBALS['wp_styles']->registered );
$this->assertSame(
'/' . WPINC . '/css/dist/theme/design-tokens.css',
$GLOBALS['wp_styles']->registered['wp-theme']->src
);
}

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

@mukeshpanchal27 mukeshpanchal27 Jul 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* @covers ::wp_default_styles
* @ticket 65646
*
* @covers ::wp_default_styles

*/
public function test_wp_components_depends_on_wp_theme() {
wp_default_styles( $GLOBALS['wp_styles'] );

$this->assertContains(
'wp-theme',
$GLOBALS['wp_styles']->registered['wp-components']->deps
);
}

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

@mukeshpanchal27 mukeshpanchal27 Jul 17, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* @covers ::wp_default_styles
* @ticket 65646
*
* @covers ::wp_default_styles

*/
public function test_wp_edit_blocks_depends_on_wp_theme_first() {
wp_default_styles( $GLOBALS['wp_styles'] );

$deps = $GLOBALS['wp_styles']->registered['wp-edit-blocks']->deps;

$this->assertContains( 'wp-theme', $deps );
$this->assertSame( 0, array_search( 'wp-theme', $deps, true ) );
}

/**
* @ticket 58394
* @ticket 63887
Expand Down
Loading