storybook-to-product

从 Storybook 到产品

你直接在 Storybook 中，使用设计系统的真实组件和真实内容，设计出了产品的下一版本，过程中无需处理后端问题。它看起来已经完成了。这是前端最前沿的代码，基本已可用于生产环境。

基本如此。从这个 story 到线上产品之间，还隔着 Storybook 从未需要处理的一切：产品自身的模板语言、数据文件、点击缩略图时打开的模态框、向无服务器函数提交的表单、有人为填充设计而编写的文案，以及新组件尚未发布的设计系统版本。

这项技能将弥合这段距离。它会评估工作，将标记和样式迁移到产品自己的语言中，将它们连接到背后的所有功能，并验证产品现在与设计稿一致。最终，它会创建一个拉取请求，并准确记录每个 story 发布时所用的版本，这样下一轮 Storybook 调整就能通过补齐差异来跟进，而不必从头重做。

这不是什么

• 不是 product-to-storybook。 那项技能会将产品现有的屏幕迁入 Storybook。这项技能则会将屏幕从 Storybook 中取出，放进生产环境。两者配合使用：如果某个 story 来自 product-to-storybook，这项技能会读取其记录，大部分问题都能直接找到答案。
• 不是 ds-adoption-plan。 那项技能会从产品出发，规划将产品定制 UI 迁移到设计系统中的方案。这项技能则从已完成的设计出发，评估将其发布所需的工作。它会借用采用计划中的工作量等级，让两者的估算标准一致。
• 不是 vibe-killer。 那项技能会使用设计系统重建单个页面。这里的页面已经使用设计系统构建完成，任务是将它部署到生产环境。
• 不是发布工具。 它绝不会发布设计系统、合并代码或部署应用。

基本原则

1. 故事是规范，产品是目标。 故事决定渲染什么。产品决定如何编写：使用什么模板语言、文件名、CSS 架构和类名。如果交接让产品看起来像 Storybook 代码，产品维护者就会撤销这些改动。
2. 动手之前先评估。 每个区域都要确定处理方式，每种行为都要命名，每项系统依赖都要检查，并且这些工作必须在修改任何产品文件之前完成。评估结果要展示给用户并经其确认，因为错误地移除内容，可能会删掉业务仍然需要的东西。
3. 不得发布虚构内容。 测试数据会混合真实文案和仅用于填充版式的占位内容。每个字段都要注明来源并确定处理方式；在宣布完成之前，还要搜索构建产物，检查其中是否存在所有虚构值。这项技能要防止的唯一结果，就是让虚构人物出现在正式页面上。
4. 内容和媒体由用户决定。 根据证据为文案提供默认值。每张图片和每段视频都要询问用户。
5. 尚未发布的内容必须询问。 如果故事依赖产品尚无法安装的设计系统改动，这项技能就会停止并询问如何处理。绝不会让产品使用本地设计系统副本。
6. Storybook 内容不得泄漏到生产环境。 来源标记、@scope 封装器、装饰器和残留测试数据都必须清除，然后通过搜索构建产物来证明它们已被清除。
7. 每个触发器都必须有对应目标。 Storybook 只展示交互的外观，不包含行为。每个模态框、表单、切换控件和链接都必须接入功能，并在真实浏览器中逐一检查。
8. 以产品自身的规则为准。 产品仓库中的 CLAUDE.md、AGENTS.md 或流程配置，其优先级高于此处的任何规则，包括如何创建分支、提交和发布。此项技能会遵循这些规则，无需询问；只有用户明确要求时才会偏离。
9. 流程止于拉取请求。 合并和部署始终由人工负责，即使所有检查都通过也不例外。
10. 追赶更新时不得覆盖内容。 如果某个字段在 Storybook 和生产环境中都发生了变化，就构成冲突，必须由人工决定。线上改动可能才是正确的。

执行流程

模式 1：交接

1. 信息收集（intake/HANDOFF-INTAKE.md）。提出三个问题，每个问题都提供一个默认值。将答案记录在产品仓库的 storybook-to-product/HANDOFF.md 中。
2. 阶段 1：评估（phases/phase-1-assessment.md）。梳理每个区域，检查每项系统依赖，列出每种行为并估算工作量。如果涉及发布门槛问题，就提出该问题。停止并向用户展示结果。 等待回复。
3. 阶段 2：内容（phases/phase-2-content.md）。标注每个字段的来源，提出默认值，并汇总后一次性询问。每项资源都要询问。
4. 阶段 3：集成（phases/phase-3-integration.md）。升级设计系统，将标记语言转换为产品格式，将样式移植到产品中，并移除已确认要淘汰的内容。
5. 阶段 4：接线（phases/phase-4-wiring.md）。处理数据、行为、表单、链接、页面外围文档以及链接记录。
6. 阶段 5：验证（phases/phase-5-proof.md）。构建、搜索泄漏内容、将产品与故事并排对照、测试每种行为、运行 axe、生成报告并创建拉取请求。

模式 2：追赶更新

phases/catch-up.md。读取链接记录，找出自已发布版本以来故事中的所有更改，检查交接后生产环境中的改动，并在独立的拉取请求中同步差异。

文件放在哪里

产品代码在产品仓库的分支上，遵循产品自身的约定进行修改。

过程记录保存在产品仓库的根目录：

storybook-to-product/
├── HANDOFF.md                ← intake answers, both versions, runs
├── ASSESSMENT.md             ← regions, dependencies, behaviors, estimate
├── CONTENT.md                ← every field and asset, with its decision
├── REPORT.md                 ← what was proven, side by sides
├── links.json                ← which story version is in production
└── catch-up/
    └── YYYY-MM-DD.md         ← one per catch-up

与任何 ds-adoption-plan/ 或 product-inspection/ 文件夹同级。如果需求来自 product-to-storybook，则先阅读设计系统仓库中的过程记录（product-to-storybook/<product>/），工作合并后再添加一条 交接 说明。reference/LINKS.md 说明了双方如何保持关联。

套件中的文件

• intake/HANDOFF-INTAKE.md：三个问题，以及那些需要等待合适时机再问的问题
• phases/phase-1-assessment.md：区域、依赖项、行为、估算，然后是检查点
• phases/phase-2-content.md：逐字段说明要发布哪些内容
• phases/phase-3-integration.md：使用产品自身的语言编写标记和样式
• phases/phase-4-wiring.md：数据、行为、表单、链接
• phases/phase-5-proof.md：构建、渲染、测试、报告、拉取请求
• phases/catch-up.md：同步后续的 Storybook 更改
• reference/TRANSLATION.md：将 Storybook 结构映射到产品模板
• reference/LINKS.md：Storybook 与产品之间的连接纽带
• reference/CAPABILITIES.md：此技能能做什么，不能做什么
• templates/：过程记录中每个文件的输出模板

文风

直白、有活力、具体。评估内容以表格列出各个区域及其处置意见，并在底部给出数字。内容清单将两种取值并排展示。报告说明构建了什么、验证了什么，以及还有哪些事项在等待某人处理。读者读完后应该能准确了解拉取请求包含什么、需要他们决定什么，以及是否已准备好发布。