How to Manage Breaking Changes in Design Tokens
A three-phase approach to deprecation, migration, and removal
Design systems evolve. Components get refined, naming conventions improve, and token architectures mature.
But what happens when these changes break existing implementations?
Let’s explore how to manage breaking changes in design tokens gracefully, keeping both your team and your products healthy.
What is a Breaking Change?
A breaking change occurs when a modification to your design token system requires developers to update their code to prevent visual or functional issues.
Common examples include:
Renaming a token — changing
color-primary-basetocolor-brand-basemeans any reference to the old name will failRemoving a token — deleting
spacing-xsbreaks layouts that depend on itChanging token structure — moving from simple to composite tokens alters how developers consume the values
Modifying a token’s type — converting a color token to a gradient requires code changes
Unlike non-breaking changes (updating a color value from #0066CC to #0052A3), breaking changes demand action from implementers. Without proper management, they cause broken interfaces, development friction, and eroded trust in your design system.
The Three-Phase Approach
Managing breaking changes isn’t about avoiding them — it’s about introducing them responsibly. A well-executed breaking change follows three phases: deprecation, migration, and removal.
Phase 1: Deprecation Notice
When you decide to make a breaking change, start by marking the affected token as deprecated. This signals to your team that the token will be removed, but gives them time to adapt.
What to do:
Add a
$deprecatedflag or comment in your token definitionUpdate your documentation to clearly mark the token as deprecated
Explain why it’s being deprecated and what should be used instead
Set a clear timeline for removal (typically 2-4 months, depending on your release cadence)
Example in JSON:
{
"color": {
"primary": {
"base": {
"$value": "#0066CC",
"$type": "color",
"$deprecated": true,
"$description": "Deprecated. Use color.brand.base instead. Will be removed in v3.0 (June 2026)."
}
}
}
}
Pro tip: If your toolchain supports it, configure linters or build warnings to flag deprecated token usage. This turns passive documentation into active developer guidance.
Phase 2: Migration Period
The migration period is where teams transition from old tokens to new ones. Your job is to make this as smooth as possible.
What to do:
Keep both old and new tokens available during this window
Provide migration guides with clear before/after code examples
Offer automated migration tools when feasible (find-and-replace scripts, codemods)
Communicate regularly through changelogs, Slack channels, or team syncs
Monitor usage analytics (if available) to identify products still using deprecated tokens
Example migration guide:
/* ❌ Old (deprecated) */
.button {
background: var(--color-primary-base);
}
/* ✅ New */
.button {
background: var(--color-brand-base);
}
Timeline matters: Short migration periods create pressure and resentment. Long ones let teams procrastinate. Find the balance based on your organization’s size and release frequency.
Phase 3: Removal of Obsolete Tokens
Once the migration period ends, it’s time to remove the deprecated token. This cleanup keeps your system lean and prevents confusion.
What to do:
Remove the token from your source files
Publish a major version release (following semantic versioning: v2.0 → v3.0)
Document the removal in your changelog
Notify teams one final time before release
Archive documentation for the old token (don’t delete it — someone will ask about it later)
Final check: Before removing, search your codebase (or usage telemetry) one last time to catch any lingering references.
Key Principles for Success
Communicate early and often. Developers hate surprises. Announce breaking changes well in advance through multiple channels.
Provide clear alternatives. Never deprecate something without offering a replacement and explaining why the new approach is better.
Respect your users’ time. Migration work is overhead. Minimize disruption by batching breaking changes into major releases rather than scattering them across minor updates.
Make it reversible (when possible). If you can alias old tokens to new ones during migration, do it. This reduces the blast radius if teams need more time.
Breaking Changes Build Trust
Handled poorly, breaking changes erode confidence in your design system. Handled well, they demonstrate maturity, respect for implementers, and a commitment to long-term quality.
Your design token system isn’t static — it should evolve with your products. By following a structured deprecation process, you give your team the runway they need to adapt while keeping your system healthy and sustainable.
__
What strategies have worked for your team when managing breaking changes? I would love to hear your experiences.