Theme: Promote ThemeProvider to stable API by aduth · Pull Request #78958 · WordPress/gutenberg

aduth · 2026-06-04T19:33:22Z

What?

Closes #76840
Closes #75319

Updates @wordpress/theme to export ThemeProvider and useThemeProviderStyles as part of its stable API.

Why?

As described in Design system theming for WordPress 7.1 #76941, ThemeProvider stabilization is an expected deliverable of WordPress 7.1
With WordPress 7.1 release development officially started as of May 20, landing this early in the release cycle allows for a longer testing cycle
Using private APIs in bundled packages causes issues, as described in UI: Remove usage of private APIs #75319

How?

Removes lock-ing of private APIs from @wordpress/theme
Updates consumers to replace unlock-ing private APIs with direct import of the stable members

Testing Instructions

Verify no regressions in surfaces where ThemeProvider is used, for example the Fonts screen or Storybook Theme pages.

In Storybook:

npm run storybook:dev
Go to http://localhost:50240/?path=/docs/design-system-theme-theme-provider--docs

In Fonts screen:

npm run dev
Go to http://localhost:8888/wp-admin/themes.php?page=font-library-wp-admin&p=%2Ffont-list
Verify that "Update" button color follows the current user theme color

Use of AI Tools

No AI was used.

github-actions · 2026-06-04T19:33:35Z

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: aduth <[email protected]>
Co-authored-by: ciampo <[email protected]>

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

github-actions · 2026-06-04T19:48:56Z

Size Change: -1.24 kB (-0.02%)

Total Size: 7.5 MB

📦 View Changed

Filename	Size	Change
`build/modules/boot/index.min.js`	52.9 kB	-63 B (-0.12%)
`build/modules/content-types/index.min.js`	159 kB	-182 B (-0.11%)
`build/scripts/block-directory/index.min.js`	43.5 kB	-198 B (-0.45%)
`build/scripts/block-editor/index.min.js`	381 kB	-183 B (-0.05%)
`build/scripts/customize-widgets/index.min.js`	14.6 kB	+6 B (+0.04%)
`build/scripts/edit-post/index.min.js`	52.9 kB	-47 B (-0.09%)
`build/scripts/edit-site/index.min.js`	299 kB	-135 B (-0.05%)
`build/scripts/editor/index.min.js`	475 kB	-202 B (-0.04%)
`build/scripts/format-library/index.min.js`	30.8 kB	-1 B (0%)
`build/scripts/media-utils/index.min.js`	114 kB	-55 B (-0.05%)
`build/scripts/theme/index.min.js`	22.1 kB	-180 B (-0.81%)

_{compressed-size-action}

github-actions · 2026-06-04T20:12:47Z

Flaky tests detected in b43c2be.
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/26975139006
📝 Reported issues:

[Flaky Test] Should insert content using the global inserter #78924 in /test/e2e/specs/widgets/editing-widgets.spec.js

ciampo

I guess this is unrelated from the the package README that mentions This package is still experimental. "Experimental" means this is an early implementation subject to drastic and breaking changes, right?

ciampo · 2026-06-08T10:12:18Z

-export { privateApis } from './private-apis';
 export type * from './prebuilt/ts/token-types';
-export { type ThemeProvider } from './theme-provider';
+export { ThemeProvider } from './theme-provider';


Now that it;s a public API, we should probably add JSDocs to the ThemeProvider component

Now that it;s a public API, we should probably add JSDocs to the ThemeProvider component

Yeah, good call. And this will benefit the MCP server once we expose it there.

Now that it;s a public API, we should probably add JSDocs to the ThemeProvider component

Yeah, good call. And this will benefit the MCP server once we expose it there.

Added in b7cdc2f. Feedback welcome on wording. I originally started from how we describe it in README.md but refined it a bit. Maybe we want to revisit the README phrasing as well. "provide design tokens" isn't exactly accurate, because the provider doesn't generate a full set of tokens.

I also altered the ESLint configuration in 2158b04 to support this, and add a more complex explanation of why that exclusion applies.

aduth · 2026-06-08T13:14:19Z

I guess this is unrelated from the the package README that mentions This package is still experimental. "Experimental" means this is an early implementation subject to drastic and breaking changes, right?

I overlooked that and my instinct would be to remove it, as the intention here is stabilizing the API. What do you think?

ciampo · 2026-06-08T13:22:39Z

I overlooked that and my instinct would be to remove it, as the intention here is stabilizing the API. What do you think?

Given that we're potentially going to apply breaking changes to the DS tokens in the upcoming weeks, we could leave it around and remove it only when we stabilize the whole package (ie. version 1.0?), leaving this PR focused on making ThemeProvider a public API.

aduth · 2026-06-08T18:32:20Z

I overlooked that and my instinct would be to remove it, as the intention here is stabilizing the API. What do you think?

Given that we're potentially going to apply breaking changes to the DS tokens in the upcoming weeks, we could leave it around and remove it only when we stabilize the whole package (ie. version 1.0?), leaving this PR focused on making ThemeProvider a public API.

Yeah, that makes sense. It was also an oversight on my part that this doesn't do anything toward actually marking the package for 1.0 release, so we could make the promotion to 1.x and removal of the "experimental" banner a separate follow-on task closer to the 7.1 public release. Maybe tying it with a specific milestone like beta or RC ?

aduth · 2026-06-22T20:41:14Z

@ciampo Do you think we're good to move forward with this, or were you considering this blocked by other theme stabilization work?

ciampo · 2026-06-22T22:02:17Z

#79254 should be the last PR introducing breaking changes in the tokens, should we wait for it to be merged first?

ciampo

#79254 is now merged, let's go!

LGTM 🚀

No current external usage, ThemeProvider should generally be preferred.

…oc params

ciampo · 2026-06-23T20:47:55Z

@aduth do you think we still need to

export type * from './prebuilt/ts/token-types';

from the package?

ciampo · 2026-06-23T20:49:21Z

Also, it looks like packages/private-apis/src/implementation.ts still mentions @wordpress/theme ?

aduth · 2026-06-23T20:56:17Z

@aduth do you think we still need to

export type * from './prebuilt/ts/token-types';

from the package?

Do you think we shouldn't? Personally I don't view that as related to the ThemeProvider component if the thinking is that we only needed those types because the component was private. Whether we want it in the public API in general though, I'm open to revisiting. They could certainly provide some value, though their original introduction was largely around the Box component and tying its typings to what's available through prebuilt token types, and we've since moved away from that.

Also, it looks like packages/private-apis/src/implementation.ts still mentions @wordpress/theme ?

Good catch, I'll update that 👍

ciampo · 2026-06-23T21:10:21Z

They could certainly provide some value, though their original introduction was largely around the Box component and tying its typings to what's available through prebuilt token types, and we've since moved away from that.

I agree that they can provide value, but (especially given the nature of the package) I think we should only export what we know is needed as of now, and add more exports if necessary. The opposite won't be possible once the package is marked as stable

aduth · 2026-06-24T12:38:26Z

The opposite won't be possible once the package is marked as stable

We could still make backwards-incompatible changes to TypeScript typings, no? Since they're not part of the window.wp.theme global.

ciampo · 2026-06-24T15:52:42Z

The opposite won't be possible once the package is marked as stable

We could still make backwards-incompatible changes to TypeScript typings, no? Since they're not part of the window.wp.theme global.

Not sure, we received complaints in the past about breaking type changes, too — especially form the point of view of third party maintainers that need to support multiple versions of WP and therefore woulnd't be able to have a single implementation that satisfies all versions at the same time (cc @mirka)

aduth · 2026-06-24T16:26:51Z

That might be improved separately with #79455.

In any case, let's take a look. I know we use a couple of the types ourselves at the moment, but most of them are likely unused.

aduth requested a review from a team as a code owner June 4, 2026 19:33

github-actions Bot added [Package] Theme /packages/theme [Package] UI /packages/ui labels Jun 4, 2026

aduth added the [Type] New API New API to be used by plugin developers or package users. label Jun 4, 2026

This comment was marked as outdated.

Sign in to view

ciampo reviewed Jun 8, 2026

View reviewed changes

aduth mentioned this pull request Jun 8, 2026

theme/ThemeProvider: rename color.bg prop to color.background #79007

Merged

aduth force-pushed the update/theme-provider-stable branch from b43c2be to b7cdc2f Compare June 8, 2026 19:08

aduth requested a review from manzoorwanijk as a code owner June 8, 2026 19:08

github-actions Bot added the [Package] Edit Site /packages/edit-site label Jun 8, 2026

ciampo mentioned this pull request Jun 11, 2026

@wordpress/theme: overall API and architecture assessment #77462

Open

23 tasks

simison mentioned this pull request Jun 22, 2026

Update Bundled @wordpress/* monorepo Automattic/jetpack#49272

Open

1 task

aduth mentioned this pull request Jun 22, 2026

Design system theming for WordPress 7.1 #76941

Open

aduth force-pushed the update/theme-provider-stable branch from b7cdc2f to f1c017b Compare June 22, 2026 20:40

ciampo approved these changes Jun 23, 2026

View reviewed changes

aduth added 5 commits June 23, 2026 12:24

Theme: Promote ThemeProvider to stable API

7520f73

Remove useThemeProviderStyles from public API

0c4f990

No current external usage, ThemeProvider should generally be preferred.

Include theme package for exclusion rule for TypeScript component JSD…

06b9f0b

…oc params

Theme: Add JSDoc documentation for ThemeProvider

9d68c29

Move UI changelog under Unreleased

9497e61

aduth force-pushed the update/theme-provider-stable branch from 7c79f96 to 9497e61 Compare June 23, 2026 16:24

aduth merged commit 3fb683e into trunk Jun 23, 2026
45 checks passed

aduth deleted the update/theme-provider-stable branch June 23, 2026 17:21

github-actions Bot added this to the Gutenberg 23.5 milestone Jun 23, 2026

simison mentioned this pull request Jun 26, 2026

Revert "Theme: Promote ThemeProvider to stable API (#78958)" #79592

Closed

This was referenced Jun 26, 2026

Theme: Revert ThemeProvider stable API #79594

Merged

Theme: Restore public ThemeProvider export #79620

Merged

simison mentioned this pull request Jun 29, 2026

Private api docs: elaborate on how to add/deprecate private APIs between bundled and externalized packages #79634

Open

ciampo mentioned this pull request Jun 30, 2026

Theme: document as stable in storybook & readme #79700

Open

Uh oh!

Conversation

aduth commented Jun 4, 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!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

github-actions Bot commented Jun 4, 2026

Uh oh!

This comment was marked as outdated.

Uh oh!

ciampo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ciampo Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

aduth Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

aduth Jun 8, 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!

aduth commented Jun 8, 2026

Uh oh!

ciampo commented Jun 8, 2026

Uh oh!

aduth commented Jun 8, 2026

Uh oh!

aduth commented Jun 22, 2026

Uh oh!

ciampo commented Jun 22, 2026

Uh oh!

ciampo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ciampo commented Jun 23, 2026

Uh oh!

ciampo commented Jun 23, 2026

Uh oh!

aduth commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ciampo commented Jun 23, 2026

Uh oh!

aduth commented Jun 24, 2026

Uh oh!

ciampo commented Jun 24, 2026

Uh oh!

aduth commented Jun 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aduth commented Jun 4, 2026 •

edited

Loading

github-actions Bot commented Jun 4, 2026 •

edited

Loading

github-actions Bot commented Jun 4, 2026 •

edited

Loading

aduth Jun 8, 2026 •

edited

Loading

aduth commented Jun 23, 2026 •

edited

Loading