Storybook

What it does

• .storybook/preview.ts imports the CSS variables export (/docs/exports), so stories render with the same tokens as the app (docs).
• Storybook's own @storybook/addon-themes sets a data attribute on <html> from a toolbar menu (docs). Pointed at the attribute the export switches on, it flips every story between modes.
• Optional: an MDX page with the ColorPalette and ColorItem doc blocks, fed by the JavaScript module export.

Before you start

• Storybook 10 (these steps were checked against the 10.6 docs) with any framework. CSS imports in preview.ts work without extra setup.
• A Stoaken API key and a stoaken.config.json from npx stoaken init (see /docs/cli).

Setup

1. Add two saved targets. css holds every mode in one file; js is one mode, for swatches.

{
  "brandId": "…",
  "brandName": "Acme",
  "serverUrl": "https://www.stoaken.com",
  "exports": [
    { "theme": "Default", "format": "css", "out": "src/styles/tokens.css" },
    { "theme": "Default", "format": "js", "mode": "scheme:light", "out": "src/styles/tokens.js" }
  ]
}

2. Run npx stoaken export. The CSS file's header names the attribute to switch on. From Stoaken's sample theme:

 * Modes:
 * - scheme: light (default), dark. Switch with data-scheme="dark" on <html> or any element.
 */
:root {
  …
  --color-brand-primary: #007c2b;
  …
}

[data-scheme="dark"] {
  --color-brand-primary: #c8bdff;
  …
}

3. Install the addon with npm install -D @storybook/addon-themes, and add '@storybook/addon-themes' to addons in .storybook/main.ts.
4. In .storybook/preview.ts, import the tokens and add the decorator. Replace @storybook/your-framework with your framework package, such as @storybook/react-vite:

import type { Preview, Renderer } from '@storybook/your-framework'
import { withThemeByDataAttribute } from '@storybook/addon-themes'

import '../src/styles/tokens.css'

const preview: Preview = {
  decorators: [
    withThemeByDataAttribute<Renderer>({
      themes: { light: 'light', dark: 'dark' },
      defaultTheme: 'light',
      attributeName: 'data-scheme',
    }),
  ],
}

export default preview

5. Optional: add a swatches page. It must match the stories globs in .storybook/main.ts, and needs @storybook/addon-docs.

import { Meta, ColorPalette, ColorItem } from '@storybook/addon-docs/blocks'
import tokens from './styles/tokens.js'

<Meta title="Tokens/Colours" />

<ColorPalette>
  <ColorItem title="Brand" subtitle="color.brand" colors={tokens.color.brand} />
  <ColorItem title="Surface" subtitle="color.surface" colors={tokens.color.surface} />
  <ColorItem title="Emerald" subtitle="palette.emerald" colors={tokens.palette.emerald} />
</ColorPalette>

Configuration

• The attribute is your Brand's: use the attribute and mode names from the file's header, for example data-color-scheme for an axis called color-scheme. The themes values are the mode names.
• Follow the device instead: export css-auto. It switches on data-theme, which is the addon's default attributeName, so you can leave that option out.
• Components must use the variables, such as background: var(--button-primary-background), for the toolbar to change them.

Try it

1. Run npm run storybook. The toolbar has a theme menu.
2. Choose dark. <html> gets data-scheme="dark", and components that use the variables change (in the sample, --color-brand-primary goes from #007c2b to #c8bdff).
3. Open Tokens/Colours in the sidebar to see the swatches.

Troubleshooting

• The menu does nothing: attributeName doesn't match the file's header, parentSelector points somewhere other than html, or the component has hard-coded colours.
• A swatch row is empty: the path after tokens. doesn't exist in tokens.js. Open the file and check the names.
• Old values: run npx stoaken export again. Add npx stoaken export --check to CI to catch this (see /docs/cli).

Limits

• The swatches show the one mode in tokens.js, whichever theme the toolbar is on. Export a second js file for the other mode if you want both.
• The addon switches one attribute. A Brand with two mode axes needs a decorator per axis, or a custom one.
• There's no Stoaken addon. Stories show the tokens as of the last export.