Terminal
Terminal/Skill
Sets up Chromatic visual tests across light and dark mode or other themes using the Modes API and the Storybook themes addon.
By Chromatic
Works with
npx skills add chromaui/chromatic-skills --skill chromatic-themesConfigure multi-theme visual testing using Chromatic's Modes API and @storybook/addon-themes.
This skill covers:
.storybook/modes.ts@storybook/addon-themes imports, a modes.ts file, or chromatic.modes.reference/docs-map.md.reference/output-contract.md.Check .storybook/preview.ts, story files, and any modes.ts:
withThemeByClassName or withThemeByDataAttribute found → addon already configured, help extend or wire up modeschromatic.modes with theme keys found → already on Modes API, help extend or fixUse the URLs in reference/docs-map.md and fetch with WebFetch. Use fetched content as the authoritative source — do not rely on remembered examples.
@storybook/addon-themes (fresh setup only)If @storybook/addon-themes is not already installed, detect the package manager by checking for lock files (bun.lockb/bun.lock → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm) and use the matching install command:
| Package manager | Command |
|---|---|
| npm | npm install --save-dev @storybook/addon-themes |
| yarn | yarn add --dev @storybook/addon-themes |
| pnpm | pnpm add --save-dev @storybook/addon-themes |
| bun | bun add --dev @storybook/addon-themes |
Then register it in .storybook/main.ts:
export default {
addons: ['@storybook/addon-themes'],
};
Ask: "Which theme library or approach does your project use? (e.g. Tailwind, Bootstrap, Material UI, styled-components, Emotion, or plain CSS classes)"
Use the answer to pick the right path:
| Library | Decorator | Docs to fetch |
|---|---|---|
| Tailwind, plain CSS classes | withThemeByClassName | themes.txt |
| Bootstrap | withThemeByDataAttribute (data-bs-theme) | getting-started/bootstrap.md |
| Material UI | custom decorator | getting-started/material-ui.md |
| styled-components | custom decorator | getting-started/styled-components.md |
| Emotion | custom decorator | getting-started/emotion.md |
| Other / unsure | withThemeByClassName | themes.txt |
Class-based (withThemeByClassName):
// .storybook/preview.ts
import { withThemeByClassName } from '@storybook/addon-themes';
export const decorators = [
withThemeByClassName({
themes: { light: 'light-theme', dark: 'dark-theme' },
defaultTheme: 'light',
// parentSelector: 'html', // default
}),
];
Data attribute (withThemeByDataAttribute):
import { withThemeByDataAttribute } from '@storybook/addon-themes';
export const decorators = [
withThemeByDataAttribute({
themes: { light: 'light', dark: 'dark' },
defaultTheme: 'light',
attributeName: 'data-bs-theme', // default: 'data-theme'
}),
];
Custom decorator — fetch the library-specific guide from reference/docs-map.md and follow it. Use pluckThemeFromContext and initializeThemeState from @storybook/addon-themes to bridge Storybook globals with the library's theme API.
Create or update .storybook/modes.ts. The theme key must exactly match a key in the decorator's themes object:
export const allModes = {
light: { theme: 'light' },
dark: { theme: 'dark' },
} as const;
Project-wide (.storybook/preview.ts):
import { allModes } from './modes';
const preview = {
parameters: { chromatic: { modes: allModes } },
};
export default preview;
Per component or per story:
import { allModes } from '../.storybook/modes';
export default {
title: 'Button',
parameters: {
chromatic: { modes: { light: allModes.light, dark: allModes.dark } },
},
};
Disable inherited modes on a specific story:
parameters: { chromatic: { modes: { dark: { disable: true } } } }
Always render the checklist from reference/output-contract.md, then show the complete content of every file to create or modify.
theme value in a mode must exactly match a key in the decorator's themes object — a mismatch silently falls back to the default theme@storybook/addon-themes requires Storybook 7.x or laterwithThemeByClassName and withThemeByDataAttributereference/docs-map.mdreference/output-contract.md../chromatic-setup-ci/reference/package-manager.md — lock file detection and install commands per package manager