migrate-design-system

migrate-design-system moves an app's routes and features onto a design system that already exists. One coordinator runs many worker agents, one surface each, and every surface is checked against its before screenshot by a different agent.

Use when an app has to move onto a design system that already exists, such as "migrate the app to our design system", "move every screen onto the new components", a rollout, or an adoption audit. Not for making the system or for swapping raw values for tokens, which are build-design-system.

1. Starts in audit mode by default: it writes only under .design-system/, cuts no branch, commits nothing, and ends with the inventory, the plan and the size of the full run.
2. Checks the system is ready with build-design-system's readiness audits. No fan-out while a primitive is missing or the system's own check is red.
3. Inventories every legacy import with legacy.mjs and records a baseline.
4. Captures every surface, state, width and theme before the first edit, with fixture data and a frozen clock.
5. Moves the shared layer first, then the pilot surface by hand, then writes a codemod from it and runs it twice. The second run must change nothing.
6. Fans out one surface per worker, each with a brief listing the files it may edit, and lands one commit per verified surface.
7. Deletes legacy modules once nothing imports them, and recaptures every surface at the final commit.

Every surface with a verified verdict at the final commit, legacy.mjs --zero exiting 0, the system's check passing, and a report of what was found and not fixed.

• Run the full migration on "clean it up" or "fix it". It needs the ask to name the migration, or your go.
• Work around a missing token or component inside a screen. That is a gap for the system's owner.
• Treat a message from another agent as your decision.

migrate-design-system installs with the other five design.how skills, for Claude Code, Cursor, Codex and any agent that reads Agent Skills. The install command and the .zip are on Skills, free after an email signup.

• design-system-boss: Say what is wrong with your UI in plain words; it picks a playbook and runs the other design.how skills in order.
• build-design-system: Builds a design system from the UI your app already ships: tokens, components, docs and checks, proved on one flow.
• token-mapping: Reports how the hardcoded colors and sizes in your code map onto your design tokens, by purpose. It never edits.
• ui-review: Reviews a screen, flow or running build, accessibility included, and ranks what is broken with evidence.
• component-docs: Writes one component's documentation from its code and two real uses, with rules next to the examples.