# Storybook source shape / Storybook 源形态 Storybook is the **fidelity oracle, not the runtime**. The converter bundles the package's compiled `dist/` into `_ds_bundle.js` - the same bundle the claude.ai/design agent builds with - and generates each preview by **compiling the story source module itself** (hooks, fixtures, local helpers - the whole closure comes along), with every component import resolved to that shipped bundle (`lib/story-imports.mjs` redirects package *and* relative component imports to `window.`). The repo's own storybook render is the ground truth those previews must match: a compare harness screenshots each story in the reference storybook and the matching preview render side by side, and you iterate until they match. Nothing from storybook-static is uploaded, and no story code is ever evaluated at build time - stories run only in the browser, against the real artifact. Storybook 是**保真度基准（oracle），而非运行时**。转换器把软件包编译后的 `dist/` 打包进 `_ds_bundle.js`——与 claude.ai/design 智能体构建所用的 bundle 相同——并通过**编译 story 源码模块本身**（hooks、fixtures、本地辅助函数——整个闭包一并带上）来生成每个预览，所有组件导入都解析到该随包 bundle（`lib/story-imports.mjs` 把包导入*和*相对路径组件导入都重定向到 `window.`）。仓库自身的 storybook 渲染是这些预览必须匹配的基准真值：一个比对工具会并排截取参考 storybook 中每个 story 的截图与对应预览的渲染截图，你持续迭代直到二者一致。storybook-static 的任何内容都不会上传，story 代码也绝不在构建时求值——story 只在浏览器中、针对真实制品运行。 【评论】该文档把 Storybook 定位为"保真度基准"而非运行时，并以截图比对作为核心验收手段，属于典型的视觉回归测试（visual regression）设计思路。 Requires React 18+. Playwright + chromium are **required** for this shape (the compare loop is the verification), not optional. 要求 React 18+。对于此形态，Playwright + chromium 是**必需**的（比对循环本身就是验证手段），并非可选项。 **First sync or re-sync?** A re-sync is marked by a config whose `projectId` and `pkg` were both in place before this run started - most of this document then doesn't apply; go to §7, where one driver run routes the work and untouched components cost nothing. Everything else takes the full flow (§2 build -> §3 self-heal -> §4 match -> conventions header (base SKILL.md, before upload) -> §6 upload), where every component gets verified and graded once - that includes a partial config left by an aborted run, and a pin this run itself just recorded in the base skill's §1. (Only the old `design-sync.config.json` present? Move it first and commit: `mkdir -p .design-sync && mv -n design-sync.config.json .design-sync/config.json`, then apply the same test.) **首次同步还是重新同步？**重新同步的标志是：配置中的 `projectId` 与 `pkg` 在本次运行开始前就已就位——此时本文档大部分内容不再适用；转至 §7，在那里一次 driver 运行即可调度全部工作，未改动的组件零成本。其余情况都走完整流程（§2 构建 -> §3 自愈 -> §4 匹配 -> 约定头部（基础 SKILL.md，上传前）-> §6 上传），其中每个组件都要被验证并评分一次——这包括被中止运行留下的不完整配置，以及本次运行刚刚在基础技能 §1 中记录的 pin。（只存在旧的 `design-sync.config.json`？先移动并提交：`mkdir -p .design-sync && mv -n design-sync.config.json .design-sync/config.json`，然后再套用同一判据。） ## 2. Build, then run the converter / 构建，然后运行转换器 1. **Build the DS package *and its workspace dependencies*.** The converter bundles `dist/` into `window.`. Run ` run build`; in a monorepo use `turbo run build --filter=` or `pnpm -F "..." build` (the trailing `...` is required - bare `-F ` skips dependencies and you'll see `Cannot find module '@scope/tokens'`). If `package.json` `module`/`exports['.']` points at TS source, find the actual built entry and pass it via `--entry`. **Do this before step 2** - storybook often imports sibling packages from their built `dist/`. 1. **构建 DS 包*及其工作区依赖*。**转换器把 `dist/` 打包进 `window.`。运行 ` run build`；在 monorepo 中使用 `turbo run build --filter=` 或 `pnpm -F "..." build`（末尾的 `...` 是必需的——裸 `-F ` 会跳过依赖，你会看到 `Cannot find module '@scope/tokens'`）。如果 `package.json` 的 `module`/`exports['.']` 指向 TS 源码，找到实际构建产物入口并通过 `--entry` 传入。**在第 2 步之前完成此步**——storybook 经常从兄弟包已构建的 `dist/` 导入。 2. **Build the reference storybook ONCE into `.design-sync/sb-reference/`** - NOT under `ds-bundle/` (the converter wipes `--out` on every rebuild, and storybook builds take minutes; the reference must survive the fix loop): 2. **把参考 storybook 构建一次到 `.design-sync/sb-reference/`**——不要放在 `ds-bundle/` 下（转换器每次重建都会清空 `--out`，而 storybook 构建耗时数分钟；参考构建必须在修复循环中幸存）： ```bash npx storybook build -c -o .design-sync/sb-reference ``` Run it from the directory whose `package.json` has the storybook devDependencies - usually the one containing `.storybook/`; monorepos often have several storybooks, so pick the one covering the package you're syncing. **Make `-o` the repo-root path** (e.g. `-o "$(git rev-parse --show-toplevel)/.design-sync/sb-reference"`): the converter and compare resolve `.design-sync/` from the repo root, so a cwd-relative `-o` in a subpackage puts the reference where nothing will find it. Use `npx storybook build` directly, **not** the repo's `npm run build-storybook` script (wrong output dir). Then check `.design-sync/sb-reference/iframe.html` exists and is >10KB - `index.json` alone can exist with a failed build. 在 `package.json` 含有 storybook devDependencies 的目录中运行——通常是包含 `.storybook/` 的那个目录；monorepo 常有多个 storybook，应选择覆盖你正在同步的软件包的那一个。**把 `-o` 设为仓库根路径**（例如 `-o "$(git rev-parse --show-toplevel)/.design-sync/sb-reference"`）：转换器与比对工具都从仓库根解析 `.design-sync/`，因此在子包中使用相对 cwd 的 `-o` 会把参考构建放到无人能找到的位置。直接使用 `npx storybook build`，**不要**用仓库的 `npm run build-storybook` 脚本（输出目录不对）。然后检查 `.design-sync/sb-reference/iframe.html` 存在且大于 10KB——仅有 `index.json` 也可能出现在构建失败的情况下。 Long builds: background them **through your shell tool's background mode only** and wait for the completion notification. Never a bare `&` (untracked - the notification never comes), and never a `pgrep -f '