Improve CSS setup instructions in package readmes by mirka · Pull Request #76975 · WordPress/gutenberg

mirka · 2026-04-01T21:08:59Z

What?

Adds a Set up section to the readmes for @wordpress/admin-ui, @wordpress/components, @wordpress/dataviews, and @wordpress/ui, covering stylesheet dependencies for WordPress plugins and for apps outside WordPress.

Why?

These packages depend on CSS from themselves and/or other packages. Instructions were split across sections or easy to miss, and non‑WordPress setups did not always spell out install steps, import order, RTL paths, or which wp_enqueue_style handles to depend on.

How?

Within WordPress: Document registering the right stylesheet handles as dependencies of the consumer’s stylesheet (with a link to wp_enqueue_style).
Outside WordPress: Document npm install where needed and import examples for @wordpress/theme/design-tokens.css and @wordpress/components/build-style/style.css, plus RTL paths for components CSS where applicable.
@wordpress/ui: Clarify that WordPress loads styles for you; outside WordPress, recommend design tokens for full theming and add a short note about isolation: isolate on the layout root for portaled popovers.

Testing Instructions

See that the instructions are correct and make sense.

Use of AI Tools

Composer 2 was used to draft this PR description.

mirka · 2026-04-01T21:52:30Z

packages/dataviews/README.md

+
+### Within WordPress
+
+To ensure proper load order, add the `wp-components` stylesheet as a dependency of your plugin's stylesheet. See [wp_enqueue_style documentation](https://developer.wordpress.org/reference/functions/wp_enqueue_style/#parameters) for how to specify dependencies.


@wordpress/dataviews and @wordpress/admin-ui don't have a stylesheet handle, so there's currently no reliable way for a third-party WP plugin to load the package styles without potentially loading duplicate or conflicting styles on a given route. (If something else is loading the same package styles on the same route.)

Maybe that's fine, but mentioning here for completeness (cc @oandregal).

github-actions · 2026-04-01T21:52:48Z

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

github-actions · 2026-04-01T21:56:10Z

Flaky tests detected in b8eb232.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/23949739516
📝 Reported issues:

[Flaky Test] Save flow should work as expected #36480 in /test/e2e/specs/editor/various/multi-entity-saving.spec.js
[Flaky Test] post title and content are editable and blocks can be inserted #76524 in /test/e2e/specs/editor/various/post-content-focus-mode.spec.js
[Flaky Test] should move focus back to the Publish panel toggle button when canceling #76179 in /test/e2e/specs/editor/various/publish-panel.spec.js
[Flaky Test] should paginate #69568 in /test/e2e/specs/site-editor/user-global-styles-revisions.spec.js
[Flaky Test] should show correct homepage actions based on current homepage or posts page #68892 in /test/e2e/specs/site-editor/homepage-settings.spec.js

aduth

Some minor comments, but LGTM overall 👍

aduth · 2026-04-02T17:53:24Z

packages/admin-ui/README.md

 npm install @wordpress/admin-ui --save
 ```

+## Set up


Super nit: But I kept wondering if this should be "setup" or "set up", but in turn it made me think it's not a very common heading I see in READMEs, compared to something like "Getting started", "Usage", maybe "Setup instructions", etc.

Although in the case of components package here, it already has "Usage". And we're treating this as something different 🤔 Maybe it's fine to have a separate section for this "necessary steps between installation and usage". Or we could fold it into an existing section. "Setup" is probably more consistent as a noun heading though, if we kept it.

Good point about the noun/verb agreement. Turns out "Setup" is used as a heading in some other packages in here as well, so I went with that ecf4fd6.

aduth · 2026-04-02T17:56:59Z

packages/admin-ui/README.md

+import '@wordpress/components/build-style/style.css';
+import '@wordpress/admin-ui/build-style/style.css';


Aside: It would be really nice if we made a subpath export with a nicer import path here, to avoid build-style being part of the import path. Feels like an implementation detail we shouldn't need to expose to end-users 🤷

On the other hand, it's probably a pretty niche use case to use these libraries outside of WordPress?

True, not an especially urgent problem. More to the general consistency of how we want to use subpath exports. They're a public API. But build-style means nothing and could disappear or be renamed tomorrow if we wanted it to.

it's probably a pretty niche use case to use these libraries outside of WordPress?

Note that until admin-ui is bundled by default by tooling provided by Gutenberg, the import is mandatory also in WP Admin contexts.

It might even help clarify in docs that component style is required to import only outside WP contexts, and the other two in all contexts?

Note that until admin-ui is bundled by default by tooling provided by Gutenberg, the import is mandatory also in WP Admin contexts.

I've raised this as a structural problem for both DataViews and Admin UI. Possibly less of a problem for Admin UI, if there's less chance of stylesheet conflicts on a given route (as opposed to e.g. DataForm, which could more plausibly have multiple separate bundles loading into a single route). I believe the simplest solution for Admin UI would be to switch to our CSS module injection system (#77032).

aduth · 2026-04-02T18:01:15Z

packages/admin-ui/README.md

+import '@wordpress/admin-ui/build-style/style.css';
+```
+
+RTL versions of the stylesheets are available in the same paths, but with `-rtl` appended to the filename (`style-rtl.css`). The design tokens stylesheet is universal and does not have a separate RTL version.


I wonder if it's worth clarifying that we don't ship an RTL-specific stylesheet for the ui package.

I also wonder what level of effort would be involved in removing it from this admin-ui package, since it doesn't include a whole lot and might be easy to migrate to logical properties.

I wonder if it's worth clarifying that we don't ship an RTL-specific stylesheet for the ui package.

The "The design tokens stylesheet is universal and does not have a separate RTL version." line at the end was supposed to be this clarification. Was that unclear or did you mean something else?

I also wonder what level of effort would be involved in removing it from this admin-ui package, since it doesn't include a whole lot and might be easy to migrate to logical properties.

Oh yes, should be pretty easy especially at this early stage. Also a move to CSS modules. In light of the #76744 problem too, ~~I'm thinking we can enforce the "CSS modules + logical properties" combination repo-wide on packages that want to adopt this new setup~~ we already do 😄.

The "The design tokens stylesheet is universal and does not have a separate RTL version." line at the end was supposed to be this clarification. Was that unclear or did you mean something else?

I was more referring to a note in packages/ui/README.md for someone who might be confused about the absence of an RTL stylesheet. There's an implication here that downstream consumers will be handling RTL concerns, so if I'm an app developer and I know that I need to handle RTL, I might be confused if I can't find any mention of a stylesheet I need to load for RTL in @wordpress/ui documentation.

Ah, I see. Added in b8eb232.

Ah, I see. Added in b8eb232.

Thanks, looks great 👍

Issue for CSS module migration of admin-ui package: #77032

oandregal · 2026-04-06T08:42:16Z

Thanks for the changes, this reads a lot better.

* Improve CSS setup instructions in readmes * Fix * Remove non-existent stylesheet handles * Use Setup as readme section heading * Add note to ui readme about no RTL version Co-authored-by: mirka <0mirka00@git.wordpress.org> Co-authored-by: aduth <aduth@git.wordpress.org>

Improve CSS setup instructions in readmes

200a8d2

mirka self-assigned this Apr 1, 2026

mirka added the [Type] Developer Documentation Documentation for developers label Apr 1, 2026

github-actions bot added [Package] Components /packages/components [Package] DataViews /packages/dataviews [Package] UI /packages/ui labels Apr 1, 2026

mirka added 2 commits April 2, 2026 06:19

Fix

ad21101

Remove non-existent stylesheet handles

1aca267

mirka commented Apr 1, 2026

View reviewed changes

mirka marked this pull request as ready for review April 1, 2026 21:52

mirka requested review from a team, ajitbohra, gigitux, ntsekouras and oandregal as code owners April 1, 2026 21:52

mirka mentioned this pull request Apr 1, 2026

Admin UI: add documentation #76484

Open

mirka mentioned this pull request Apr 2, 2026

Theme: Rename typography tokens to use "typography" prefix #76912

Merged

aduth approved these changes Apr 2, 2026

View reviewed changes

mirka added 2 commits April 3, 2026 23:17

Use Setup as readme section heading

ecf4fd6

Add note to ui readme about no RTL version

b8eb232

mirka enabled auto-merge (squash) April 3, 2026 14:33

mirka mentioned this pull request Apr 3, 2026

Admin UI: Move to CSS modules #77032

Open

mirka merged commit 49b4af3 into trunk Apr 3, 2026
43 of 49 checks passed

mirka deleted the readme-css-setup branch April 3, 2026 15:10

github-actions bot added this to the Gutenberg 23.0 milestone Apr 3, 2026

ciampo mentioned this pull request Apr 10, 2026

ui/docs: add additional global css setup instructions #77228

Merged


		### Within WordPress

		To ensure proper load order, add the `wp-components` stylesheet as a dependency of your plugin's stylesheet. See [wp_enqueue_style documentation](https://developer.wordpress.org/reference/functions/wp_enqueue_style/#parameters) for how to specify dependencies.

		import '@wordpress/components/build-style/style.css';
		import '@wordpress/admin-ui/build-style/style.css';

Conversation

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

Uh oh!

What?

Why?

How?

Testing Instructions

Use of AI Tools

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aduth left a comment

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!

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!

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

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!

Uh oh!

oandregal commented Apr 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mirka commented Apr 1, 2026 •

edited

Loading

github-actions bot commented Apr 1, 2026 •

edited

Loading

github-actions bot commented Apr 1, 2026 •

edited

Loading

mirka Apr 3, 2026 •

edited

Loading