Migrating a design system is no small feat. It requires careful planning, coordination, and clear cross-team communication. When we decided to move forward with migrating from our custom in-house system to a new componant library based on Chakra-UI, we needed to have a solid plan. Here's an overview of how we approached the migration process:

Documentation is just as important as the component

Most developers like to dive in and just install a package and get going. Others, like me, sometimes need a reference as a jumpoff point. We wanted to make a system that could be adopted by developers of all kinds of workflows. As we built new components, we wrote documentation in parallel. For each component, we created a mapping document that identified its equivalent in the new library, noted any required customizations, and estimated the effort needed to migrate.

Understanding the scope

To get a sense of the migration scope, we first audited our existing design system to identify all the components in use. We then created a mapping document that listed each component, its equivalent in the new library, and any customizations that would be needed. This helped us prioritize which components to tackle first based on their usage frequency and complexity.

Getting teams to understand their scope

Once we had a clear understanding of the migration scope, we worked closely with product teams to help them understand how the migration would impact their areas of the product. A helpful tool for this was a code scanner CLI tool I built that could scan our monorepo for component usage. This allowed teams to see exactly where their components were being used and what props and styles were applied. With this information, teams could better plan their migration efforts and allocate resources accordingly. See my project post on the Code Scanner CLI tool for a deep dive on what this took.

[Examples of migrated components here]

Creating a migration strategy

We developed a phased migration strategy that allowed us to gradually transition from the old system to the new one. This involved breaking down the migration into manageable chunks, starting with the most critical product areas and gradually working our way through the rest. We also established clear guidelines for how to handle customizations and edge cases to ensure consistency across the board.

Themeing considerations To maintain visual consistency during the migration, we ensured that our new Chakra-UI-based components were themed to match the old design system as closely as possible. This involved customizing the new library to align with existing brand colors, typography, and spacing guidelines. By doing so, we minimized visual disruptions for users during the transition period. However, one thing I would have done differently is to have a more robust theming strategy from the start. While we were able to achieve a match, our new design system wasn't finished yet, so we ended up supporting tokens and variants that were not being used in the new system. This created some confusion for teams trying to migrate, as they had to navigate both the old and new token systems, and we eventually needed to create hooks and utilities to support styles that needed to be applied in one theme but not the other. In the future, I would recommend having a clearer theming strategy in place before starting the migration to avoid this kind of confusion and tech debt.

Two providers

To facilitate a smooth transition, we implemented a dual-provider approach. This meant that both the old and new design systems could coexist during the migration period. We created a wrapper component that included both the provider from the old system (built in-house with styled-components) and the new system (Chakra-ui). This approach minimized disruption to ongoing development and allowed teams to migrate at their own pace.

Rollout

AB testing was a crucial part of our rollout strategy. We gradually introduced the new design system to a subset of users, allowing us to gather feedback and identify any issues before a full-scale launch. This iterative approach helped us refine the migration process and ensure a seamless user experience.