Storybook: Demonstrate light, dark, and nested themes

[ciampo]

Related: #82038

What?

Makes light and dark themes easier to understand through clear Storybook toolbar presets and short ThemeProvider documentation.

It also expands the example application into a WordPress-editor-like layout with a separately themed sidebar, a toolbar-controlled canvas, and themed overlays.

Why?

ThemeProvider accepts color seeds, not a light or dark mode. Consumers need a clear mapping from light and dark background seeds to generated tokens, plus a practical example of theme inheritance across an application.

How?

The toolbar controls the root and canvas themes. Inline presets control the application shell and sidebar, while nested providers reapply the root settings to the canvas.

The menu and dialog currently retain the sidebar theme through React context when portaled to the document body. #82038 will make overlays follow their portal destination instead, and this example will clearly demonstrate that change.

Testing Instructions

1. Run npm run storybook:dev and open Design System > Theme > Theme Provider > Example Application.
2. Change the toolbar theme and confirm that the controls and canvas update.
3. Change Sidebar theme and confirm that only the application shell and sidebar update.
4. Open Site actions > View site details and confirm that the menu and dialog use the sidebar theme.
5. Open Design System > Theme > Introduction and review Light and dark themes.

Testing Instructions for Keyboard

Use Tab, Enter, Space, and Escape to operate the theme controls, menu, and dialog. Confirm that closing the dialog returns focus to Site actions.

Screen recording

Here are the new Theme tools used on the new version of the "example application" story:

Kapture.2026-08-26.at.16.09.34.mp4

Use of AI Tools

Codex was used to implement, inspect, and verify this change.

[github-actions]

Size Change: 0 B

Total Size: 7.92 MB

_{compressed-size-action}

[github-actions]

Flaky tests detected in 8e96be8.
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/32995399456
📝 Reported tests:

Should save the changes in /test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js, passed after 2 failed attempts.

TimeoutError: page.waitForFunction: Timeout 10000ms exceeded.
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js:34:14
TimeoutError: locator.click: Timeout 10000ms exceeded.
Call log:
  - waiting for locator('role=button[name="Visual"i]')

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js:33:55

[github-actions]

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: ciampo <mciampini@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.

[ciampo]

Also moved to #82081, will remove from this PR on rebasing

[aduth]

This is a really neat improvement 👍 Especially like the support for custom color schemes and seeing how that affects components through the Storybook, and the ability to link those to others.

Example: http://localhost:50240/?path=/docs/design-system-components-button--docs&globals=dsColorTheme:custom;dsPrimaryColor:!hex(0b6f0d)

Left a handful of comments, but nothing particularly blocking.

[aduth]

These changes make it so that all of the following content falls under the "Light and dark themes" heading, including details about "the cursor prop" that don't really have anything to do with light and dark mode. We could maybe reorganize the details so that this section comes last and only includes relevant details about contrasting color ramps, for example.

[aduth]

I notice this shows up as black on a dark gray background with very little contrast. Why is that?

http://localhost:50240/?path=/story/design-system-theme-theme-provider-example-application--example-application&globals=dsColorTheme:dark

[aduth]

Could the three sections here be implemented as a vertical Stack with xl gap rather than applying top margin to this and bottom margin to the "My app" text?

I suppose it's all dummy content anyways and not really crucial to "get it right" if the intent here is more about showing how overlay content works in the context of the sidebar.

[aduth]

Do we really want to be adding all this new Emotion stuff? I guess I don't know exactly how it'd look like to do it otherwise, I suppose a bunch of inline styles?

[aduth]

I'm not really sure I understand the purpose of this function. It looks like it essentially always returns the value it's given? I guess its value is in falling back to light for any unexpected values?

[aduth]

This feels a bit specific to the "Example Application" story that I wonder if it should live there instead.

[ciampo]

@aduth all feedback addressed, going to merge once CI checks are green

[aduth]

I don't think #82039 (comment) was addressed? I'll disable auto-merge just for acknowledgment.

[ciampo]

It was addressed. The text was wrong because ThemeProvider creates the dark color tokens, but it does not automatically apply them as the CSS color property. Setting the color CSS property in storybook/decorators/with-design-system-theme.tsx fixed it.

Here's a screenshot:

[aduth]

Strange, I swear I had updated my local copy, but you're right, I missed the color change, and it works as expected for me on the newly published Storybook site.

[aduth]

Something I noticed after testing it out a bit more: It might be nice if this option were persisted a bit better (URL or otherwise). Right now, if you select a sidebar theme like Ectoplasm, and then proceed change the content area theme under the "Theme" toolbar dropdown, the sidebar theme will reset to "Fresh".

reset.mov

[ciampo]

Yeah, that's because it's a custom UI, not linked via Storybook controls / addons. I'll look into improve that aspect

[ciampo]

#82111