- Your service stays aligned with the current GoA standard as more services update and users move between them
- You get access to new component properties, examples, and templates that reduce build time for common service types
- Your product remains supported — the legacy design system stops receiving fixes after September 2026
Most of the update applies automatically. Most of the work will be reviewing what changed in your product and deciding where design follow-up is needed. These steps help you work through the process.
The developer-first approach lets you see what actually changed in your product before committing to design work.
When you run the update first, spacing, typography, and token changes apply automatically. You can then review the result with your team and focus design and development effort on the screens that need it most. This avoids redesigning screens based on assumptions about what will change before you update.
The migration walkthrough steps through four stages — legacy design system, upgrade applied, layout and styling fixes, and custom component updates — and shows the visual impact on your interface at each stage. The walkthrough covers both public form and workspace product types. Review it with your team before you start: it helps designers and developers see where changes occur, and gives product owners a clearer picture of the scope for planning.
Applying the update to some parts of your product but not others tends to cause the update to stall. Teams focus on a few components then deprioritize the rest, leaving the product in a mixed state that becomes harder to resolve over time. Reviewing your updated application together in step 3 is designed to address this. Reviewing the full update in a branch before committing gives your team a clear picture of the actual work involved. Use that branch to plan your migration window — you are not committing to proceeding until you are ready.
Create a dedicated branch for the update. Keeping it separate from your regular development work lets your team review the changes before merging.
git checkout -b ds-migrationUse a branch name that works for your team — this is just an example.
Follow the steps in Setup to install the updated packages. Run your application after installing the updates. Do this before making any other changes.
Walk through your application with your product team. At this stage, the team will identify what needs attention and decide what to prioritize.
What to look for:
| Area | What to look for |
|---|---|
| Spacing and layout | Screens that feel too tight or unbalanced |
| Typography | Headings or body text that look off in size or weight |
| Dense or data-heavy screens | These carry the most risk during an update and often need the most follow-up |
| Custom components | Anything built outside the design system that needs manual alignment |
Record what you find. A list of screens and issues is enough at this stage. Your designers and product owner can use that output to plan and prioritize work.
There is no single estimate for how long a migration takes. It varies depending on your product. The main factors are:
| Factor | Impact on migration effort |
|---|---|
| App size | More screens means more to test and review after the update |
| Design system utilization | Products with more custom code need more manual alignment |
| Developer familiarity | Developers with more design system experience move faster through the migration steps |
Use the team review of your updated application in step 3 to build a realistic estimate for your own product before committing to a timeline.
- Bring what you find when reviewing your updated application to drop-in hours to get feedback on what to prioritize
- If you find a problem with the design system itself, reach out on the support channel rather than working around it
- Get feedback on your service
- Propose new components or patterns
- Suggest updates to existing resources
- Ask questions
- Share feedback