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. When design-system-boss is installed and nobody has checked the system's specs, the boss triages first, since a migration copies a weak system's gaps everywhere. Not for making the system.
Real-world examples not captured yet
This skill shows a gallery of live HTML demos (CDN libraries welcome — GSAP, Three.js, etc.) rendered inline via srcdoc.
Skill markdown
# Migrate to a design system Words are in `build-design-system/references/glossary.md`, bans, widths and voice in the accepted `.design-system/taste.md`. The system is settled and behaviour stays unchanged, except for announced data-bug fixes. A missing token or component is a gap for the system's owner, never a workaround here. The Never list in `build-design-system` holds for the coordinator and every worker. Scripts are in this skill's `scripts/`. Run each from the repo root as `node <this skill>/scripts/<name>.mjs`, except `scripts/legacy.mjs`, which is copied into the repo's `scripts/` so CI runs its ratchet. Captures and pixel diffs use `build-design-system/scripts/capture.mjs` and `build-design-system/scripts/pixdiff.mjs`, and capture installs `build-design-system/scripts/capture-guard.mjs` before the first navigation. ## Modes Audit mode is the default. It writes only under `.design-system/`, which `.git/info/exclude` keeps out of every commit, cuts no branch, commits nothing and ends with the inventory, the plan and the offer of the full run with its size. Full mode starts only when the ask names the migration or the person accepted the offer (`Go, <budget>`). "Clean it up" and "fix it" are not clearance. ## Steps 1. **Roles.** Add `.design-system/` to `.git/info/exclude`. In full mode use the branch the person named, or cut the run branch and write the branch you started on to `.design-system/start-branch`, which `land.mjs` refuses. Write `.design-system/roles.md`: coordinator, worker, verifier, reviewer, each a model or `inherit-parent`. The writer never grades itself. The verifier is a different agent, on another model family where the host has one. Write `.design-system/decisions.tsv` as append-only rows (`time, phase, decision, why, evidence pointer, result`). A wrong call gets a superseding row, never an edit. Evidence is a sha, a path or a command, never prose. 2. **Ready?** Run the readiness audits in `build-design-system`. Check every open backlog row against the code first. Rows go stale. Some are already fixed, and a "needs a system change" row is often a caller ignoring a prop the system has. No fan-out while a text or control primitive is missing, a gap is open or the system's own check is red. 3. **Inventory.** `node <this skill>/scripts/legacy.mjs --init-config --config .design-system/legacy.json`, point `legacyImports` and `systemImports` at the real modules, then `--inventory --config .design-system/legacy.json`. It exits 2 while a placeholder is left or no file was scanned. Every finding gets a surface. In audit mode, stop here and write the plan. In full mode, copy the script to `scripts/legacy.mjs` and the config to `scripts/legacy.json`, and `--record` the baseline (`scripts/legacy-baseline.json`) in its own commit. 4. **Baselines.** Capture every surface, state, width and theme before the first edit, in the environment CI uses, with fixture data and a frozen clock, plus a no-change control capture. `capture.mjs` refuses to start without `--writes <file>`, and with it until every write in the file is seen blocked (lesson 6). No baseline, no parity claim. Never edit a harness, a baseline or a threshold, or restructure a component to make a diff pass. A baseline that looks wrong is kept as captured and becomes a gate (default: keep it, and fix the bug it shows as an `intended change`), and the run goes on. 5. **Shared layer first.** One agent, alone, lands layout and providers. Then migrate the pilot surface by hand with a verifier, write the codemod from it, diff its output against the hand work, and run it twice. The second run changes nothing. Fan out only after that. 6. **Fan out.** A rolling window, one surface per worker, each brief with a MAY EDIT list, each surface verified by another agent. A retry or a fix goes to a fresh worker with the brief, every later directive and the prior verdict. Read `references/running-many-agents.md` before the first spawn. 7. **Land.** `land.mjs`, one commit per verified surface, then the system's check at that commit. A surface whose diff touches write lines lands with `--bodies-check` (lesson 5). 8. **Delete legacy.** A module with zero callers goes in one change with its adapter and allowlist rows, and the ratchet bans its path. 9. **Close.** Recapture every surface at the final commit. Only verdicts at that commit count. Have a read-only reviewer go through the diff's comments (narration, worker or gate references, "do not change" notes), and offer to turn each "do not change" into a check, then delete the comment. A different agent audits `decisions.tsv` against the run. Then run the correction pass in `references/correct.md`. Done when `legacy.mjs --zero` exits 0 at the final commit (no legacy import and no file mixing the system with legacy, whatever the baseline holds), every raw or palette row `--inventory` still prints is a listed exception, every surface has a `verified` verdict at that commit, the system's check exits 0, …
More from arla6ka
- Build Design SystemUse when an ask names one phase of design system work, such as "extract tokens from the app" or "add states and specs to our Button", or for an empty repo, such as "start a design system from scratch". A whole-app ask on a shipped app ("we need a design system") goes to design-system-boss when it is installed. Moving an app onto an existing system is migrate-design-system.
- Component DocsWrites one component's documentation entry from its code, stories and real call sites, in a Geist-style page order. Use for "document the button", "write docs for Select", "what states does Toast have", usage rules for a component, or a new or changed component. Skip foundations, overview pages and multi-component patterns. Docs for a whole design system go to design-system-boss.
- Design System BossUse for vague whole-app design system asks on an app that already ships UI, like "our UI is a mess, fix it", "we need a design system", "we hardcode colors everywhere", "make the buttons consistent for an upstream PR", "document our whole design system" or "check the app before I ship". Triages the app, then runs the design.how skills in order. One named screen goes to ui-review, one component to component-docs, an empty repo to build-design-system.
- LimeLime design system rules for this project's UI. Use when building or changing any screen, component, form or style, when porting an existing screen onto Lime, or when checking UI against Lime.
- QuartzQuartz design system rules for this project's UI. Use when building or changing any screen, component, form or style, when porting an existing screen onto Quartz, or when checking UI against Quartz.
- Token MappingReports how hardcoded style values on a page, file or diff map onto a project's existing design tokens, purpose first, then value. Use for "are we using our tokens here", "which hardcoded colors map to which tokens", a token audit or planning a token migration. It never edits and never creates or renames tokens. Fixes and whole-app consistency go to design-system-boss.