Theming: Theme manager with CSS custom properties

[JReinhold]

Closes #27223

Theming 2.0

Over the years, much has changed in Storybook, but theming has remained the same. From users' perspective, the list of options felt like an in-between without a good support for multiple themes. For maintainers, it became quite a struggle to understand what colour which led to a lot of compromises and overrides. With this project, we intend to simplify the theming API for users while allowing maintainers more freedom on how to use these values.

To offer a nice transition, we introduced a function that will convert the existing theme into the new theme to make sure this work in backward compatible. Here is a quick highlight of what this update is about:

• Setting a custom theme will have to be done using pure CSS in storybook/manager-head.html.
• All theme values are set using CSS variables like --sb-accent.
• You can set a different theme for light and dark theme.
• By just updating --sb-accent, we automatically generate a set of colours for your text, background, icons, .. automatically.
• You can have a custom accent or background for the sidebar.
• Using class names, you can extend this API to your need and create multiple themes if you want.

RFC available here - #24344
Following PR with all updated values in the manager - #26863

List of CSS variables available

• --sb-accent - Set the accent colour everywhere.
• --sb-background - Set the background on the sidebar, toolbar and addon panel.
• --sb-accentSidebar - Set a custom accent colour for your sidebar.
• --sb-backgroundSidebar - Set a custom background for your sidebar.
• --sb-documentation - To set the colour of the docs icon on the sidebar.
• --sb-directory - To set the colour of the directory icon on the sidebar.
• --sb-component - To set the colour of the component icon on the sidebar.
• --sb-story - To set the colour of the story icon on the sidebar.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

1. Create a sandbox
2. Open it. Toggle between light and dak theme in the browser DevTools, see that the color changes instantly now and doesn't require a reload.
3. Add this to a .storybook/manager-head.html emulating a user writing a custom theme:

<style>
  @media (prefers-color-scheme: light) {
    :root {
      --sb-accent: #8df68a;
    }
  }
  @media (prefers-color-scheme: dark) {
    :root {
      --sb-accent: #144d30;
    }
  }

</style>

4. Restart Storybook and see your new theme in effect. 💅

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=<PR_NUMBER>

[github-actions]

	Fails
🚫	PR is marked with "ci: do not merge" label.
🚫	PR is not labeled with one of: ["ci:normal","ci:merged","ci:daily","ci:docs"]

Generated by 🚫 dangerJS against a5269bb

[cdedreuille]

@JReinhold Thanks a lot for this first POC. I just added the list of main CSS variables we want to support for both light and dark theme. I think there's still some investigation to do to make sure we keep the old theme in place while implementing the new version.

The main issue is that this is not a 1 to 1 mapping so just changing the set color in the old theme by the CSS variable will not be enough. I think one way to go with it would be to have new new CSS variables in place directly in the manager and we find a way to convert the old theme into css variables. Just as an example, theme.textColor in the old theme will be multiple css variables in the old theme so you can customise the text color in multiple places.

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit a5269bb. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 1 target

• nx run-many -t build -c production --parallel=3

---

Sent with 💌 from NxCloud.