design-how-migrate-design-system
Audit or replace legacy UI with an existing design system in bounded waves while preserving route behavior and rendering.
Try your first task
A source-grounded starter task has not been verified for this skill yet.
SKILL.md
name: "design-how-migrate-design-system"description: "Audit or replace legacy UI with an existing design system in bounded waves while preserving route behavior and rendering."category: "design"risk: "critical"source: "https://github.com/arla6ka/design.how/tree/1ce5304466db2ba47a7a7524603e86df77c702bd/skills/migrate-design-system"source_repo: "arla6ka/design.how"source_type: "community"license: "MIT"license_source: "https://github.com/arla6ka/design.how/blob/1ce5304466db2ba47a7a7524603e86df77c702bd/LICENSE"author: "Arlan Marat"date_added: "2026-11-19"Migrate a Design System
When to Use
Use for adoption audits and scoped migrations onto existing tokens and primitives. Use design-how-build-design-system when the required primitives or contracts are missing.
Workflow
- Inventory the routes, legacy imports, local lookalikes and public exports. Group each replacement by component family and flag gaps that need changes to the system. Default to a read-only audit when rollout scope is unclear.
- Define a before/after contract for each surface: exact routes, files, fixture states, visual exceptions and behaviors. Check props, slots, accessible names, formulas and formatting. Capture baselines at the narrowest and widest supported widths.
- Pick a pilot with a harder call site. Map a legacy primitive to a system primitive only if the required props, events and semantics are available. Leave unsupported paths on legacy and record the gap. Keep unrelated refactors and cleanup out of the wave.
- Compare interactions and screenshots with identical data and environment. Exercise submission, loading, keyboard, focus and errors on a disposable backend. Count open legacy imports and explicitly list any intentional state or visual difference.
- Re-read the diff and check shared call sites before scaling. Roll out in small route groups with rollback points. Remove a legacy export only after checking consumers including other packages, and only within the approved scope.
Example
“Move settings from the old Select to our system Select.” First compare controlled values, disabled options, Escape, label and focus behavior, then migrate one settings route and compare the recorded states.
Limitations
Requires an existing system. Count checks can miss dynamic consumers and screenshots can miss behavioral regressions. A failed parity check blocks that surface. Use isolated fixtures and follow the project's normal version control flow.
Bundled resources
- Read parity, migration lessons, correction, and staging guidance.
- Use the installed
scripts/legacy.mjsto inventory legacy imports andscripts/parity.mjsto compare outputs of trusted local modules. Usescripts/bodies-check.mjswith synthetic request fixtures. Use capture and pixel diff from the installeddesign-how-build-design-systemsibling. scripts/land.mjsis an optional helper for explicitly authorized local migration commits. Use a work branch, the exact reviewed paths, and the project checks. Its shell callback is for a locally written check, never text copied from project data or PR feedback. Leave hooks enabled and use the project's normal pull-request flow.
Source
Adapted from design.how by Arlan Marat. See MIT license.