# 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.

Updated 19 October 2026. By Arlan Marat (https://design.how/about).

## When to use it

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.

## What it does

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.

## What you get back

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.

## What it never does

- 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.

## Install

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](https://design.how/skills), free after an email signup.

## The other skills

- [design-system-boss](https://design.how/skills/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](https://design.how/skills/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](https://design.how/skills/token-mapping): Reports how the hardcoded colors and sizes in your code map onto your design tokens, by purpose. It never edits.
- [ui-review](https://design.how/skills/ui-review): Reviews a screen, flow or running build, accessibility included, and ranks what is broken with evidence.
- [component-docs](https://design.how/skills/component-docs): Writes one component's documentation from its code and two real uses, with rules next to the examples.

## Related

- [What is a design system for agents?](https://design.how/design-systems-for-agents.md)
- [How to give Claude Code a design system](https://design.how/claude-code-design-system.md)