storybook-addon-theme-playground


storybook-addon-theme-playground is a theme addon for storybook. It provides a panel where theme values can be tweaked directly.

!Screenshot
🌍 Example

Features

- 🎛 Seperate panel with auto-generated controls for each theme value
- 🧬 Customizable controls based on your needs

Table of Contents

- Installation
- Parameters
- Config
- Controls
- Control components
- Default controls
- Typescript

Installation

#### 1. Install the addon

``sh
npm install -D storybook-addon-theme-playground

yarn add -D storybook-addon-theme-playground
`

#### 2. Add the addon to your storybook config

Add to .storybook/main.js

`js
module.exports = {
addons: ["storybook-addon-theme-playground"],
};
`

#### 3. Add parameters

Add to .storybook/preview.js.

`js
// Import a theme provider of your choice
import { ThemeProvider } from "styled-components";

import theme from "path/to/theme";

export const parameters = {
themePlayground: {
theme,
provider: ThemeProvider,
},
};
`

To add multiple themes, add an Array to the theme key. Each theme must have a name and a theme key.

`js
import { ThemeProvider } from "styled-components";
import defaultTheme from "path/to/default/theme";
import anotherTheme from "path/to/another/theme";

export const parameters = {
themePlayground: {
theme: [
{ name: "Default Theme", theme: defaultTheme },
{ name: "Another Theme", theme: anotherTheme },
],
provider: ThemeProvider,
},
};
`

Parameters

$3

object | Array<{ name: string, theme: object }> | required

The theme object or multiple themes as an array of objects.

$3

any | required

Any provider component which will accept a theme object prop and children. storybook-addon-theme-playground has no default provider due to extendability.

$3

object | optional

Optional control components of default controls. Look at the controls section for detailed documentation.

$3

object | optional

An additional config object can be added. Look at the Config section for detailed documentation.

$3

"path" || "startCase" || (path: string[]) => string | default: "startCase"

$3

boolean | default: true

Set to false updating the theme values will not be debounced.

$3

number | default: 500

$3

boolean | default: true

Set to false no code component will be rendered.

$3

boolean | default: false

Shows the difference between initial theme and modified theme. Currently in an experimental state. Rendering multiple global styles for example override each other.

$3

boolean | default: false

Set to true to disable addon panel for single stories.

`js
export default {
title: "Disabled story",
parameters: {
themePlayground: { disabled: true },
},
};
`

Config

Example

`js
import { ThemeProvider } from "styled-components";

export const parameters = {
themePlayground: {
theme: { button: { color: "#000" } },
provider: ThemeProvider,
config: {
// One of "path"
labelFormat: "path", // "button.color"
// or "startCase"
labelFormat: "startCase", // "Button Color"
// or a custom function
labelFormat: (path) => {
// path is equal to ["button", "color"]
return path.join("-"); // "button-color"
},
debounce: true || false,
debounceRate: 500,
showConfig: true || false,
},
},
};
`

Controls

storybook-addon-theme-playground will render default controls based on the theme value. If you want to customize them, you can override the default controls by adding an controls object to the parameters.

As a key use the theme object path, e.g 'button.spacing'.

All controls accept a type, label, description and icon prop.
You can use all icons from the storybook styleguide.

Example

`js
import { ThemeProvider } from "styled-components";

import theme from "path/to/theme";

const controls = {
"button.spacing": {
type: "number",
icon: "expand",
label: "Button Spacing",
description: "Spacing for all buttons",
min: 1,
max: 20,
steps: 1,
},
"button.color.primary": {
type: "color",
label: "Button Primary Color",
},
};

export const parameters = {
themePlayground: { theme, controls, provider: ThemeProvider },
};
`

$3

It is also possible to hide specific theme values or objects, e.g.:

`js
const controls = {
breakpoints: {
hidden: true,
},
"button.spacing": {
hidden: true,
},
};
`

Control components

$3

`js
'theme.path': {
type: 'color',
icon: string,
hidden: boolean,
label: string | 'Theme Path',
description: string | null
}
`

$3

`js
'theme.path': {
type: 'number',
icon: string,
hidden: boolean,
label: string | 'Theme Path',
description: string | null,
min: number | 0,
max: number | 100,
steps: number | 1
}
`

$3

`js
'theme.path': {
type: 'select',
icon: string,
hidden: boolean,
label: string | 'Theme Path',
description: string | null
options: [
{
value: string | number,
label: string
}
]
}
`

$3

`js
'theme.path': {
type: 'shorthand',
icon: string,
hidden: boolean,
label: string | 'Theme Path',
description: string | null
}
`

$3

`js
'theme.path': {
type: 'switch',
icon: string,
hidden: boolean,
label: string | 'Theme Path',
description: string | null
}
`

$3

`js
'theme.path': {
type: 'radio',
icon: string,
hidden: boolean,
label: string | 'Theme Path',
description: string | null
options: [
{
value: string,
label: string
}
]
}
`

$3

`js
'theme.path': {
type: 'range',
icon: string,
hidden: boolean,
label: string | 'Theme Path',
description: string | null,
min: number | 0,
max: number | 100,
steps: number | 1
}
`

Default controls

storybook-addon-theme-playground will render the following components based on the value.

$3

> boolean

$3

> number

$3

> string

$3

> string && string.endsWith("px" || "rem" || "em" || "%")

$3

> string && string.startsWith("#" || "rgba" || "rgba") || label.includes("color")

$3

> object && Object.keys(object).length === 4 && Object.keys(object).includes("top" && "right" && "bottom" && "left")

Typescript

`ts
// .storybook/preview.ts

import {
withThemePlayground,
ThemePlaygroundProps,
} from "storybook-addon-theme-playground";

import theme from "path/to/theme";

interface ThemePlaygroundParams extends ThemePlaygroundProps {
theme: typeof theme;
}

const params: ThemePlaygroundParams = {
theme,
provider: ThemeProvider,
controls: {
"headline.fontWeight": {
type: "range",
max: 900,
min: 1,
description: "Define the font weight of the variable font",
},
"copy.fontWeight": {
type: "range",
max: 900,
min: 1,
description: "Define the font weight of the variable font",
},
},
};

export const parameters = { themePlayground: params };
``