build-design-system

构建设计系统

术语见 references/glossary.md，禁用项和默认宽度见 references/taste.md。应用自身的外观就是设计来源。除非用户选择了设计来源并确认了示例，否则不要擅自添加应用中尚不存在的颜色、字体、阴影、渐变或动效数值。

脚本位于此技能的 scripts/ 中。请在仓库根目录下使用 node 运行，并先阅读 --help。scripts/capture.mjs 会在 scripts/capture-guard.mjs 后运行截图，后者会阻止所有写入；scripts/pixdiff.mjs 用于比较截图。运行 capture 和 pixdiff 需要 Playwright 和 Chromium；scripts/find-chromium.mjs 会查找 Chromium，或说明如何安装。

步骤

1. 确定方向。 阅读 AGENTS.md 或 CLAUDE.md、项目清单和路由树。用用户自己的措辞写下他们的抱怨、能回应这一抱怨的第一个可见改动，以及试点流程（优先选抱怨中提到的流程，否则选组件类别最多且包含错误状态表单的流程）。将 .design-system/ 加入 .git/info/exclude，确保笔记、截图或临时文件绝不会被提交。使用用户指定的分支作为运行分支；如果用户没有指定，则新建一个分支，并将起始分支写入 .design-system/start-branch，否则 land.mjs 会拒绝运行。向用户展示一次 references/taste.md，此时不要预选任何禁用项；将用户接受的版本保存为 .design-system/taste.md。不要再询问其他问题。采用默认选项，将其记录为 default (unanswered)，然后继续。 完成条件：已记录抱怨、试点流程、分支和接受的 taste 文件。

2. 盘点并建立基准。 列出每个界面、其状态，以及是否会写入数据。使用 scripts/check-system.mjs --no-allowlist --no-self-test --json 按出现次数统计原始值（#fff、text-gray-500、p-[13px]）。并将组件归类到各组件类别中。编辑前，按照最窄和最宽的受支持宽度（默认分别为 390 和 1280），为每个界面的每种状态截图；每种宽度都要进行一次全新导航。启动应用（此处端口为 3000）后，在 .design-system/surfaces.tsv 中按 surface<TAB>route<TAB>states 格式逐行列出每个界面，并将应用发送的每个写入请求按 METHOD URL 格式记录到 .design-system/writes.txt，内容从网络日志中复制。然后运行 node <this skill>/scripts/capture.mjs --base http://localhost:3000 --kind before --out .design-system/captures --surfaces .design-system/surfaces.tsv --writes .design-system/writes.txt。如果缺少 --writes（对于不发送写入请求的应用，则缺少 --no-backend），脚本会拒绝启动；它会在浏览器打开前验证每个写入请求都已被拦截，保存每张截图对应的无障碍树，并在有任何截图遗漏时以状态码 1 退出。删除所有无人使用的内容，并单独提交。 完成条件：每个界面都有基准截图，或已说明未截图的原因。

3. 设计令牌。 按用途对原始值聚类，为其命名，并将每个界面与其前景色配对（references/tokens.md）。持续运行 token-mapping，直到每个原始值都映射到某个用途、某项合并或列明的例外。容差范围内的合并属于既定决策。超出容差时，为每个聚类开启一个默认采用合并方案的审批项。在所有路由中，将每组相同值全部替换。
   完成条件：token-mapping 报告除例外清单之外没有遗漏，并且所有受替换影响的界面在容差为 0 时，pixdiff.mjs 的结果均为 0%。

4. 组件。 首先端到端构建使用最广泛的组件类别（references/components.md）。文本基元和小文本基元要与 Button 一同在第 1 波发布。使用 component-docs 为每个组件编写文档。将组件类别扩展到其他界面前，先向用户展示该组件类别；因为核心问题若在各屏幕采用设计系统后才被发现，就需要全面返工（例如：禁用字段仍显示为红色、Combobox 比 Input 高 2 px、面板操作按钮不换行、文件拖放无声失败）。 完成条件：每个规范组件都有登记表条目和文档；并且其禁用、必填、错误和长文本状态均已在展示页中截图并向用户展示。

5. 检查。 将 scripts/check-system.mjs 和 scripts/oklch.mjs 复制到仓库的 scripts/，运行 --init，然后运行一次 --init-allowlist。只有在规则被观察到失败后，才算验证过：在扫描文件夹中植入一个违规项，运行 --files <plant> --no-allowlist，确认退出码为 1 且指出了规则，然后删除这个植入项。允许列表和棘轮机制只会缩小。新增禁令时，必须在同一次变更中附带对应的检查规则。复制规则时，必须附带按元素限定的豁免，适用于必须保持原样的文本（引文、术语、版本字符串），以及供机器或人员粘贴到其他地方的载荷字符串（提示词、API 示例、剪贴板值），因为改写这些内容会改变其他人收到的内容。 完成标准：在干净克隆中检查退出码为 0，--self-test 以 "all as expected" 结束，并且本次运行新增的每条规则都曾在其植入项上观察到失败。

6. 试点。 使用逐块审阅过的 codemod 迁移试点流程。使用基线的命令、宽度、主题和数据采集迁移后的结果，只更改 --kind after，然后对两个文件夹运行 pixdiff.mjs。任何无法解释的差异都是缺陷。通过键盘走查流程，触发错误和加载状态，然后对迁移后的采集结果运行 ui-review。 完成标准：采集结果中的每个差异都能追溯到某项决策或门槛。没有采集到的渲染变更应标记为 checks-only。

7. 就绪情况。 在迁移范围扩大之前，以下五项审计必须全部通过，或记录豁免。

8. 交接。 重新统计数量。用数字报告系统覆盖的范围，先列出尚未确定的默认值，再按优先级列出已发现但未修复的问题。提出迁移方案并说明其规模。不要启动迁移。 完成标准：报告中的每个数字都注明生成该数字的命令。

就绪情况审计

屏幕开始使用系统后才发现缺口，需要全面排查；之前发现，则只需增加一行。请在第 5 步结束时以及第一波迁移开始前，再次运行以下审计。将每项结果连同一个判定词写入 .design-system/readiness.md。

1. 插槽和属性对等。 每个有调用点的旧版基础组件，其每个属性都必须在新版基础组件中有对应属性，或记录为缺口。
2. 行为契约。 为每个交互式基础组件编写一张“何时触发什么”的表格，每行对应一项测试（references/components.md）。
3. 语气对等。 将每个可按压和行基础组件与每种状态语气以及 muted 逐一组合。每个空白单元格都必须记录为缺口，或明确说明不支持。
4. 固定字符串。 每个旧版测试中按角色名称或文本查询的内容，都必须在新版基础组件中有默认名称和标签覆盖项。
5. 最复杂的屏幕。 每个系列中最复杂的调用点都必须在展示页中渲染，并附带截图。

尚未就绪的系列不得迁移。其屏幕继续使用旧版。

绝不

• 除非对方在本次会话中提出要求，否则不得推送、发布或部署。
• 不得在运行开始时所在的分支上提交。先切出运行分支。
• 不得在工作区有未提交更改时存储更改或切换分支。若工作区不干净，应使用独立工作树作为运行分支（git worktree add）。
• 不得删除其他软件包或公共 API 导出的任何内容。停止操作，并将其连同导入方一起列为门槛。
• 不得默默跳过步骤。如果应用无法构建或运行，报告必须写明 code-complete, not runtime-verified，并指出未测试的内容。
• 不得将自己的工作称为 verified。如果主机无法启动其他 Agent，则按顺序运行各步骤，重新审阅差异和采集结果来逐项检查，并将这些判定标记为 self-verified。

规则

• 原始值异味包括 #fff、rgb(、text-gray-500、p-[13px] 和 style={{ padding: 12 }}。每项都对应一个语义令牌或列出的例外。
• 缺少基础值时应新增差距行，绝不能在界面中用变通方案处理。
• 色彩差异在 delta E OK 2 内合并、间距差异在 2 px 内合并，属于决策。边框宽度、字重和缓动不设容差。
• 仅增加语义（名称、角色、aria-current）的变更属于决策。删除或重构语义的变更则属于门禁。
• 错误：{saving ? "Saving..." : "Save"}。正确：保留空闲状态下的标签，在同一容器内显示微调器，并设置 aria-busy。
• 同一修复再次出现时，应将其变成检查规则或脚本，而不是再添一句说明。
• 绝不编辑基线来让差异检查通过。若检查误报正确代码，应修正检查，并添加一个能证明修复有效的植入用例，绝不能靠改动代码来迁就检查。
• 未由脚本生成的计数，或从未见过失败的检查结果，都不得报告。

完成标准

在干净克隆的代码库中，所有规则都经过失败验证后，检查以 0 退出；生产构建中的每条路由均返回 200（capture.mjs --status）；试点与其基线一致，列出的预期变更除外；每项交接计数均由脚本生成。

references/traps.md 按 ID 列出行为陷阱。references/tokens.md 包含层级、名称、容差和动效预设。