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 old source code. The right way is to keep the old interface running, gradually transitioning each part to the new system in a phased replacement, starting from tokens to 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 frequent question Sinh Vũ hears when clients start building a design system is: "The old interface has hundreds of screens, do we really have to redo everything?" Not at all. Redoing everything at once is the most expensive and risky approach. There is an alternative, 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), recognized by the Microsoft Azure Architecture Center as one of the safest ways to transition running systems. Applied to the design system, the roadmap consists of three phases:
- Phase 1, review and standardize tokens: Inventory all existing interfaces, identify color values, font sizes, and spacing that are used inconsistently, then name and consolidate them into tokens. This is the foundation; getting this step right makes everything else much easier.
- Phase 2, build components and documentation based on tokens: Gradually create new components (interface elements) using the standardized tokens, along with user guidelines for the design and technical teams.
- Phase 3, transition sample products first, then scale: Select one screen or a small flow, transition to the new system entirely, observe any arising issues, make adjustments, and then scale 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.
Additionally, feature flags allow you to enable a new system for a small group first, observe the results, and turn it off immediately if there are issues 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 governance documentation and processes: The design and technical teams do not know which components have been transitioned and which have not, leading to a mix of both old and new systems without a clear exit strategy.
Sinh Vũ's viewpoint
In practice, the most time-consuming part is not building new components but the initial inventory and standardization of tokens. The team often wants to skip this step because it is less "visible" compared to having shiny new components. But if the tokens are not stable, everything built will need to be revised.
Sinh Vũ also recommends clearly defining the boundaries between the old and new components from the start: which documents are part of the new system, which components have officially transitioned, and which are still in the transition phase. Without clear boundaries, after six months, 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.
Strangler Fig Pattern, Microsoft Azure Architecture Center
Decision checklist
Topic: Transitioning from an old interface to a new design system without starting from scratch. Sinh Vũ guide, sinhvu.com
Select each item you find appropriate, 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 might consider it if the product is truly small, has few users, and you are about to replace the entire underlying technology. However, even in that case, inventory the old interface first to avoid missing important design decisions. In most cases, a gradual transition is safer as it preserves history and reduces the risk of launch.
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 everywhere. Standardizing tokens first is essential because all components share this foundation. If the tokens are not stable, the components built on them will also deviate from the standard and require multiple revisions.
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. Sinh Vũ recommends that you work with the technical team to assess the scope before applying it, and not to run tests directly on the main branch.