Design system migration checklist: plan a source-to-screen cutover

This checklist begins after the target design system has been selected. Its job is to replace existing tokens, components, packages, wrappers, and local styling rules without losing supported product behavior. It doesn't choose a brand strategy, rename the product, approve identity assets, or plan customer communications. Put that work in a rebranding plan so the technical migration doesn't quietly acquire a second, much larger mandate.

Write the boundary as a migration contract before counting components. Name the current and target authorities, their versions, supported platforms, behaviors that must remain stable, permitted changes, excluded surfaces, acceptance conditions, and rollback boundary. Give every unresolved field an owner. Don't let the implementation team settle the question through whichever value or component happens to be easiest to install.

• Current authority and version: the exact library, token source, package, or project rules being replaced.
• Target authority and version: the selected system and the artifacts that carry its decisions.
• Preserved behavior: workflows, keyboard behavior, responsive behavior, data presentation, permissions, and other contracts that must not change.
• Permitted change: the intended visual or structural differences approved for this migration.
• Exclusions: products, platforms, brand work, deprecated flows, or experimental surfaces outside this wave.
• Acceptance boundary: the consumers and conditions that require evidence before the wave can close.
• Rollback boundary: what can be reverted together without producing an unsupported hybrid.

A component list helps, but it's too coarse for migration. A single Button name may refer to several implementations, package versions, wrappers, variants, or product-specific behaviors. At the other extreme, one semantic token can reach hundreds of components. The migration unit should be the smallest decision or contract that a clear owner can replace, verify, and roll back.

Inventory units across the source-to-screen path. Include token roles, typography and spacing contracts, component APIs, packages, wrappers, product surfaces, modes, interaction states, and named consumers. Record dependencies in both directions: what the unit needs and what will change when it moves.

• Token unit: a semantic role, mode pair, alias, or deprecated name with known consumers.
• Component unit: a versioned API, variant, state contract, composition rule, or behavior.
• Distribution unit: a package, registry item, generated file, design library, or documentation release.
• Adaptation unit: a compatibility wrapper, alias, transform, or project mapping.
• Consumer unit: a named route, workflow, screen, application, or embedded surface using the contract.
• Observation unit: a specific consumer under a recorded mode, viewport, state, content condition, and environment.

Inventory intended and actual use. Search results, dependency graphs, design-library analytics, and code references can identify candidates, but none of them alone proves runtime use. Attach each finding to a named consumer. Mark uncertain relationships as unresolved instead of filling the gaps with inference.

Choose one mapping disposition for each current unit. That disposition determines who must act and what evidence they need. A direct replacement follows an established target contract. A transformed mapping needs a documented conversion, while a wrapper needs support and removal rules. A redesign requires an authorized product decision. An exception needs a defined scope and review dates. A blocked unit exposes a gap in the target system.

Keep expectations and observations in the same record, but never in the same field. This stops a planned result from being mistaken for a test result. A row can link to detailed evidence elsewhere; the register remains the control surface for status, ownership, and closure.

Migration unit ID:
Unit type: token | component | package | wrapper | surface | other
Current authority and version:
Current contract:
Target authority and version:
Target contract:
Named consumers:
Required modes, states, viewports, and content conditions:
Dependencies:
Preserved behavior:
Permitted changes:
Mapping disposition: direct | transformed | wrapper | redesign | exception | blocked
Replacement mechanism:
Coexistence window and precedence:
Owner:
Expected result:
Delivered evidence:
Mapped evidence:
Adopted evidence:
Observed evidence:
Open exceptions and review trigger:
Rollback trigger:
Rollback mechanism and last verified status:
Final disposition: accept | revise | block | rollback | unresolved
Closure condition:
Retest triggers:

Give the register stable identifiers so evidence, defects, and exceptions can point to the same unit. Keep versions precise enough to distinguish the assessed artifact from a later release. When a decision changes, preserve the earlier record and supersede it. The reason for a mixed implementation then remains recoverable.

No rollout pattern is universally safe. Choose one for a defined set of migration units. Base the decision on dependency coupling, blast radius, reversibility, tolerance for mixed versions, available evidence, and rollback cost.

A coordinated cutover fits when the old and new contracts can't coexist safely, such as a theme architecture change that would create ambiguous precedence across one application shell. Prefer phased replacement when units are separable and the team can observe each wave independently. Use a compatibility wrapper only when its translation is explicit and temporary. Land-and-expand helps when the migration route itself needs evidence, but success on one surface doesn't approve the rest of the estate.

During a gradual migration, old and new implementations are both legitimate for a time. That is manageable only when the boundary is written down. Without it, local aliases, copied styles, wrapper variants, and package overrides accumulate until nobody can say which behavior is temporary.

• Precedence: which authority wins when old and new rules both reach a consumer.
• Package boundaries: which packages, entry points, or applications may use each version.
• Alias and wrapper ownership: who may add mappings and who approves changes.
• Support window: the dates or wave conditions during which coexistence is supported.
• Expiry criteria: the dependency, consumer, and evidence conditions required before removal.
• Observability: how remaining old references, wrapper calls, exceptions, and runtime failures are found.
• Forbidden combinations: versions, themes, wrappers, or local overrides that must never coexist.
• Failure behavior: what happens when a mapping is missing or a consumer receives incompatible artifacts.

Pick a pilot that is representative enough to expose the migration path but bounded enough to reverse. A decorative marketing page may be easy, yet reveal little about application states. A payment flow may be representative but too consequential for the first attempt. A better pilot often includes shared tokens, at least one interactive component, realistic content, light and dark modes where supported, and a noncritical workflow with observable outcomes.

1. 1

   Confirm the source decision

   Record the approved target contract, version, owner, preserved behavior, and permitted changes.

2. 2

   Inspect the delivered artifact

   Confirm that the required tokens, component contracts, packages, or guidance exist in the exact artifact being used.

3. 3

   Verify the project mapping

   Check that the consumer resolves the intended package, export, aliases, tokens, fonts, and mode policy.

4. 4

   Verify the component contract

   Check structure, variants, states, responsive behavior, content handling, and preserved interactions before evaluating polish.

5. 5

   Record approved exceptions

   Keep deliberate divergence separate from defects. Give each exception an owner, scope, reason, and review trigger.

6. 6

   Confirm consumer adoption

   Establish that the named surface uses the target component or mapping instead of a local substitute or stale wrapper.

7. 7

   Observe the rendered result

   Inspect representative modes, states, viewports, content extremes, keyboard paths, and consequential interactions under recorded conditions.

8. 8

   Exercise the rollback route

   Verify the rollback mechanism within the pilot boundary before expanding the wave. Record what was tested and what remains unproven.

Keep a baseline for behavior that must remain stable. Depending on the contract, use screenshots, interaction tests, accessibility observations, performance measurements, or recorded product outcomes. Keep known defects visible. Changing the baseline to hide an old defect turns uncertainty into false parity.

A single progress percentage hides where the migration stops. Report four evidence states for every accepted unit. They build on one another, but one doesn't automatically prove the next.

This distinction matters in status reports. A team can truthfully say that 90 percent of artifacts were delivered while only 40 percent of named consumers have adopted them. Combining those figures into one done value would hide the actual cutover risk.

Don't inspect every possible rendering unless the contract requires it. Select representative consumers based on reach, difference, and consequence. Include the shared shell or highest-reach consumer, unusual compositions, a high-consequence workflow, and any platform whose implementation differs from the pilot.

• Modes: every supported light, dark, high-contrast, branded, or nested mode relevant to the unit.
• Interaction states: default, hover, focus, active, selected, disabled, loading, validation, error, empty, and recovery states that the component supports.
• Content extremes: long labels, localization, large numbers, missing media, dense data, and user-generated content.
• Viewports and containers: narrow and wide layouts, zoom conditions, and container-specific adaptations.
• Consequential surfaces: authentication, billing, permissions, destructive actions, critical data entry, and other workflows where regression cost is high.
• Behavior: keyboard order, focus movement, pointer behavior, validation, navigation, persistence, and asynchronous transitions.
• Accessibility evidence: system-level checks plus product-level retesting. A component result cannot certify every composition in a product.
• Operational conditions: the deployed package, feature configuration, runtime environment, and rollback route relevant to the wave.

Wave ID:
Scope and included migration-unit IDs:
Excluded units and reason:
Target versions:
Rollout route:
Coexistence contract version:
Representative consumers and selection rationale:
Required modes, states, viewports, and content conditions:
Delivered evidence complete: yes | no | not applicable
Mapped evidence complete: yes | no | not applicable
Adopted evidence complete: yes | no | not applicable
Observed evidence complete: yes | no | not applicable
Open defects:
Approved exceptions, owners, and review triggers:
Rollback trigger:
Rollback mechanism verified under:
Retest triggers:
Decision authority:
Decision: accept | revise | block | rollback
Decision rationale and evidence links:
Next wave authorization: approved | withheld | not requested

Accept the wave when every required unit has the necessary evidence, each open divergence is resolved or covered by a current authorized exception, and rollback remains usable. Revise when the route is sound but correctable gaps remain. Block when required authority, target capability, evidence, or safe rollback is missing. Roll back when an agreed trigger occurs and keeping the wave would create greater product risk.

When a migrated screen looks wrong, trace the issue from the governing decision downstream. Fix the first layer where expected and observed evidence differ. Patching the visible consumer may remove the symptom while preserving the cause, allowing the defect to return in the next component or wave.

Ambient Sage illustrates the upstream boundary without pretending that a migration was executed. The public kit supplies a warm neutral visual direction, semantic light and dark color roles, typography, spacing, layout guidance, component rules, and implementation-oriented artifacts. These are candidate target inputs for a consuming project.

An intake row can mark the public kit and its available artifacts as delivered. Project mapping remains unresolved until a named project connects its configuration and dependencies to them. Component adoption remains unresolved until named consumers use the intended contracts. Accessibility, preserved behavior, and runtime rendering remain unresolved until the team evaluates them under recorded product conditions.

Measure migration progress by evidence state and consequence, not raw component count. Replacing ten unused icons isn't equivalent to migrating one table that supports a critical workflow. For each wave, report the number of required units delivered, mapped, adopted, and observed alongside high-reach consumers, open target gaps, expired exceptions, remaining legacy references, and rollback readiness.

Use wave-level outcomes to decide whether the route transfers. A pilot may show that the mapping and verification method works for one application while leaving another platform untested. Expand only when the next scope has named units, representative conditions, an owner, and its own acceptance decision.

Start with one consequential migration unit and complete its register before scheduling the wider rollout. If you can't name its current contract, target contract, consumers, owner, evidence, and rollback trigger, the migration isn't ready to expand.

• An insider's guide to a seamless Figma migration: Figma's guide supports treating migration as cross-functional work involving planning, advocacy, rebuilding, onboarding, timelines, and communication.
• Guide | Carbon Design System: Carbon's migration guide distinguishes release changes across themes, design kits, packages, Sass, grid, and component implementations.
• migrate-design-system Skill: The application-migration workflow emphasizes inventory, preserved behavior, baselines, shared-layer changes, and verification rather than package installation alone.
• Checklist & Recs FlowUI Migration: The FlowUI case study shows that feedback from important product surfaces can reveal interaction and layout failures after the implementation appears ready.
• I tried three ways to ship a design system. Here's what actually worked.: The practitioner retrospective compares coordinated replacement, gradual replacement, and land-and-expand, showing that each rollout route carries different disruption and adoption risks.
• Design System Versioning: Manage Your UI/UX in 2026: The versioning guide connects migration planning with coordinated design assets, code, documentation, and release history.
• Ambient Sage Design Kit: The public Ambient Sage kit provides target-state visual inputs including semantic colors, typography, spacing, component guidance, and implementation artifacts, but it does not prove adoption in a consuming product.
• Rebranding a SaaS product checklist: The existing rebranding guide covers identity and brand-change cutovers, which sit outside this technical design-system migration checklist.