storybook

Storybook

当工作涉及 Storybook 10（或升级到该版本）时，请使用此技能：包括 stories、CSF、配置、文档、交互/无障碍/视觉测试、Vitest addon、可移植 stories、框架包、Agent/MCP 工具，或从 8.x/9.x 迁移。

工作流

1. 修改代码前，先检查本地 Storybook 的情况：
   • storybook、框架包（例如 @storybook/react-vite、@storybook/nextjs-vite）、@storybook/addon-docs、@storybook/addon-a11y、@storybook/addon-vitest、Node、Vite/Vitest，以及 React/Vue/Svelte 对等依赖的版本。
   • 配置：.storybook/main.ts|js（必须使用 ESM）、preview.ts|tsx、可选的 manager.ts、vitest.setup.ts、story glob、staticDirs。
   • Story 风格：CSF3 Meta/StoryObj、实验性的 CSF Next（definePreview / preview.meta / meta.story）、MDX 文档、标签。
   • 测试路径：Vitest addon、旧版 test-runner、可移植的 composeStories、Chromatic/视觉测试、无障碍测试。
2. 版本不明确，或工作涉及升级、ESM、CSF Next 或 Vitest 浏览器模式时，更新查阅最新文档。从 source-map.md 开始。
3. 安装、框架、main/preview、核心功能与 addons，以及 CLI，请使用 setup-core.md。
4. CSF3/CSF Next、args、render、decorators、parameters、标签和文档，请使用 writing-stories.md。
5. play、storybook/test、Vitest addon、可移植 stories 和无障碍测试，请使用 testing.md。
6. 构建、CI、doctor/upgrade、8→9→10 包迁移、AI/MCP 工具和常见故障，请使用 production-migration.md。

实施判断

• 除非仓库有意固定版本，否则以 Storybook 10 为目标。类型/导入优先使用框架包（@storybook/react-vite），而不是孤立的仅渲染器包。
• 默认编写 CSF3（satisfies Meta、StoryObj）。将 CSF Next 视为选择启用的实验性功能；未经批准，不要重写稳定的 CSF3 代码库。
• 从 storybook/test 导入测试工具（从 storybook/manager-api / storybook/preview-api 导入 manager/preview API）。不要重新引入 @storybook/test、@storybook/addon-interactions 或 @storybook/addon-essentials。
• Controls、actions、viewport 和 interactions 属于 core。需要这些功能时，安装 @storybook/addon-docs、@storybook/addon-a11y 和 @storybook/addon-vitest。
• 对于 Vite React/Vue/Svelte 项目，优先使用 @storybook/addon-vitest，而不是 @storybook/test-runner。Next.js 使用 Vitest addon 时需要 @storybook/nextjs-vite。
• 将 stories 与组件放在一起。优先使用 args + Controls，而不是 story 局部的 React state；使用 play 进行交互和断言。
• 有目的地使用标签（autodocs、!autodocs、!test、自定义筛选器）。meta 上的 titles/component 必须能静态分析。
• AI 工具（@storybook/addon-mcp、storybook skills / storybook tools）在 10.6 中仅供预览。仅在用户要求时添加；docs 工具集需要 features.componentsManifest: true。
• Storybook 11 目前为 alpha（next）；除非仓库选择启用，否则请使用 10.x。
• .storybook/main.* 必须是有效的 ESM（不能使用 require / __dirname）。路径计算请使用 import.meta.url。

验证

优先使用仓库现有的检查。对有实质影响的 Storybook 更改，请执行相关检查：

• 运行 bun run storybook（或项目脚本），检查 stories 能否编译和渲染。
• 更改 main 配置、框架、Vite 别名或 ESM 边界时，运行 bunx storybook build。
• 升级后或 @storybook/* 版本不匹配时，运行 bunx storybook doctor。
• 更改 play/无障碍/覆盖率时，运行针对性的 Vitest story 项目（vitest --project=storybook）或 UI 测试小组件。
• 对 Meta/StoryObj、框架导入和 storybook/test 用法进行类型检查。
• 如果仓库中有视觉/Chromatic 或无障碍测试流水线，则执行相应的冒烟测试。