storybook

dot-skills Storybook 最佳实践

全面介绍如何将 Storybook 9+ 用作 TypeScript/React 组件库的工作坊和测试平台。涵盖 8 个类别中的 52 条规则，按组件在设计系统中的生命周期排序：错误的 .storybook/main.ts 会影响所有故事；格式错误的 CSF Meta 会导致该文件无法使用 autodocs、控件、测试和 a11y 面板。

本技能涵盖的内容

1. 设置 — main.ts、preview.ts、框架选择（Vite 还是 Webpack、Next.js 还是仅 React）、通过 CLI 安装插件、staticDirs。
2. 编写故事（CSF3） — satisfies Meta<typeof Component>、具名导出 = 故事、tags: ['autodocs'] 的放置位置、何时适合使用 render、故事命名约定。
3. Args、argTypes、控件 — 何时依赖推断、何时声明 control: 'select'、使用 storybook/test 中的 fn() 处理回调、args、parameters 与 globals 的区别。
4. 装饰器与组合 — 在 preview.ts 中配置全局提供程序、使用 MSW 模拟网络请求、子路径导入模块模拟（Storybook 9+）、装饰器签名中的常见问题。
5. 交互测试 — play 函数、storybook/test 导入路径（而非 @storybook/test）、解构 canvas/userEvent、优先使用 findBy* 而非 waitFor、在 CI 中使用 addon-vitest、可移植故事。
6. 无障碍（通过 @storybook/addon-a11y 使用 axe-core） — 将 parameters.a11y.test = 'error' 作为实际门槛、按规则禁用检查、使用 runOnly 限定 WCAG 目标范围、门户的 context、使用 globals.a11y.manual 标记有意违规的测试样例。
7. 文档与设计系统 — autodocs 与 MDX、在 MDX 中使用 <Canvas of={...} /> 引用故事、状态标签、将设计令牌作为故事、通过 parameters.design 添加 Figma 链接。
8. 构建与部署 — 优先使用 Vite 而非 Webpack、大型库按需打包、部署到 Chromatic/Vercel 供设计师审阅、CI 缓存配置。

适用场景

遇到以下情况时，请使用本技能：

• 编辑或创建会加载 storybookTest 的 *.stories.tsx、*.mdx、.storybook/main.ts、.storybook/preview.ts 或 vitest.config.ts。
• 在新项目中设置 Storybook（选择框架、完成 npx storybook init 后续配置）。
• 添加或升级插件（a11y、vitest、designs、msw）。
• 通过 play 函数和 Vitest 插件连接组件测试。
• 排查“Storybook 很慢”“控件显示文本而不是下拉选择”“我的对话框没有显示 a11y 面板”“CI 中的 play 函数不稳定”等问题。

以下情况请跳过本技能，改用：

• 使用 react-optimise / clean-code-ts-react 处理底层组件设计。
• 在 Storybook 之外，使用 react-testing-library 了解 render/screen/userEvent 的语义。
• 使用 WCAG/ARIA 参考文档了解规范本身；本技能假定你了解 aria-labelledby 的作用，并说明 addon-a11y 如何检查它。

按优先级划分的规则类别

顺序反映了组件生命周期（配置 → 编写 → 接入 → 装饰 → 测试 → 审核 → 编写文档 → 发布）。前面的阶段会产生连锁影响。

优先级	类别	影响	前缀	规则数
1	设置与配置	CRITICAL	config-	8
2	编写故事（CSF3）	CRITICAL	csf-	8
3	Args、ArgTypes 与控件	HIGH	args-	5
4	装饰器与组合	HIGH	deco-	7
5	交互测试	HIGH	test-	7
6	无障碍（axe）	HIGH	axe-	5
7	文档与设计系统	MEDIUM-HIGH	docs-	5
8	构建、性能与部署	MEDIUM	build-	7

快速参考

1. 设置与配置（关键）

• config-typed-main-config — 使用 satisfies StorybookConfig 为 main.ts 添加类型
• config-pick-the-right-framework-package — 使用与构建方式匹配的框架包（例如，Next.js 使用 @storybook/nextjs-vite）
• config-narrow-stories-glob — 将 stories glob 缩小到仅匹配故事文件
• config-typed-preview — 使用框架的 Preview 类型为 preview.ts 添加类型
• config-add-addons-via-cli — 使用 npx storybook add 安装插件，绝不要手动安装
• config-static-dirs-not-bundler-imports — 通过 staticDirs 提供资源，而非使用打包工具导入
• config-tokens-css-vars-in-preview — 将 Style Dictionary / Tokens Studio 的输出作为 CSS 变量接入 preview.ts
• config-story-sort-for-large-libraries — 为设计系统侧边栏设置 parameters.options.storySort 顺序（基础 → 组件 → 模式）

2. 故事编写 — CSF3（关键）

• csf-satisfies-meta-not-typed — 使用 satisfies Meta<typeof Component>，绝不要使用 : Meta<typeof Component>
• csf-prefer-args-over-render — 默认使用 args；仅在复合故事中使用 render
• csf-set-meta-component-explicitly — 始终设置 meta.component（自动文档、控件和类型都依赖它）
• csf-name-stories-by-state — 根据用户可见状态命名故事，而非根据属性值命名
• csf-tags-autodocs-on-meta — tags: ['autodocs'] 应放在 meta 上，而非单个故事上
• csf-co-locate-stories-with-component — 将 Component.stories.tsx 与 Component.tsx 放在同一目录
• csf-default-export-is-the-meta — 默认导出 = meta；具名导出 = 故事
• csf-title-hierarchy-for-design-systems — Meta title: 'Components/Inputs/Button' 分类体系（基础 / 组件 / 模式 / 示例）

3. Args、ArgTypes 与控件（高）

• args-derive-from-component-props — 让 argTypes 自动推断；仅声明无法推断的内容
• args-use-fn-for-callbacks — 对回调 args 使用 storybook/test 中的 fn()
• args-explicit-control-for-unions — 对无法推断的联合类型声明 control + options
• args-no-jsx-in-args — args 中不要包含 JSX；在 render 中组合 JSX
• args-pick-args-vs-parameters-vs-globals — args = 组件输入，parameters = 插件配置，globals = 工具栏状态

4. 装饰器与组合（高）

• deco-global-providers-in-preview — 将 Theme/QueryClient/Intl providers 放在 preview.ts 中
• deco-msw-for-network-mocks — 使用 MSW 模拟网络层；不要替换 SDK
• deco-mock-modules-with-subpath-imports — 通过 package.json#imports 模拟非网络模块
• deco-decorator-component-not-call — 将装饰器渲染为 <Story />，而不是 {story()}
• deco-context-aware-decorators — 从 context 中读取 globals 和 parameters，以创建响应式包装器
• deco-themes-addon-for-multi-brand — 使用 @storybook/addon-themes 的 withThemeByClassName/withThemeByDataAttribute 实现多品牌切换
• deco-rtl-direction-toggle — 工具栏中的 dir 切换开关，用 dir="rtl" 包装每个 story，以检测双向文本回归问题

5. 交互测试（高）

• test-import-from-storybook-test — 从 storybook/test 导入（Storybook 9+），而不是 @storybook/test
• test-await-every-userevent-call — 对每次 userEvent 调用都使用 await
• test-use-canvas-from-play-arg — 从 play 参数中解构出 canvas/userEvent
• test-fn-for-spied-callbacks — 使用 args: { onSubmit: fn() }，然后通过 expect(args.onSubmit).toHaveBeenCalledWith(...) 进行断言
• test-findby-over-waitfor — 优先使用 findByRole，而不是 waitFor + getByRole
• test-vitest-addon-for-ci — 在 CI 中通过 @storybook/addon-vitest 运行 play，而不是使用旧版 test-runner
• test-portable-stories-for-rtl — 通过 composeStories 在 RTL/Vitest 测试中复用 stories

6. 无障碍 — axe（高）

• axe-set-test-error-globally — 在 preview.ts 中设置 parameters.a11y.test = 'error'，作为真正的门禁
• axe-disable-rules-not-stories — 禁用特定规则；绝不要对整个 story 设置 test: 'off'
• axe-restrict-runonly-to-wcag-aa — 将 runOnly 限定为你的 WCAG 目标级别（通常为 AA）
• axe-context-for-portals — 为渲染到 portals 中的组件设置 parameters.a11y.context
• axe-globals-manual-for-intentional-violations — 为有意违反规则的 fixtures 设置 globals.a11y.manual: true

7. 文档与设计系统（中高）

• docs-autodocs-vs-mdx — 组件页面使用 Autodocs，跨主题文档使用 MDX
• docs-mdx-references-stories — 使用 <Canvas of={Story} />，而不是内联渲染
• docs-component-status-tags — 使用状态标签和侧边栏徽章展示生命周期
• docs-design-tokens-as-stories — 将设计令牌作为 stories 编写文档，以进行视觉回归测试
• docs-figma-link-via-design-addon — 通过 parameters.design 将每个 story 链接到对应的 Figma 画板

8. 构建、性能与部署（中）

• build-prefer-vite-over-webpack — 优先使用基于 Vite 的框架包，而非旧版 Webpack
• build-trim-test-bundle — 通过 main.ts 的 build.test 配置精简 Vitest-addon 测试构建
• build-deploy-static-build-to-shareable-host — 为每个 PR 将 storybook build 部署到 Chromatic/Vercel
• build-cache-storybook-in-ci — 在 CI 中缓存 Vite/Webpack 和 Playwright 层
• build-storybook-composition-refs — 在 main.ts 中使用 refs，将多包设计系统组合到一个主 Storybook 中
• build-manager-brand — 使用 create() 配置 .storybook/manager.ts，设置 Logo、品牌链接和侧边栏配色
• build-chromatic-modes-multi-theme — 通过 Chromatic modes 跨主题、视口和方向为每个 Story 创建快照

如何使用

• 从 references/_sections.md 开始，了解类别结构和影响原因。
• 如果你正在设置 Storybook，请阅读所有 config- 规则，然后阅读 csf- 规则。
• 如果你要编写新 Story，请阅读 csf- 和 args- 规则。
• 如果你想为 Story 添加测试，请阅读 test- 和 deco-msw-for-network-mocks。
• 如果你希望 a11y 违规导致 CI 失败，请阅读所有 axe- 规则。
• 如果你要从头构建设计系统，请按以下顺序阅读：config-tokens-css-vars-in-preview、config-story-sort-for-large-libraries、csf-title-hierarchy-for-design-systems、deco-themes-addon-for-multi-brand、build-manager-brand、build-chromatic-modes-multi-theme。然后阅读 docs-component-status-tags 和 docs-design-tokens-as-stories，了解治理和 Token 展示层。
• 如果你有一个多包单体仓库设计系统，请先阅读 build-storybook-composition-refs，然后按照上述设计系统路径阅读。
• 如果你需要 RTL / 多方向覆盖，请先阅读 deco-rtl-direction-toggle，然后阅读 build-chromatic-modes-multi-theme，将 RTL 接入视觉回归测试。
• 对于 gotchas.md：这里记录了随时间发现的故障模式；调试不常见问题前务必查看。
• 使用 assets/templates/_template.md 添加新规则。

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	添加新规则的模板
gotchas.md	随时间累积的故障模式
metadata.json	版本、参考资料、摘要

相关技能

• clean-code-ts-react — 底层组件设计质量（命名、函数结构、抽象）。
• react-testing-library — 在 Storybook 之外使用时的 RTL 查询和模式。
• web-interface-guidelines — 用于编写组件文档的 Vercel Web Interface Guidelines。