migrate-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrate to a design system

迁移到设计系统

The system is settled. One coordinator splits the app into surfaces and runs worker agents one surface at a time, with behavior unchanged. The same skill runs as an audit that ends at a plan. Sibling skill paths start at

<skills>

. Surface, run branch, identical-value swap, decision, gate, clearance, footprint and

<skills>

mean what

build-design-system/references/run-record.md

(Terms) says.

It never designs the system. A missing token or component is a request to the system's owner. It does not change product behavior or deploy unless the standing orders grant it. No editing worker starts before

frame.md

states a budget.

A writing run lands every surface, and every decided gate default, on the run branch (

ds/<yyyy-mm-dd>-migrate

unless one is named), so Next is a plain merge. Moving surfaces beyond identical-value swaps and decided defaults needs clearance, and each visible change needs a gate or decision, before and after captures and a montage row (

references/verification.md

系统已确定。一名协调Agent将应用拆分为多个surface，每次在一个surface上运行工作Agent，且保持行为不变。同一技能可作为审计模式运行，最终输出一份计划。同级技能路径从

<skills>

起始。Surface、run branch、identical-value swap、decision、gate、clearance、footprint 和

<skills>

的含义以

build-design-system/references/run-record.md

（术语表）中的定义为准。

本技能绝不设计系统。缺失的token或组件需向系统所有者提出申请。除非常设指令授权，否则不得更改产品行为或进行部署。在

frame.md

明确预算之前，不得启动任何编辑类工作Agent。

写入式运行会将所有surface及所有已决定的gate默认值落地到run branch（若未指定则为

ds/<yyyy-mm-dd>-migrate

），因此下一步只需直接合并。对surface的修改若超出identical-value swap和已决定默认值的范围，需要获得clearance；每一项可见变更都需要对应一个gate或decision，且需包含变更前后的捕获截图以及montage行（见

references/verification.md

）。

When a coordinator calls it

当协调Agent调用本技能时

A coordinator may pass the system location, scope, pilot, budget or a run folder. Use what it gives, default the rest from Inputs, and park questions in

gates.md

. A boss that takes this seat on a host without subagents records that as one decision row. The reply starts with the status line, then

Commit: <run branch head>

, then the final report,

plan.md

in audit mode, or the stop shape below. Audit mode can run beside the build (

references/inventory.md

, Audit mode and plan.md).

协调Agent可传入系统位置、范围、试点、预算或运行文件夹。使用传入的参数，其余参数从输入项中取默认值，疑问暂存到

gates.md

中。若在没有子Agent的宿主上由boss承担此角色，需将其记录为一条decision行。回复首先包含状态行，然后是

Commit: <run branch head>

，接着是最终报告（审计模式下为

plan.md

），或下文的停止状态说明。审计模式可与构建并行运行（见

references/inventory.md

中「审计模式与plan.md」部分）。

Done

完成条件

Done means the predicate in

frame.md

holds on the final integration commit, proved from the run folder.

The inventory script's
```
--check
```
exits 0 there: zero legacy imports, zero raw values outside
```
allowlist.tsv
```
, zero palette uses when
```
frame.md
```
counts them, zero legacy files.
Every row in
```
queue.tsv
```
is
```
landed
```
with a
```
verified
```
or
```
self-verified
```
ledger row at that commit. A verdict at a surface's branch commit or a reopened row does not count.
The rule that blocks new legacy usage fails CI on a planted violation, and exits 0 at every handoff with the remaining findings in its committed ignore list (
```
references/inventory.md
```
). A red check at handoff is a failed run.
```
baselines/MANIFEST.sha256
```
still matches, and the forbidden-path check passed on every landed diff.
Every spawned agent has a terminal row in
```
agents.tsv
```
, and every
```
decisions.tsv
```
row points at evidence that resolves.
Every fix that recurred became a check, or the report says why it could not.
Every gate is
```
applied
```
,
```
open
```
and listed with its default, or
```
decided
```
and listed as not landed with its reason.

The first commit that changes a surface fixes the complaint quoted in

frame.md

(run-record, Frame), and every claim names its command (standing order 6).

The final message is the four-part handoff in run-record (Handoff report), with migrate's counts and Next from

close.md

(

references/run-folder.md

, close.md).

If it stops, return the rule that stopped it, the count verified so far, the run folder path, the first action on resume, and the smallest reply that unblocks it.

完成意味着

frame.md

中的判定谓词在最终集成提交上成立，且可通过运行文件夹中的内容证明。

清单脚本的
```
--check
```
命令在此处退出码为0：无遗留导入、
```
allowlist.tsv
```
外无原始值、若
```
frame.md
```
要求统计则无调色板使用、无遗留文件。
```
queue.tsv
```
中的每一行都处于
```
landed
```
状态，且在该提交下有对应的
```
verified
```
或
```
self-verified
```
台账行。在surface的分支提交上的结论或已重新打开的行不计入。
阻止新增遗留使用的规则在植入违规项时会使CI失败，且在每次交接时退出码为0，剩余问题记录在已提交的忽略列表中（见
```
references/inventory.md
```
）。交接时若检查不通过，则运行失败。
```
baselines/MANIFEST.sha256
```
仍匹配，且所有已落地的diff都通过了禁止路径检查。
每个生成的Agent在
```
agents.tsv
```
中都有终止行，且
```
decisions.tsv
```
的每一行都指向可解决的证据。
所有重复出现的修复都已转化为检查项，否则报告中会说明无法转化的原因。
所有gate要么处于
```
applied
```
/
```
open
```
状态并列出其默认值，要么处于
```
decided
```
状态并列出未落地的原因。

首次修改某个surface的提交需修复

frame.md

（run-record，Frame）中引用的问题，且每项声明都需指明其对应的命令（常设指令第6条）。

最终消息为run-record中定义的四部分交接内容（交接报告），包含迁移计数以及来自

close.md

的下一步操作（见

references/run-folder.md

中close.md部分）。

如果运行停止，需返回导致停止的规则、目前已验证的数量、运行文件夹路径、恢复时的首个操作，以及可解除阻塞的最小可行回复。

Inputs

输入参数

Input	Required	If missing
The target system: token source, components, docs, and a version or commit	Yes	Find it per `references/inventory.md` (Finding the target system) and pin the commit in `frame.md`
The app repo, able to build and run	Yes	Stop if it cannot build, except in audit mode. If it cannot run, offer audit mode only, since nothing can be verified.
Scope	No	Everything the inventory finds, listed in `frame.md` for the person to trim
Pilot surface	No	The one the person complained about, else the one with the most system components and a failure state
Budget	No	The session, stated in `frame.md`
Widths and themes	No	The app's narrowest and widest widths, default 390 and 1280, and every theme it ships
Parity mode, `exact` or `mapped`	No	`mapped` when system values differ from legacy ones ( `references/verification.md` )
Parallel agents with worktree isolation	No	`references/platforms.md`
A visual test harness	No	`capture.mjs` , run in the CI environment

Project instructions (AGENTS.md, CLAUDE.md) seed the standing orders. With about five surfaces or fewer, one worker runs the phases in sequence, still with the inventory, baselines, ledger and predicate, because a window costs more than it saves.

输入项	必填	缺失时处理
目标系统：token源、组件、文档，以及版本或提交号	是	按照 `references/inventory.md` （查找目标系统）中的说明查找，并在 `frame.md` 中固定提交号
可构建并运行的应用仓库	是	若无法构建则停止（审计模式除外）。若无法运行，则仅提供审计模式，因为无法进行任何验证。
范围	否	清单发现的所有内容，列于 `frame.md` 中供人员裁剪
试点surface	否	用户反馈有问题的surface，若没有则选择系统组件最多且存在失败状态的surface
预算	否	当前会话，在 `frame.md` 中说明
宽度与主题	否	应用的最小和最大宽度，默认390和1280，以及应用自带的所有主题
一致性模式， `exact` 或 `mapped`	否	当系统值与遗留值不同时使用 `mapped` （见 `references/verification.md` ）
带worktree隔离的并行Agent	否	见 `references/platforms.md`
视觉测试框架	否	`capture.mjs` ，在CI环境中运行

项目说明（AGENTS.md、CLAUDE.md）为常设指令提供初始内容。当surface数量约为5个或更少时，由一个工作Agent按顺序执行所有阶段，仍需包含清单、基线、台账和判定谓词，因为并行窗口的开销大于收益。

Procedure

执行流程

Default every row above and present

frame.md

once, asking only where no default is safe. Inventory is read-only and starts meanwhile. Read

references/orchestration.md

and

references/run-folder.md

before Frame. Each exit condition is proved by a run-folder file.

Frame. Create
```
.migration/<run>/
```
and write
```
frame.md
```
and
```
standing-orders.md
```
(
```
references/run-folder.md
```
). Exit when every field is filled or has a stated default, before any spawn.
Inventory. One agent builds or reuses the inventory script and the lint rule that blocks new legacy usage, and mappers run
```
token-mapping
```
per surface (
```
references/inventory.md
```
). Ambiguous rows become gates. Exit when
```
inventory/counts.txt
```
has the counts, every finding has a surface, and the rule fails on a planted violation. Audit mode adds no rule, writes
```
plan.md
```
, and stops.
Baselines. One agent captures and measures every surface before any edit (
```
references/verification.md
```
, Baselines). Exit when every surface has a baseline or a stated
```
not captured
```
reason, and the manifest is written.
Shared layer. One agent, alone, lands what every surface needs (
```
references/inventory.md
```
, The shared layer). Nobody touches those files afterwards. Exit when the layer has landed, the runtime checks pass, and every baseline still matches or its diffs are explained.
Pilot. Brief the pilot from
```
references/worker-brief.md
```
and run it end to end: worker, verifier, ledger row, landing. Fix what it exposed in the template. Exit when the pilot is
```
verified
```
and landed, and the template changes are logged.
Build the codemod. Turn the pilot's recipe into a codemod, run it on the pilot's starting commit and diff the result against the hand migration. What it misses goes in the brief. The codemod and
```
codemod/RECIPE.md
```
stay outside every worker's write scope. Exit when that diff is recorded and a second run is a no-op.
Fan out. Run a rolling window under the cap in
```
frame.md
```
(
```
references/orchestration.md
```
), one surface per worker, each with its own branch and worktree (or the fallback in
```
references/platforms.md
```
) and a brief with every field filled. Exit spawning at about 70% of the budget (
```
references/orchestration.md
```
, Budget and stopping).
Verify each surface. A verifier that did not write the code checks the visual diff, rendered checklist, accessibility snapshot, behavior and its delta, and runs
```
design-review
```
(
```
references/verification.md
```
). Without subagents the coordinator self-verifies by the checklist there. Exit per surface when the ledger has a verdict for its current commit.
Integrate continuously. Land each verified surface on the run branch as its own commit with its captures. A conflict becomes a unit for a worker. After each landing, run the integration checks. A red integration build stops landing until it is green.
Delete legacy. When a legacy module has zero callers, one unit deletes it, its adapter and its allowlist rows in one change, and the lint rule bans the path. Anything imported from outside the repo waits at a gate.
Close. Run a last drain, recapture every surface at the final integration commit, and give each reopened row a new verdict there. Spend budget left on verifiers for
```
checks-only
```
,
```
self-verified
```
and reopened surfaces. Write
```
close.md
```
, audit
```
decisions.tsv
```
, turn each recurring fix into a check (
```
references/orchestration.md
```
), and clear scratch files. Exit when the predicate holds or the report names what is left.

为上述所有输入项设置默认值，一次性生成

frame.md

，仅在无法安全设置默认值时才询问用户。清单操作是只读的，可同时启动。在Frame阶段前需阅读

references/orchestration.md

和

references/run-folder.md

。每个退出条件都需由运行文件夹中的文件证明。

Frame。 创建
```
.migration/<run>/
```
目录，编写
```
frame.md
```
和
```
standing-orders.md
```
（见
```
references/run-folder.md
```
）。在生成任何子Agent前，当所有字段都已填写或已声明默认值时，退出此阶段。
Inventory。 由一个Agent构建或复用清单脚本以及阻止新增遗留使用的lint规则，映射器为每个surface运行
```
token-mapping
```
（见
```
references/inventory.md
```
）。含义不明确的行转化为gate。当
```
inventory/counts.txt
```
包含统计数据、每个问题都对应一个surface、且规则在植入违规项时会失败时，退出此阶段。审计模式下不添加规则，编写
```
plan.md
```
后停止。
Baselines。 由一个Agent在进行任何编辑前捕获并测量每个surface（见
```
references/verification.md
```
基线部分）。当所有surface都有基线或已声明「未捕获」原因，且Manifest已编写完成时，退出此阶段。
Shared layer。 由一个Agent单独落地所有surface都需要的内容（见
```
references/inventory.md
```
共享层部分）。之后任何人不得修改这些文件。当共享层落地、运行时检查通过，且所有基线仍匹配或其diff已得到解释时，退出此阶段。
Pilot。 根据
```
references/worker-brief.md
```
为试点提供说明，端到端运行：工作Agent、验证Agent、台账行、落地。修复试点中暴露的模板问题。当试点通过
```
verified
```
并落地，且模板变更已记录时，退出此阶段。
构建codemod。 将试点的方案转化为codemod，在试点的起始提交上运行，并将结果与手动迁移的结果进行diff对比。遗漏的内容加入说明中。codemod和
```
codemod/RECIPE.md
```
位于所有工作Agent的写入范围之外。当该diff已记录，且第二次运行无变更时，退出此阶段。
Fan out。 在
```
frame.md
```
规定的上限下运行滚动窗口（见
```
references/orchestration.md
```
），每个工作Agent对应一个surface，每个surface都有自己的分支和worktree（或采用
```
references/platforms.md
```
中的备用方案），以及填写完整的说明。当预算使用约70%时停止生成新的Agent（见
```
references/orchestration.md
```
预算与停止部分）。
验证每个surface。 由未编写代码的验证Agent检查视觉diff、渲染后的检查清单、可访问性快照、行为及其增量，并运行
```
design-review
```
（见
```
references/verification.md
```
）。若没有子Agent，协调Agent需根据该处的检查清单进行自验证。当台账中包含某个surface当前提交的结论时，该surface的验证阶段退出。
持续集成。 将每个已验证的surface作为独立提交落地到run branch，并附带其捕获内容。冲突将作为一个工作单元分配给工作Agent。每次落地后运行集成检查。若集成构建失败，则停止落地，直到构建恢复通过。
删除遗留代码。 当某个遗留模块的调用方数量为0时，由一个工作单元在一次变更中删除该模块、其适配器以及对应的allowlist行，且lint规则会禁止该路径。任何从仓库外部导入的内容需在gate处等待。
Close。 执行最后一次清理，在最终集成提交上重新捕获所有surface，并为所有重新打开的行给出新的结论。将剩余预算用于验证
```
checks-only
```
、
```
self-verified
```
以及重新打开的surface。编写
```
close.md
```
、审计
```
decisions.tsv
```
、将每个重复出现的修复转化为检查项（见
```
references/orchestration.md
```
），并清理临时文件。当判定谓词成立，或报告中列出了剩余未完成项时，退出此阶段。

Boundaries

边界规则

The coordinator never writes product code when it can spawn subagents. On a host without subagents it runs the phases itself, in sequence, and self-verifies per

references/verification.md

Decide and log, without asking: the surface split and order, window size under the cap, retries and splits (

build-design-system/references/coordinator-path.md

, Dev server and retries), which verifier runs, clean landings, brief or codemod fixes the evidence supports, identical-value swaps on any surface, gate defaults the build recorded as

decided

, and adds-only accessibility changes (

build-design-system/references/traps.md

, Adds-only accessibility changes).

Park in

gates.md

with a default and keep working. Mapped pixel changes, color moves, component swaps and codemods on non-pilot surfaces are gates whose defaults land on the run branch with captures. These gates default to leaving the code as it is:

A token or component the system lacks.
A visual diff nobody can explain, or a change that removes, renames or restructures existing semantics.
A Blocking
```
design-review
```
finding already present in the baseline. The surface still verifies.
A behavior change of any size, including one that looks like a fix, because a migration keeps behavior as found.
A standing order that the code contradicts.
A dead end that survived one replan.
Deleting data, or an export used outside the repo.

Never:

Let two workers edit the same file, or let any worker touch the shared layer after its phase.
Invent a token, component, prop, or variant to fill a gap.
Count
```
checks-only
```
,
```
blocked
```
, or a self-report as verified, or let a decision row stand in for a verifier.
Keep a legacy module or adapter alive after its last caller moved, except behind a gate with an owner and a removal date.
Relax the done predicate to declare the run finished.

协调Agent在可生成子Agent的情况下绝不编写产品代码。在没有子Agent的宿主上，协调Agent自行按顺序执行所有阶段，并根据

references/verification.md

进行自验证。

以下事项可自行决定并记录，无需询问：surface的拆分与顺序、上限内的窗口大小、重试与拆分（见

build-design-system/references/coordinator-path.md

开发服务器与重试部分）、运行哪个验证Agent、干净落地、证据支持的说明或codemod修复、任意surface的identical-value swap、构建记录为

decided

的gate默认值，以及仅新增的可访问性变更（见

build-design-system/references/traps.md

仅新增可访问性变更部分）。

以下事项需存入

gates.md

并设置默认值，同时继续工作。非试点surface上的映射像素变更、颜色调整、组件替换和codemod都属于gate，其默认值会随捕获内容落地到run branch。这些gate的默认值为保持代码不变：

系统缺失的token或组件。
无人能解释的视觉diff，或删除、重命名、重构现有语义的变更。
基线中已存在的阻塞性
```
design-review
```
问题。该surface仍可通过验证。
任何规模的行为变更，包括看起来像是修复的变更，因为迁移需保持原有行为不变。
与常设指令冲突的代码。
经过一次重新规划仍无法解决的死胡同。
删除数据，或仓库外部正在使用的导出项。

禁止：

让两个工作Agent编辑同一个文件，或让任何工作Agent在共享层阶段结束后修改共享层文件。
发明新的token、组件、prop或变体来填补缺口。
将
```
checks-only
```
、
```
blocked
```
或自报告视为已验证，或用decision行代替验证Agent。
在最后一个调用方迁移后仍保留遗留模块或适配器，除非在gate后指定了负责人和移除日期。
放宽完成判定谓词来宣称运行完成。