product-to-storybook

产品到 Storybook

你的设计系统 Storybook 会孤立展示每个组件，却几乎不会展示这些组件所属的产品。因此，当你修改卡片或表格时，只能猜测后续会发生什么；想要不再猜测，唯一的办法就是逐个打开所有产品查看。

这项技能可以解决这个问题。它会分析现有产品，梳理其核心页面模板，并在 Storybook 中重建这些模板的代表性版本；只要产品已经使用了你的本地设计系统，就会沿用该系统。等所有产品都加入其中后，修改一个组件就能同时看到它对所有产品的影响；你也可以直接在 Storybook 中设计产品的下一个版本，不必担心后端问题。

这是一次补录。它生成的屏幕是页面模板，其中固定了具有代表性的内容，而不是每个 URL 的实时镜像。这样设计自有其目的：模板足够有代表性，可以作为设计依据，同时又足够独立，不会因其背后的任何内容而出问题。

这不是什么

• 不是 vibe-killer。 它会将定制页面转换为使用你的系统。此技能则会将产品屏幕迁移到 Storybook，并标出不属于系统的部分。它绝不会转换任何区域。如果你想转换这些被标出的区域，可以在之后运行 vibe-killer。
• 不是 ds-adoption-plan。 它会为迁移评估成本并安排时间。此技能则会生成你今天就能查看的屏幕，以及一份设计系统可能需要补齐的缺口清单。
• 不是原型制作工具。 它构建的每个屏幕都已存在。“这个产品还不存在”属于原型制作，而原型制作是另一项工作，使用的占位内容也不同。
• 不是生产环境工作。 它会编写 story 和 fixture，不会自行在你的库中编写配方、模式或组件。当产品包含非设计系统提供的 UI 时，它会询问你打算如何处理，并在执行任何操作之前记录你的决定。

基本原则

1. 以本地设计系统为准。 故事使用与其一同检出的系统版本渲染，而不是产品锁定的版本。这样才能看清波及范围。记录产品锁定的版本，并将本地已不存在的每个属性或插槽标记为差距清单中的版本偏移，而不是悄悄修正。
2. 使用模板，而不是 URL。 一个有 3,000 个页面的网站可能只有五种模板。找出这些模板及其排列组合（在合理范围内），并构建它们。编写任何故事之前，先向用户展示清单并获得确认，因为错误的分组是唯一会让整个流程白费的错误。
3. 使用真实内容，一次冻结。 每个故事都包含产品实际内容的一个切面，用来展示系统必须支持的内容形态：带 YouTube 嵌入内容的帖子、标题长达 60 个字符的卡片、含 40 个标签的列表。将内容连同日期和来源 URL 一起捕获到夹具中。绝不使用 lorem，也绝不实时获取。
4. 绝不使用真实人物的数据。 登录后的屏幕使用根据数据结构编写的夹具，而不是任何人的账户数据。如果捕获内容中发现真实用户数据，立即停止、删除数据并说明情况。这是停止条件，不是警告。
5. 所有内容都要标记。 故事中的每个区域都要注明来源：data-origin="system"、data-origin="product" 或 data-placeholder="missing-component"。reference/MARKERS.md 规定了标记约定。差距清单根据这些标记生成，因此忘记标记的区域会成为你永远看不到的差距。
6. 产品 CSS 各守其位。 产品自身样式表提供的所有内容都要用 @scope 包裹，并且只在该产品的故事中加载。然后验证这一点：分别渲染设计系统故事，确认前后没有变化。波及范围从系统向外延伸，绝不会从产品反向影响系统。
7. 出现一些差异是意料之中的，也要明确说明。 基于本地系统构建的故事看起来应该与线上页面略有不同，因为本地系统比产品锁定的版本更新。并排报告会展示两者，并清楚说明哪些差异属于版本偏移，哪些是技能本身出了问题。
8. 刷新时绝不覆盖任何内容。 后续运行会报告发生的偏移并征求确认。用户可能是有意重新设计了该屏幕。

运行流程

模式 1 — 为产品补建故事

1. Storybook 接入（intake/STORYBOOK-INTAKE.md），每个设计系统执行一次。了解该 Storybook 如何编写故事、产品屏幕应放在哪里，以及系统如何加载。如果 product-to-storybook/STORYBOOK.md 已存在且内容为最新，则跳过此步骤。
2. 产品接入（intake/PRODUCT-INTAKE.md），每个产品执行一次。包含五个问题，每个问题都有默认答案。将答案记录在产品的 GARAGE.md 中，确保刷新时不再重复提问。
3. 阶段 1 — 清单（phases/phase-1-inventory.md）。找出模板及其排列组合。停止并向用户展示。 等待确认。
4. 阶段 2 — 捕获（phases/phase-2-capture.md）。选择内容切面，并将其冻结到夹具中。
5. 阶段 3 — 迁移（phases/phase-3-relocation.md）。编写故事。产品使用系统组件的地方就使用系统组件，其他地方都标记区域，并对产品 CSS 使用作用域限定。
6. 阶段 4 — 验证（phases/phase-4-proof.md）。渲染并排比较，验证系统自身的故事没有变化，编写差距清单和报告。

模式 2 — 刷新（偏移检查）

phases/refresh.md。重新读取产品，并与 Storybook 中的内容进行比较，报告变更：新增或移除的模板、发生变化的排列组合、锁定版本升级，以及不属于系统的新 UI。生成偏移报告，不做其他任何更改。

模式 3 — 构建或更新 Storybook 档案

单独运行 intake/STORYBOOK-INTAKE.md。当 Storybook 升级到新的主版本、故事开始被放到错误的分区，或系统的加载顺序发生变化时，就该采取这一步。

了解产品

可以是源代码仓库、线上 URL，或两者兼有。intake/PRODUCT-INTAKE.md 的问题 1 会用用户看到的措辞说明各自的价值。记录你使用了哪一种；所有下游产物都会注明这一点。

文件放在哪里

故事放在设计系统仓库中，存入用户选择的 Storybook 分区（默认：Products/<product>/）。每个模板对应一个故事文件，排列方式作为其中命名的故事；每个模板都以一个有代表性的 Default 开头。测试数据与故事文件放在一起。

过程记录存放在设计系统仓库的根目录：

product-to-storybook/
├── STORYBOOK.md                     ← how this Storybook works, built once
├── markers.css                      ← the origin/placeholder stylesheet
└── <product>/
    ├── GARAGE.md                    ← intake answers, source, pinned version
    ├── INVENTORY.md                 ← templates and permutations, confirmed
    ├── GAPS.md                      ← the gap ledger
    ├── REPORT.md                    ← side-by-side proof, what was verified
    └── drift/
        └── YYYY-MM-DD.md            ← one per refresh

与任何 ds-inspection/、vibe-killer/ 或 ds-adoption-plan/ 文件夹同级。如果产品仓库中有来自相关技能的 adoption-plan/MAPPING.md 或 product-inspection/GARAGE.md，请先阅读。这些文件已经说明哪些区域属于系统、哪些是自定义内容；你需要根据渲染后的页面确认，而不是从头开始。

本工具包中的文件

• intake/STORYBOOK-INTAKE.md — 了解宿主 Storybook，仅一次
• intake/PRODUCT-INTAKE.md — 五个问题，每个产品回答一次
• phases/phase-1-inventory.md — 模板和排列方式，然后进行检查点确认
• phases/phase-2-capture.md — 内容横截面，冻结
• phases/phase-3-relocation.md — 编写故事
• phases/phase-4-proof.md — 渲染、比较、验证并报告
• phases/refresh.md — 漂移检查
• reference/MARKERS.md — 来源与占位符约定
• reference/CAPABILITIES.md — 此技能能做和不能做的事
• templates/ — 过程记录中每个文件的输出模板

表达风格

朴实、有活力、具体。清单是一份带数量的模板列表。差异记录表是一张带截图的表格。报告要说明渲染了什么、哪些内容匹配、哪些内容发生了变化，以及原因。读者看完后应能准确了解哪些屏幕现在已加入 Storybook，哪些区域并非来自系统，以及该如何处理。