Primary references
These sources support the standards and technical explanations in this guide. Color Pick recommendations and product-specific limitations are identified separately in the article.
Web and UI
How to Audit a Color Design Token Migration
Compare two color-token releases, detect breaking changes and probable renames, test theme regressions, and create a safer migration plan.
Direct answer
Compare token paths, values, types, aliases, deprecations, and resolved theme output before replacing a design-token release. Treat removed or renamed semantic and component tokens as potentially breaking, then rerun contrast and component-state audits across every supported theme and brand. A value match can suggest a rename, but it is an inference that requires human review.
At a glance
Why color-token migrations break products
A small token-file change can alter many components through aliases and theme overrides.
Renaming a primitive may break a build. Changing a semantic token may compile successfully while altering buttons, links, charts, and focus indicators. A dark-theme override can be missed when only the light theme is reviewed.
Migration review therefore needs structural comparison and resolved visual evidence.
- Removed token paths
- Renamed aliases
- Changed resolved colors
- New circular references
- Missing theme overrides
- Contrast regressions
- Deprecated tokens still used by components
Compare structure before visual output
Inventory additions, removals, changes, deprecations, and likely renames.
| Change | Typical risk | Review |
|---|---|---|
| Added | Low | Confirm naming and ownership |
| Removed | High | Find every consumer |
| Changed semantic value | Medium–high | Review all inherited components |
| Probable rename | High | Confirm intent and update imports |
| Deprecated | Low now, higher later | Publish replacement path |
Resolve every supported theme and brand
Source-token equality does not prove resolved equality.
- 1
Resolve light, dark, and high-contrast contexts in both releases.
- 2
Repeat the resolution for each supported brand primitive set.
- 3
Compare component-state output, not only semantic tokens.
- 4
Report broken and circular aliases before calculating visual metrics.
Run contrast and state regression tests
A migration is safer when measurable behavior is compared before and after.
Recheck body text, secondary text, links, buttons, input boundaries, focus indicators, badges, tables, and tooltips. Report the worst result, not only the average.
State coverage should also be compared. A renamed disabled or error token can disappear from a component while the default state remains correct.
Publish a migration map
Developers need explicit replacements and release impact.
- Old path and replacement path
- Whether the change is breaking
- Affected themes and components
- Before and after resolved colors
- Contrast or state regression results
- Removal date for deprecated aliases
{
"deprecated": "color.primary",
"replacement": "semantic.action.primary",
"breaking": true,
"reason": "Role-based naming and multi-theme resolution"
}Review inferred renames and product implementation
Automated comparison cannot know every design decision.
A tool may infer a rename when an old and new token share the same value and layer. Two unrelated tokens can also share a value, so the suggestion must be confirmed by a person who understands product intent.
Token evidence also cannot confirm that every application has updated its imports, CSS output, visual snapshots, or runtime theme switcher.
Put the guide into practice
Open migration assistantCompare two token releases
Paste previous and proposed token sets, review possible breaking changes, and keep the same workspace for contrast and state audits.
Frequently asked questions
Is changing a primitive token a breaking change?
It may not break an import path, but it can produce a wide visual change through aliases. Treat it as a behavioral change and review all resolved consumers.
How can a probable rename be detected?
A comparison can pair a removed token with an added token that has the same value and layer. This is only a heuristic and should be confirmed against source history and product intent.
Should deprecated tokens be removed immediately?
Usually not. Publish a replacement, migration window, usage search, and removal date that match your release policy.
What should be tested after migration?
Build output, aliases, themes, brands, contrast, component states, snapshots, interactive focus behavior, and real product screens.