diff --git a/code/addons/themes/README.md b/code/addons/themes/README.md index 55bc748fd48f..c529f8a60258 100644 --- a/code/addons/themes/README.md +++ b/code/addons/themes/README.md @@ -27,6 +27,7 @@ For tool-specific setup, check out the recipes below - [`@emotion/styled`](https://github.com/storybookjs/storybook/tree/next/code/addons/themes/docs/getting-started/emotion.md) - [`@mui/material`](https://github.com/storybookjs/storybook/tree/next/code/addons/themes/docs/getting-started/material-ui.md) - [`bootstrap`](https://github.com/storybookjs/storybook/tree/next/code/addons/themes/docs/getting-started/bootstrap.md) +- [`postcss`](https://github.com/storybookjs/storybook/tree/next/code/addons/themes/docs/getting-started/postcss.md) - [`styled-components`](https://github.com/storybookjs/storybook/tree/next/code/addons/themes/docs/getting-started/styled-components.md) - [`tailwind`](https://github.com/storybookjs/storybook/tree/next/code/addons/themes/docs/getting-started/tailwind.md) - [`vuetify@3.x`](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#writing-a-custom-decorator) diff --git a/code/addons/themes/docs/getting-started/postcss.md b/code/addons/themes/docs/getting-started/postcss.md new file mode 100644 index 000000000000..3748dd272a10 --- /dev/null +++ b/code/addons/themes/docs/getting-started/postcss.md @@ -0,0 +1,114 @@ +# 🏁 Getting started with `postcss` + +## 📦 Install addon + +To get started, **install the package** as a dev dependency + +yarn: + +```zsh +yarn add -D @storybook/addon-themes postcss-dark-theme-class +``` + +npm: + +```zsh +npm install -D @storybook/addon-themes postcss-dark-theme-class +``` + +pnpm: + +```zsh +pnpm add -D @storybook/addon-themes postcss-dark-theme-class +``` + +## 🧩 Register Addon + +Now, **include the addon** in your `.storybook/main.js` file. + +```diff +module.exports = { + stories: [ + "../stories/**/*.stories.mdx", + "../stories/**/*.stories.@(js|jsx|ts|tsx)", + ], + addons: [ + "@storybook/addon-essentials", ++ "@storybook/addon-themes" + ], +}; +``` + +## 🏷️ Add class to `prefers-color-scheme` media + +CSS has special media at-rule for dark theme: `@media (prefers-color-scheme: dark)`. [`postcss-dark-theme-class`](https://github.com/postcss/postcss-dark-theme-class) can copy content of those at-rules to `.is-dark` selector. + +Check your project for existing PostCSS config: `postcss.config.js` in the project root, `"postcss"` section in `package.json` or postcss in bundle config. + +Add plugin to the list. + +```diff +module.exports = { + plugins: [ ++ require('postcss-dark-theme-class'), + require('autoprefixer') + ] +} +``` + +Use `prefers-color-scheme` media in your CSS: + +```css +:root { + --text-color: black; +} +@media (prefers-color-scheme: dark) { + html { + --text-color: white + } +} +``` + +## 🥾 Import your CSS + +To give your stories access to styles, import them into your `.storybook/preview.js` file. + +```diff +import { Preview } from "@storybook/your-renderer"; + ++import "../src/index.css"; + +const preview: Preview = { + parameters: { /* ... */ }, +}; + +export default preview; +``` + +## 🎨 Provide your theme(s) + +To enable switching between these modes in a click for your stories, use our `withThemeByClassName` decorator by adding the following code to your `.storybook/preview.js` file. + +```diff +-import { Preview } from "@storybook/your-renderer"; ++import { Preview, Renderer } from "@storybook/your-renderer"; ++import { withThemeByClassName } from "@storybook/addon-themes"; + +import "../src/index.css"; + + +const preview: Preview = { + parameters: { /* ... */ }, ++ decorators: [ ++ withThemeByClassName({ ++ themes: { ++ light: "is-light", ++ dark: "is-dark", ++ }, ++ defaultTheme: "light", ++ }), ++ ] +}; + +export default preview; +```