Skip to content

DataViews: externalize theme stylesheet #75182

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

Merged
oandregal merged 4 commits into from
Feb 3, 2026
+21 −4
Merged

DataViews: externalize theme stylesheet #75182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
00f7bf9
Remove design-token stylesheet
oandregal Feb 3, 2026
fbae7e1
Update stylesheet dependencies
oandregal Feb 3, 2026
8a4bdc0
Update PR number in changelog
oandregal Feb 3, 2026
936ba46
Add theme stylesheet as a dependency
oandregal Feb 3, 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
4 changes: 4 additions & 0 deletions packages/dataviews/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

## Unreleased

### Breaking Changes

- The design tokens stylesheet (`@wordpress/theme/design-tokens.css`) is no longer embedded in the DataViews stylesheet. Applications using DataViews outside of WordPress must now explicitly include the design tokens stylesheet. See the README for installation instructions. [#75182](https://github.com/WordPress/gutenberg/pull/75182)

### Bug Fixes

- DataViews: Add title attribute in grid item title field. [#75085](https://github.com/WordPress/gutenberg/pull/75085)
Expand Down
13 changes: 13 additions & 0 deletions packages/dataviews/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,19 @@ Install the module
npm install @wordpress/dataviews --save
```

## Stylesheet Dependencies

DataViews depends on stylesheets from `@wordpress/components` and `@wordpress/theme`. In a WordPress admin page context, these are loaded automatically. For applications outside WordPress, you will need to include these stylesheets:
Copy link
Member

@mirka mirka Feb 4, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

Sorry I overlooked this point — as far as I know these are not "loaded automatically" in WordPress, they require an wp_enqueue_style like we document in the @wordpress/components readme:

gutenberg/packages/components/README.md

Line 28 in b054863

Many components include CSS to add styles, which you will need to load in order for them to appear correctly. Within WordPress, 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.

This is also wrong in the @wordpress/ui readme so I'll fix.

Another point is that I don't think we load the @wordpress/theme design tokens stylesheet in Gutenberg yet, so if DataViews actually uses anything that requires a design token, that might be broken right now 😅

(cc @WordPress/gutenberg-components in case I got something wrong here)

Copy link
Member

@aduth aduth Feb 4, 2026

Choose a reason for hiding this comment

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

I thought this would be handled through the dependency chain from DataViews style loading to the wp-theme stylesheet as a dependency, i.e. what was corrected in #74743.

Copy link
Member

@mirka mirka Feb 5, 2026

Choose a reason for hiding this comment

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

Even if the DataViews stylesheet did load the theme stylesheet (which it doesn't anymore in this PR), shouldn't a consumer need to wp_enqueue_style the DataViews stylesheet at least? To ensure correct load order, at the very least? That's what's documented in the @wordpress/components readme, so if that's wrong I would want to fix it.

Copy link
Member

@aduth aduth Feb 5, 2026

Choose a reason for hiding this comment

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

Hm, the more I dig into this, the more I feel we may in-fact be missing something.

I think there's some partial truth to this. There are examples like @wordpress/boot where technically WordPress is handling the "loaded automatically" by loading theme styles. But obviously this boot package isn't yet used everywhere.

There may be some incidental behavior where the theme styles are brought in via dependency chains, e.g. @wordpress/dataviews -> @wordpress/ui -> @wordpress/theme which is translated into style dependencies through the build's inferStyleDependencies. But it builds those dependencies out of imports in the JavaScript code, which is fragile and not a strong signal of what style dependencies should be loaded.

How it should work? I'm not super clear, but maybe one of:

  • Use @wordpress/boot in more places as a true boot-point for "WordPress" and all its core styling
  • Manually revise dependencies like what we do in lib/client-assets.php to include wp-theme in more entrypoint packages
  • Sprinkle @use "@wordpress/theme/src/prebuilt/css/design-tokens.css" throughout some more entrypoint stylesheets
  • Invent a way to more explicitly define these dependencies, like a wpStyleDependencies field in package.json that's respected by the build tool

Some of those options may still require documentation that consumers would be responsible for ensuring the styles are enqueued.

cc @youknowriad @jsnajdr

Copy link
Contributor

@youknowriad youknowriad Feb 5, 2026

Choose a reason for hiding this comment

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

The way I see it is:

  • is any package that renders <ThemeProvider> should be also doing @use "@wordpress/theme/src/prebuilt/css/design-tokens.css"
  • The "boot" package is one of many entry points in WordPress
  • Most edit-* packages are also entry points and if we want to start using UI components in these, they need to render ThemeProvider and include the tokens CSS.
  • Since dataviews is already using UI components and dataviews is used in most of these edit-* packages, we need to follow-up with the addition of ThemeProvider and tokens to all of these packages.

Where I think we could improve things:

  • Using ThemeProvider should ideally automatically inject the design tokens (once).

Copy link
Member

@aduth aduth Feb 5, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

  • Using ThemeProvider should ideally automatically inject the design tokens (once).

It's an option, though as discussed previously in #74174 (comment) it feels like it just shifts the dependency from the a stylesheet to a React component. So a project external to WordPress that wants to use DataViews but doesn't care about theming still has to introduce a ThemeProvider wrapper somewhere.

  • Most edit-* packages are also entry points and if we want to start using UI components in these, they need to render ThemeProvider and include the tokens CSS.

Yeah, I think this is a logical next step. We may not strictly need the ThemeProvider component, just the styles should be enough to start. I also want to be conscious whether this ships with WordPress 7.0 and creates expectations around the theme variables; ideally we'd leave it out, but I also don't want anything to be broken if it was by these changes 😓

If we did add the styles to the entrypoints, then I think it's accurate to say that this would be handled automatically inside WordPress as mentioned in the changelog note.

Copy link
Contributor

@youknowriad youknowriad Feb 5, 2026

Choose a reason for hiding this comment

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

It's an option, though as discussed previously in #74174 (comment) it feels like it just shifts the dependency from the a stylesheet to a React component. So a project external to WordPress that wants to use DataViews but doesn't care about theming still has to introduce a ThemeProvider wrapper somewhere.

Yes, but the main API for these components is React, so it's just simplifies things and ThemeProvider is almost already mandatory. That said, this is not the main thing in this discussion. We can live with or without it.

Yeah, I think this is a logical next step. We may not strictly need the ThemeProvider component, just the styles should be enough to start.

We do need the ThemeProvider (or more precisely the UserThemeProvider) in order to adapt to the currently selected user profile.

If you think this is too soon for 7.0, the only other option I see is to revert the usage of the UI package in dataviews.

Copy link
Member

@aduth aduth Feb 5, 2026

Choose a reason for hiding this comment

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

We do need the ThemeProvider (or more precisely the UserThemeProvider) in order to adapt to the currently selected user profile.

I'm not sure if we're using anything where we need the user preference at the moment? Although yes, we should probably just go ahead and get this established.

If you think this is too soon for 7.0, the only other option I see is to revert the usage of the UI package in dataviews.

I was going to suggest we could revert the changes made in this pull request, but (a) I'm still not entirely sure it's broken as-is, and (b) regardless, the styles would be defining :root theme CSS properties, so those are going to be present for everyone.

I think we could probably be okay with what's shipping, especially after the latest rounds of token refinement. I'd like if we had some flexibility for revisions without too much fear of backwards-compatibility even after releasing, though I dunno how others may feel about that.

Copy link
Contributor

@ciampo ciampo Feb 6, 2026

Choose a reason for hiding this comment

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

As of now, ThemeProvider is only needed if in need of customizing the default theme — otherwise, the CSS file includes all the required variables with the default theme values.

I see value in not requiring ThemeProvider, and also in the fact that using CSS variables should prevent FUOC while the ThemeProvider hasn't calculcated the overridden CSS variables.

Copy link
Contributor

@youknowriad youknowriad Feb 6, 2026

Choose a reason for hiding this comment

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

Important thing is that edit-site and edit-post... still update properly the colors when the user profile is modified. So if tomorrow someone starts using any component that uses colors from @wordpress/ui in @wordpress/dataviews we'd be introducing a bug without knowing.


```bash
npm install @wordpress/components @wordpress/theme
```

```tsx
import '@wordpress/components/build-style/style.css';
import '@wordpress/theme/design-tokens.css';
```

## `DataViews`

<div class="callout callout-info">At <a href="https://wordpress.github.io/gutenberg/">WordPress Gutenberg's Storybook</a> there's an <a href="https://wordpress.github.io/gutenberg/?path=/docs/dataviews-dataviews--docs">example implementation of the Dataviews component</a>.</div>
Expand Down
2 changes: 0 additions & 2 deletions packages/dataviews/src/style.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
@use "@wordpress/theme/src/prebuilt/css/design-tokens.css" as *;

@use "./dataviews/style.scss" as *;
@use "./components/dataviews-bulk-actions/style.scss" as *;
@use "./components/dataviews-filters/style.scss" as *;
Expand Down
5 changes: 3 additions & 2 deletions storybook/package-styles/config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import fieldsLtr from '../package-styles/fields-ltr.lazy.scss?inline';
import fieldsRtl from '../package-styles/fields-rtl.lazy.scss?inline';
import mediaFieldsLtr from '../package-styles/media-fields-ltr.lazy.scss?inline';
import mediaFieldsRtl from '../package-styles/media-fields-rtl.lazy.scss?inline';
import theme from '../package-styles/theme.lazy.scss?inline';
Copy link
Member

@mirka mirka Feb 3, 2026

Choose a reason for hiding this comment

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

I would like to consolidate this to a single designTokens import.

Copy link
Member Author

@oandregal oandregal Feb 3, 2026

Choose a reason for hiding this comment

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

👍 designTokens looks good to me as name, though that link points to the UI stylesheet that is different? I merged in the interest of velocity, but happy to iterate on this or address any other issue if you can't on #74899

Copy link
Member

@mirka mirka Feb 4, 2026

Choose a reason for hiding this comment

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

No worries, consolidated in #74899!

import ui from '../package-styles/ui.lazy.scss?inline';

/**
Expand Down Expand Up @@ -60,8 +61,8 @@ const CONFIG = [
},
{
componentIdMatcher: /^dataviews-/,
ltr: [ componentsLtr, dataviewsLtr ],
rtl: [ componentsRtl, dataviewsRtl ],
ltr: [ theme, componentsLtr, dataviewsLtr ],
rtl: [ theme, componentsRtl, dataviewsRtl ],
},
{
componentIdMatcher: /^fields-/,
Expand Down
1 change: 1 addition & 0 deletions storybook/package-styles/theme.lazy.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
@import "../../packages/theme/src/prebuilt/css/design-tokens.css";
Loading