Transitioning the old interface to the new system without starting from scratch
The correct approach is not to tear down and rebuild, but to gradually replace each part while the product is still running.
You do not need to stop the product or discard all the old code. The correct approach is to keep the old interface running, gradually transition each part to the new system through incremental replacement, starting with tokens and then components. Only when a part is stable in the new system should you turn off the corresponding old part.
- Products that are currently running, cannot be paused, with large source code.
- Prioritize the token and a sample display screen before committing to scaling.
- Start over (big bang) when a major product is already in motion.
The most frequently asked question when starting to build a design system is: "The old interface has hundreds of screens, do we really have to redo everything?" Not at all. Rebuilding everything at once is the most expensive and riskiest approach. There is an alternative path, proven in practice, called incremental replacement.
Why should we not redo it all at once?
The approach of starting over (often called "big bang rewrite", meaning rewriting everything at once) creates a parallel code branch that can last for months. During this time, the actual product must still run and receive modification requests. As a result, the two branches diverge increasingly, the team becomes exhausted fixing both at once, and the launch date for the new system keeps getting pushed back.
More dangerously: a design or technical error discovered late will spread throughout the entire refreshed interface, with no simple way back.
The right approach: incremental replacement
The foundational principle is the Strangler Fig Pattern (a gradual replacement model, named after the strangler fig tree that grows around an old tree and gradually replaces it). The Microsoft Azure Architecture Center describes this as a way to transition running systems to reduce risk. Applied to the design system, the roadmap consists of three phases:
- Phase 1, review and standardize tokens: Inventory all existing interfaces, identify the color values, font sizes, and spacing being used inconsistently. Name and consolidate them into tokens. This is the foundation; getting this step right will make everything else much easier.
- Phase 2, build components and documentation based on tokens: Gradually build new components (interface elements) using the recently standardized tokens. Along with this, provide usage documentation for the design and technical teams.
- Phase 3, transition a sample product first, then scale up: Choose one screen or a small flow, fully transition it to the new system. Observe any issues that arise, make adjustments, and then scale it to the rest.
Support tools: codemod and feature flags
When scaling, renaming components or changing the source code structure manually can easily lead to oversights and take time. Codemod (an automated code modification tool, a script that changes code according to predefined rules) helps execute this quickly and consistently. Atlassian and MUI are two organizations that have published how to use codemod in the design system transition process.
At the same time, a feature flag (a toggle for enabling or disabling features based on environment or user group) allows you to enable the new system for a small group first to observe the results. If there are issues, you can turn it off immediately without needing to redeploy. This is an important fallback when implementing on a live product.
Gradual transition is appropriate when the product is running in real-time, without stopping, large codebase, or multiple screens that need to remain stable. A complete overhaul is only reasonable when the product is truly small, has few real users, and the team is about to replace the entire underlying technology at once. Even then, an inventory of the old interface should be conducted first to avoid losing important design information.
Common errors when transitioning systems
- Skip inventory of old interfaces: not knowing what you have means you won't know what needs to be transitioned. The result is missing standard points, half-hearted migration, and a confusing mix of new and old systems.
- Scaling before reaching the sample point: An unchecked error in a component or token will replicate everywhere, requiring a simultaneous fix.
- Lack of documentation and governance processes: The design team and the technical team do not know which components have transitioned and which have not. As a result, both old and new systems are used interchangeably without a clear exit strategy.
- Do not draw boundaries between old and new from the start: Which documents belong to the new system, which components have officially transitioned, and which components are still in transition need to be clearly documented. Without these boundaries, after a while, you will no longer know which system you are using.
Keep the old system running while gradually transitioning each part. Do not tear everything down and rebuild at once.
Practical experience, following the spirit of the Strangler Fig Pattern
Decision checklist
Topic: Transitioning from the old interface to the new design system without starting from scratch. Sinh Vũ Handbook, sinhvu.com
Tick each item that applies or that you can already answer, then print or save as PDF to take with you.
If you have marked most of the signs above, this is the time to discuss in more detail. Sinh Vũ can help you review and propose a direction.
References
Microsoft Azure Architecture Center, Strangler Fig Pattern. Atlassian and MUI codemods, practical operational documentation. A three-phase roadmap perspective: Sinh Vũ's practical experience.
Frequently asked questions
For a small project with few users, should it be completely redone?
You may consider it if the product is truly small, has few users, and you are about to change the entire underlying technology. But even then, inventory the old interfaces first to avoid missing important design decisions. In most cases, a gradual transition is still safer as it preserves history and reduces launch risks.
What is a token and why should it be standardized first?
Tokens (design variables) are foundational values such as colors, font sizes, and spacing, named and used consistently instead of hardcoding them in multiple places. Standardize tokens first because every component will share this foundation. If the tokens are not stable, the components built on them will also deviate from the standard and will need to be corrected multiple times.
What is codemod, and does it require an engineer to use it?
Codemod (automated code transformation tool) is a script that changes source code in bulk according to predefined rules, for example, renaming an old component to a new name throughout the project. Using codemod requires an experienced frontend engineer. It is advisable to work with the technical team to assess the scope before applying it, and do not run tests directly on the main branch.
This article is for reference. The scope, pricing, and specific commitments of Sinh Vũ are detailed in the proposal and signed contract.