Theming our Storybook#

In the Installing Storybook lesson, we learned about main and preview, the most important configuration files of Storybook, and saw how the main file relates to Storybook server configurations and preview relates to how stories are rendered. There's also another configuration file that is not very well known, but can bring quite some value to your Storybook's UI: manager.

Manager#

Storybook is essentially a React application that loads components in isolation using iframes. The manager is what the app layer of Storybook is called, and preview is the region in which stories are rendered:

If you want to configure Storybook's UI, you can do so by creating a .storybook/manager.ts file.

The manager controls the behavior, look and feel of the Storybook's UI. This file allows you to set preferences for Storybook's UI, such as the position of the addons panel, whether or not you want keyboard shortcuts, and more (you can see full details here). The file also allows us to configure Storybook's theme (background colors, text colors, etc.).

Dark mode!#

Nowadays, apps are only cool if they have dark mode, right? Thankfully, Storybook supports that too! Following the steps from the theming docs, we see how the code looks like, switching Storybook's theme to dark mode. Create a new file .storybook/manager.ts

// .storybook/manager.ts

import { addons } from '@storybook/addons';

import { themes } from '@storybook/theming';

addons.setConfig({

  // define a theme preset, which could be light (default) or dark

  theme: themes.dark,

});

As this is the first time you are introducing the manager file to this project, you need to restart Storybook for the changes to be applied.

And here is what Storybook looks like:

Before:

After:

Pretty cool, right?

Making Storybook match our brand#

The create function provides many theme variables that you can override. This means you can set the values for backgrounds, shadows, borders, etc.

As an exercise, let's update manager.ts to create a theme that matches with newline's brand (feel free to change and make your own theme).

// ./storybook/manager.ts

import { addons } from '@storybook/addons'

import { create } from '@storybook/theming'

const theme = create({

  base: 'light', // this will inherit the base properties of Storybooks'light theme

  // Base color

  colorSecondary: '#45bc5a', // Chateau Green

  // UI

  appBg: '#F6F9FC',

  appContentBg: '#FFFFFF',

  appBorderColor: 'rgba(0,0,0,.1)',

  appBorderRadius: 4,

  // Typography

  fontBase: '"Open Sans", sans-serif',

  fontCode: 'monospace',

  // Text colors

  textColor: '#333333',

  textInverseColor: '#FFFFFF',

  textMutedColor: '#666666',

  // Toolbar default and active colors

  barTextColor: '#999999',

  barSelectedColor: '#45bc5a',

  barBg: '#FFFFFF',

  // Form colors

  inputBg: '#FFFFFF',

  inputBorder: 'rgba(0,0,0,.3)',

  inputTextColor: '#333333',

  inputBorderRadius: 4,

  // Brand assets

  brandTitle: 'Newline Storybook',

  brandUrl: 'https://newline.co',

  brandImage:

    'https://d8dgeb1f3fxgw.cloudfront.net/static/img/logo/newline/newline-logo-longwise-solo-lightbg-gray.svg',

})

addons.setConfig({

  theme,

})

Because the manager file was already picked by Storybook, you don't need to restart Storybook again. Now you can just refresh the browser and see the newly customized Storybook UI:

Before:

After:

Customizing the favicon#

Storybook also allows you to append HTML to the manager layer, which is useful for adding styles or meta tags to Storybook's HTML. Let's try that out by creating a file manager-head.html inside of .storybook folder with newline's logo as favicon. This small detail can make a Storybook feel much more personal:

<!-- .storybook/manager-head.html -->

<link rel="icon" type="image/png" sizes="16x16" href="https://d8dgeb1f3fxgw.cloudfront.net/static/img/icons/favicon-16x16.png">

For these changes to be applied, we need to kill and restart Storybook. After running Storybook again, notice the updated favicon in the browser's bar!

If you'd like to see more in-depth explanations about theming, check the documentation here.

What's next?#

We just learned how to customize Storybook to look more like our brand or style. If you're customizing your own project's Storybook, share it in newline's Discord community so everybody can see how cool it looks like! In the next lesson, we will go over what we have done in this module.