Skip to main contentCarbon Design System

Migration guide

This guide includes everything you need to migrate your offering from Carbon v9 to v10.

Transitioning to v10

The transition path to v10 was designed to be as seamless as possible but there are breaking changes. This guide is for teams migrating from v9 to v10. If your team uses an older version of Carbon, some of this information may not apply to you.

Migration strategy

Have a plan. Meet with stakeholders from design, OM, and engineering to kick off the migration process. Establish dedicated channels of communication for migration, and involve the broader team as needed.

Migrate in a dedicated branch. This update includes substantial changes to layout and spacing. We don’t recommend a piece-by-piece migration of your product in production. Teams should perform the migration first in a separate branch (or branches). This allows the creation of new design specs for any possible rough spots in alignment or sizing that may appear in the UI after upgrading.

Tackle components, colors, type, spacing, and iconography first. Aligning your product to the new grid will be design-intensive, and can be tackled after the breaking changes with other elements have been addressed.


To improve this guide, make a suggestion, or just ask a question, please open an issue on GitHub.