Add ExampleApplication story for ThemeProvider to better demonstrate component theme-ability#76463
Merged
jameskoster merged 7 commits intotrunkfrom Mar 17, 2026
Merged
Add ExampleApplication story for ThemeProvider to better demonstrate component theme-ability#76463jameskoster merged 7 commits intotrunkfrom
jameskoster merged 7 commits intotrunkfrom
Conversation
Adds a richer Storybook demo showing ThemeProvider in an app-like layout with sidebar, header, and content area using @wordpress/ui components (Button, Card, Tabs, Link, Badge, Notice, Text, Stack). Storybook controls for primary color, background color, and density allow interactive exploration of theme token propagation. Made-with: Cursor
jameskoster
added
[Type] Enhancement
|
Flaky tests detected in 1a220b9. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/23195216329
|
Needed to resolve the @wordpress/ui import in the ExampleApplication story. Made-with: Cursor
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Avoids a circular devDependency between @wordpress/theme and @wordpress/ui. Also excludes storybook stories from the use-recommended-components lint rule.
|
Size Change: 0 B Total Size: 8.75 MB ℹ️ View Unchanged
|
mirka
reviewed
Mar 13, 2026
Member
mirka
left a comment
mirka
left a comment
There was a problem hiding this comment.
Very cool!
I went ahead and pushed some necessary changes:
- Moved the story to the root
storybookworkspace, to avoid adding a@wordpress/uidependency in@wordpress/theme. We can't do that because it would create a circular dependency between the theme and ui packages. - Removed the
experimentaltag on the story (related #76500).
Comment on lines
+296
to
+317
| argTypes: { | ||
| children: { table: { disable: true } }, | ||
| isRoot: { table: { disable: true } }, | ||
| color: { table: { disable: true } }, | ||
| primary: { | ||
| control: { type: 'color' }, | ||
| description: 'Primary seed color for the theme.', | ||
| }, | ||
| bg: { | ||
| control: { type: 'color' }, | ||
| description: 'Background seed color for the theme.', | ||
| }, | ||
| density: { | ||
| control: { type: 'select' }, | ||
| options: [ undefined, 'default', 'compact', 'comfortable' ], | ||
| }, | ||
| } as any, | ||
| args: { | ||
| primary: undefined, | ||
| bg: undefined, | ||
| density: undefined, | ||
| } as any, |
Member
There was a problem hiding this comment.
This is not very maintainable, so I'd like to suggest two possible alternatives:
-
Demonstrate it using the standard
ThemeProvidercontrols like the otherThemeProviderstories, but withchildrenandisRoothidden. The downside is that thecolorcontrol is an object, and hard to play with. -
Move this story somewhere outside of the "Theme Provider" section, and demonstrate it using the Theming tool, instead of the Controls. Maybe add more color options to the tool, if that's better.
What do you think? The main disadvantage of keeping it custom-defined like the current implementation is that we'll have to update it every time any of these options are changed or added in ThemeProvider. So ideally we want to "piggyback" these onto a theming playground that already exists.
Contributor
Author
There was a problem hiding this comment.
What I like about the current implementation is the free-form edit-ability of the bg and primary controls; it really demonstrates the power and flexibility of the color system.
Maybe add more color options to the tool, if that's better.
I'm guessing not, but would a 'Custom' option with color pickers be feasible?
Contributor
There was a problem hiding this comment.
I agree with both 😅 in the dedicated tokens story, I opted for a picker directly in the code — although I'm not sure it's better than custom controls?
Contributor
Author
There was a problem hiding this comment.
I updated to follow the With Picker story example. Do y'all think this is better?
Contributor
There was a problem hiding this comment.
Still not sure about the best approach (compromise) here, but I don't think it should be blocking
mirka
reviewed
Mar 13, 2026
Comment on lines
+62
to
+65
| { /* eslint-disable jsx-a11y/heading-has-content */ } | ||
| <Text | ||
| variant="heading-sm" | ||
| render={ <h2 /> } |
Member
There was a problem hiding this comment.
This is not very nice, huh 😅 I'll look into what we can do so we don't need an eslint-disable every time.
Made-with: Cursor
Use useState hooks and native color/select inputs rendered directly in the story canvas instead of custom argTypes with `as any` casts. This makes the story self-contained and avoids manual maintenance when ThemeProvider's API changes. Made-with: Cursor
ciampo
approved these changes
Mar 17, 2026
Contributor
ciampo
left a comment
ciampo
left a comment
There was a problem hiding this comment.
I believe we can ship this and iterate as needed, unless @mirka has any blocking feedback?
Separately, I think that we should update storybook/package.json to include @wordpress/element, @wordpress/private-apis and @worpress/ui — although I then noticed that almost no @wordpress/* dependencies are listed there. So probably something that should be tackled separately
Member
|
Yes, non-blocking 👍 We might even consider bringing these color picker controls into the main theming toolbar tool. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Screen.Recording.2026-03-13.at.09.44.13.mov
What
Adds a new
ExampleApplicationStorybook story forThemeProviderthat renders a realistic mock application page, demonstrating how multiple@wordpress/uicomponents respond to theme changes together.Why
The existing
ThemeProviderstories demonstrate token values and individual behaviors, but don't show how theming works in a real-world application context. Having a cohesive example makes it much easier to evaluate the effect of changingprimarycolor,bgcolor, anddensityacross a full UI -- buttons, cards, tabs, links, badges, and notices all responding in concert.How
ExampleApplicationstory that renders a two-column layout with a sidebar navigation and a main content area containing a header and settings cards.@wordpress/uicomponents exclusively:Button,Card,Badge,Tabs,Link,Notice,Stack, andText.--wpds-color-*), so every surface and text element adapts whenprimaryorbgseed colors are changed via Storybook controls.primary,bg, anddensityto keep the demo focused.@wordpress/uias adevDependencyinpackages/theme/package.jsonto support the import.Testing
npm run storybook:dev -w storybookprimarycolor picker -- the brand button and links should updatebgcolor picker -- all surface backgrounds should updatedensitybetween default, compact, and comfortable -- spacing should adjust throughout