Storybook 暗色主题配置指南为 Docs 与整个 UI 应用深色主题【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本指南聚焦于 Storybook 主题系统中的 Docs 主题配置核心场景是在.storybook/preview.js中通过parameters.docs.theme为文档页Docs指定暗色主题同时兼顾管理器Manager UI的全局主题设置与自定义主题的创建方法。读完本文你将掌握内置主题light/dark/normal的选择机制、Docs 与主 UI 独立主题化的工作方式并能基于storybook/theming的create()API 生成符合团队品牌的自定义主题。主题系统概览内置主题与独立作用域Storybook 使用一套轻量的 theming APIstorybook/theming主题系统分为两个相互独立的层面Manager管理器 UI侧边栏、工具栏、面板等界面外壳通过.storybook/manager.js中的addons.setConfig({ theme })配置。Docs文档页基于 MDX/CSF 生成的组件文档通过.storybook/preview.js中的parameters.docs.theme配置。Storybook 内置了三套可直接使用的主题——light、dark以及跟随系统偏好preferred color scheme的normal。除非显式指定管理器默认使用normal主题而 Docs 的默认主题始终是 light无论主 UI 当前处于何种主题。这意味着即使你把整个 Storybook 界面切换成了暗色文档页仍会以亮色渲染需要单独配置。从源码看内置主题的定义集中在 code/core/src/theming/create.tsthemes对象由三部分组成export const themes: Themes { ...themesBase, // light 与 dark normal: themesBase[preferredColorScheme], // 跟随系统偏好 };其中preferredColorScheme由getPreferredColorScheme()在运行时解析因此normal主题在不同操作系统/浏览器设置下会解析为light或dark。该模块还同时导出了create()函数用于基于内置主题创建自定义主题详见后文。为 Docs 配置暗色主题要让 Docs 文档页使用暗色主题需要在预览侧preview的parameters.docs中设置theme字段将其指向storybook/theming导出的themes.dark。CSF 3 写法通用 renderer在.storybook/preview.js中import { themes } from storybook/theming; export default { parameters: { docs: { theme: themes.dark, }, }, };对应的 TypeScript 版本.storybook/preview.ts// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. import type { Preview } from storybook/your-framework; import { themes } from storybook/theming; const preview: Preview { parameters: { docs: { theme: themes.dark, }, }, }; export default preview;注意storybook/your-framework是占位符实际应替换为项目所用的框架包例如storybook/react-vite、storybook/nextjs、storybook/vue3-vite等。CSF Next 写法definePreviewCSF Next 实验性语法通过definePreview()组织配置需要显式引入并注册storybook/addon-docs。React 框架.storybook/preview.tsx// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { definePreview } from storybook/your-framework; import addonDocs from storybook/addon-docs; import { themes } from storybook/theming; export default definePreview({ addons: [addonDocs()], parameters: { docs: { theme: themes.dark, }, }, });JS 版本.storybook/preview.jsx// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { definePreview } from storybook/your-framework; import addonDocs from storybook/addon-docs; import { themes } from storybook/theming; export default definePreview({ addons: [addonDocs()], parameters: { docs: { theme: themes.dark, }, }, });Vue 框架.storybook/preview.tsimport { definePreview } from storybook/vue3-vite; import addonDocs from storybook/addon-docs; import { themes } from storybook/theming; export default definePreview({ addons: [addonDocs()], parameters: { docs: { theme: themes.dark, }, }, });import { definePreview } from storybook/vue3-vite; import addonDocs from storybook/addon-docs; import { themes } from storybook/theming; export default definePreview({ addons: [addonDocs()], parameters: { docs: { theme: themes.dark, }, }, });Angular 框架.storybook/preview.tsimport { definePreview } from storybook/angular; import addonDocs from storybook/addon-docs; import { themes } from storybook/theming; export default definePreview({ addons: [addonDocs()], parameters: { docs: { theme: themes.dark, }, }, });Web Components 框架.storybook/preview.tsimport { definePreview } from storybook/web-components-vite; import addonDocs from storybook/addon-docs; import { themes } from storybook/theming; export default definePreview({ addons: [addonDocs()], parameters: { docs: { theme: themes.dark, }, }, });import { definePreview } from storybook/web-components-vite; import addonDocs from storybook/addon-docs; import { themes } from storybook/theming; export default definePreview({ addons: [addonDocs()], parameters: { docs: { theme: themes.dark, }, }, });为整个 Storybook UI 应用暗色主题如果你希望侧边栏、工具栏、面板等 Manager UI 也整体变为暗色则需在.storybook/manager.js中通过addons.setConfig()设置主题相关代码片段见 docs/_snippets/storybook-manager-dark-theme.mdimport { addons } from storybook/manager-api; import { themes } from storybook/theming; addons.setConfig({ theme: themes.dark, });Manager 与 Docs 的配合关系主 UI 与 Docs 使用同一套主题系统但彼此独立渲染、互不继承。假设你已在manager.js中配置了暗色主题若想让 Docs 保持一致仍需按上一节的方式在preview.js中单独指定parameters.docs.theme。两处配置叠加后整个 Storybook 才会呈现统一的暗色观感。需要强调的是设置主题时应当传入完整的主题对象——主题是整体替换而非合并。因此不要只传一个{ base: dark }的部分对象到setConfig或docs.theme除非你明确使用create()生成完整主题。深入源码dark 主题的构成与 create() 创建自定义主题内置 dark 主题变量themes.dark本质上是定义在 code/core/src/theming/themes/dark.ts 中的一组ThemeVars主要包括品牌色colorPrimary: #FF4785珊瑚红、colorSecondary: #479DFF界面背景appBg: #1B1C1D、appContentBg: #222325、appHoverBg: #233952、appBorderColor: hsl(0 0% 100% / 0.1)、appBorderRadius: 4字体fontBase、fontCode继承自全局排版基础变量文字颜色textColor: #C9CCCF、textInverseColor: #1B1C1D、textMutedColor: #95999D工具栏barTextColor: #95999D、barHoverColor: #70B3FF、barSelectedColor: #479DFF、barBg: #222325表单控件buttonBg、booleanBg、inputBg、inputBorder、inputTextColor等light主题定义于同目录的light.ts结构一致、取值相反。Docs 暗色主题的渲染正是由这些变量驱动的Docs 容器与各 Block 组件均通过 emotion 从主题中取色相关实现可参见 code/addons/docs/src 下的 Blocks 组件。用 create() 生成自定义主题内置主题无法满足品牌需求时可在.storybook目录下新建YourTheme.js基于create()派生新主题import { create } from storybook/theming; export default create({ base: light, // Brand brandTitle: My custom Storybook, brandUrl: https://example.com, brandImage: https://storybook.js.org/images/placeholders/350x150.png, brandTarget: _self, // Colors colorPrimary: #3AEB97, colorSecondary: #70C3FF, // UI appBg: linear-gradient(to bottom right, #ffb1b1, #ffd6a5), appContentBg: linear-gradient(to bottom right, #f9f4f1, #fce9d8), appBorderColor: grey, appBorderRadius: 4, // Fonts fontBase: Open Sans, sans-serif, fontCode: monospace, // Text colors textColor: black, textInverseColor: rgba(255,255,255,0.9), textMutedColor: grey, });create()的合并逻辑见 code/core/src/theming/create.ts先继承preferredColorScheme对应主题再叠加vars.base指定的内置主题最后合并用户传入的vars并自动保证barSelectedColor回退到colorSecondary。其中base属性是必填的其余变量均可选。之后在manager.js中引入即可生效import { addons } from storybook/manager-api; import yourTheme from ./YourTheme; addons.setConfig({ theme: yourTheme, });storybook/theming使用 TypeScript 编写类型定义随包发布TypeScript 用户可以借助类型提示构建合法主题。进阶定制CSS 逃生舱与 MDX 组件覆盖主题 API 刻意保持精简。若需要更细粒度的样式控制可借助以下逃生舱均为高级用法使用时需自行承担风险因为 Storybook 内部 HTML 结构可能在版本迭代中变化Storybook UI 的样式在.storybook/manager-head.html中插入style标签Docs 的样式在.storybook/preview-head.html中插入style标签。另外使用 MDX 编写文档时还可以通过parameters.docs.components覆盖 Markdown 渲染的组件例如自定义code块的渲染器甚至替换内置的Canvas /Block。这是 Storybook 官方未正式支持的进阶能力但为特殊场景提供了极大的灵活性。小结与最佳实践为 Storybook 应用暗色主题时记住两条关键结论Docs 与 Manager 独立主题化themes.dark只作用于你配置它的那一侧。想全站暗色需同时在manager.jsaddons.setConfig和preview.jsparameters.docs.theme两处配置主题是替换而非合并始终传入由内置themes或create()生成的完整主题对象base必填。从 code/core/src/theming/create.ts 的源码可以确认normal主题是跟随系统配色偏好的动态解析结果而light/dark是稳定的内置常量——这使 Storybook 既能开箱即用地切换深浅色也支持基于create()的深度品牌定制。完整的主题配置说明还可参考 docs/configure/user-interface/theming.mdx。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考