[RFC] Storybook Theming 2.0 - CSS variables + HTML classes

[cdedreuille]

Status: in review; championed by @cdedreuille

Summary

A lot has changed in Storybook over the years but theming stayed the same. The values and colour calculation made sense but as the platform evolved it has become a system that's hard to maintain and difficult to work with. One of the key aspect of Storybook is to be able to use as a documentation tool and share your design system with your team and community. We want to make it easy for anyone to make Storybook their own.

By upgrading our theming system, we hope that users will feel comfortable enough to use Storybook as the main medium to promote their design system. We believe there's 4 main key principles to this work:

• Light / Dark
  Custom themes could be set as light and dark mode following the user local setup
• Explicit
  It should be really easy to understand what colour is used and where.
• Easy to customise
  We want users to make Storybook feel like an extension of their brand.
• Easy to maintain
  For internal updates or for addon creators, it should be easy to maintain.

Problem Statement

Storybook theming is today hard to understand for any maintainers and in some part incomplete, specially when it comes to light and dark mode. Not everything can be customised and a lot of users feel limited. Here are a few of the main problems we are trying to solve with theming 2.0

• Hard to understand where the themes values are used
• No support for a custom theme that works for both light and dark mode
• Very confusing for addon creators or contributors
• Very hard internally to understand what colours need to be used

Non-goals

Storybook is still a tool. Even though we want to allow for a lot of flexibility, we don't want Storybook to become a site builder. Every elements we want to support inside this new theming system will be part of a controlled list of options. If some users feel the need for complete customisation, there are other possible solutions we can think about (embed, ...)

Implementation

A solution in 3 steps:

1. CSS variables
   Replace all colours, font family, by CSS variables the user can update.
2. HTML classes
   Add classnames on all components to allow users to use them as they see fit.
3. Theme generator - Coming soon as a separate RFC
   Generate a theme using very simple values. Could even be as part of the onboarding.

Prior Art

CSS variables is quite common these days. Arc is using it and allow you to customise arc directly if you want. Slack is also using a theme generator that's quite easy to use.

Deliverables

CSS variables

Today we are using a very limited series of values to set your theme. We then use these values in the background to create a more complete set of tokens we use in the app. We believe that this calculation is not necessary. We are proposing to create a list of tokens set as CSS variables with main goals to be explicit and easy to customise. Each elements in the manager and every single components will get their own set of tokens that you can customise globally in your theme.

→ Would have to be done as a non-breaking change, potentially as part of 8.0

→ Full transition in 9.0 to remove the old layout

We have multiple ways to solve this technically 👇

Option 1 - The JS option

// .storybook/manager.js

// The create() function would be depreciated in 8.0
import { create } from '@storybook/theming/create';

addons.setConfig({
  theme: create({}) // depreciated but still accessible in 8.0
  themeLight: customLight,
  themeDark: customDark,
});

const customLight = {
  // Global data
  brandTitle: 'My custom Storybook',
  brandUrl: 'https://example.com',
  brandImage: 'https://storybook.js.org/images/placeholders/350x150.png',
  brandTarget: '_self',
	
	// Colors
  sidebarBorderRight: "#FFD000",
  toolbarBg: "--var-wert"
}

const customDark = {
  sidebarBorderRight: "#FFF3F3",
  toolbarBg: "--sb-sidebar-bg"
}

👍 Pros

• The object can be typed for you to see the list of options directly
• All done in one file
• You can only set 2 themes for light and dark mode.

👎 Cons

• Names are different from the CSS variables

Option 2 - The CSS option

// .storybook/manager.js

// The create() function would be depreciated in 8.0
import { create } from '@storybook/theming/create';

addons.setConfig({
  theme: create({}) // depreciated but still accessible in 8.0

  brandTitle: 'My custom Storybook',
  brandUrl: 'https://example.com',
  brandImage: 'https://storybook.js.org/images/placeholders/350x150.png',
  brandTarget: '_self',
});

/* .storybook/theme.css */

:root {
  --sb-sidebar-bg: '#00080',
}

@media (prefers-color-scheme: dark) {
  --sb-sidebar-bg: '#00080',
}

👍 Pros

• It uses CSS without having JS in between
• Names are exactly how they should be

👎 Cons

• Not sure how a user can know about the different values they could use.

How to name css variables

Each component will have its own set of css variables centralised under :root

• Every variable will have a prefix --sb

• Following by a group sidebar, iconButton, … written in camelCase

• And then a property bg, hoverBg, … written in camelCase

  → [--sb]-[group]-[property]

HTML Classes

This is for power users who really want to mess around. Sometimes you want to explore more interactions. By adding class names on main components we allow them to inject javascript or css wherever they want.

Risks

By making this project backward compatible in 8.0 we remove most of the risks linked with this project. But still, this will touch a lot of files so we will have to be careful to build it in many pieces.

Unresolved Questions

• What is the right implementation. JS or CSS?
• Should we add more than just colours in the list of CSS variables?
• Would the HTML classes be useful?
• How users would use HTML classes?

[JReinhold]

Option 1 or 2

It feels like this proposal is mainly about creating a set of CSS custom properties that the user can override (basically option 2). I don't see how option 1 is much of an improvement over the current system, I like option 2 way more just because of the fact that it's using standard browser API's that were used for this, so it won't require any special CSS-in-JS knowledge to operate.

I don't feel like the downside of option 2 - discoverability - is such a big deal. Given that we'll probably have a lot of variables, getting a complete list of them from TypeScript will be too overwhelming anyway. This is much better documented visually in a public Figma file or similar.

[cdedreuille]

I also like option 2 but I'm just wondering about maintainability. What if we depreciate some values because the DOM element is just not there? They might end up with css variables that are not used anymore without a way to tell them. It would not break anything but I just wanted to make sure that we are ok with that.

[Sidnioulz]

You could use CSS tricks to show deprecation banners in development environments, that appear only when a deprecated CSS var is shown, telling users to remove them.

You could also make a small PostCSS plugin that reports the use of deprecated variables.

[JReinhold]

Backwards compatibility

I can see how in 8.0 we can have this new CSS Custom Properties API while still supporting the current way of customizing the theme with @storybook/theming. Under the hood that package could just map the input to set custom properties.

[JReinhold]

Should we add more than just colours in the list of CSS variables?

I definitely think that we should. A custom brand is also about border radii, sizes, font families. It's not feasible that every single padding etc. is customisable, but I think it's doable with the main ones, that won't break everything.

[cdedreuille]

Yes you're right but I don't think we should add everything. We can add more elements as we go or if there's any requests for it.

[JReinhold]

Would the HTML classes be useful?

I feel like this would be great for power users. But we need to keep it as a "breaking API", ie. users can expect changes to classes and the DOM in patch releases, otherwise we'll be tying our hands too much. But I think there is a segment of users out there that would be okay with that - we're already seeing users using this today by targeting the hash-generated classes.

[cdedreuille]

This is really an easy one. The bigger part will be to document it to make sure people understand that this can break anytime.

[JReinhold]

An interesting note here is that this is actually how we document it today, we just haven't been consistent with actually adding the classes and we need a system that enforces this.

https://storybook.js.org/docs/react/configure/theming#css-escape-hatches

[chakAs3]

What is the right implementation. JS or CSS?

Ideally should be only CSS, especially now with tool like tailwindcss made fun and easy. Even animations now with the new Chrome API, so handy without a need for Javascript

[cdedreuille]

Yes, sounds about right.

[wraybowling]

I'm going to throw out an alternative method I like to use, a single class that encapsulates storybook related things. Simply, .storybookjs wrappers around blocks of page content controlled by Storybook could be overwritten in CSS as you like without worrying about making a CSS variable for everything.

[JReinhold]

I'm not sure I understand this, can you explain more how this would work in practice?

[Sidnioulz]

They might mean to replace the CSS-in-JS and its unpredictable selectors with a more predictable system like BEM, and then adding a .storybookjs class on HTML bodys so you can rewrite the selectors with more specificity?

I personally prefer CSS variables, they offer a more compact and discoverable way of editing the theme if well thought out, but I have to say I would have been able to customise Storybook much further if it indeed used a more predictable styling systme than CSS in JS frameworks.

[JReinhold]

A new unanswered question came to mind.

With this new CSS Variable approach, how do we maintain the possibility to change the styles at runtime, by the user? Ie. being able to toggle between different themes dynamically?

This is currently what storybook-dark-mode does, which makes use of addons.setOptions({ theme }) under the hood.

But if we're replacing the JS API for styles with a CSS API, we might need another way to change the theme dynamically.

Admittedly Storybook manager UI should have a built-in toggle to set dark/light/system theme that could solve this, but that is another proposal entirely, and it also might not solve it for users needing other themes than light/dark - eg. if you need red/blue/yellow themes, or even different brands.

[brittneypostma]

I do wish I didn't have to restart the server every time I make a change to see them. That would be a nice addition.

[cdedreuille]

If we have a css only approach using CSS variables it will change automatically if your laptop goes to dark mode. I agree that we should offer a (light/dark/auto) switch. We could potentially add this feature as part of this project.

[brittneypostma]

I was just chatting with Jeppe and saying this would be awesome to have something like this and I had a thought that I could just import my css variable file into the manager-head file. I just tried it and it works.

[JReinhold]

Great to hear, will make it way simpler for users importing their own design tokens!

[cdedreuille]

Following up on this RFC, we are working on a solution here #25314. The main changes have been to reduce the number of CSS variables to the strict minimum. For a user, you could if you want change a single CSS variable and the entire manager will adapt to this colour.

If you need more customisation, we will advise you to use our classnames directly.