Three-phase approach to managing breaking changes in design tokens¶
Insight: Breaking changes in design tokens (renaming, removing, restructuring, type changes) require a three-phase management approach: deprecation (mark with $deprecated flag, document why, set timeline), migration (provide codemods or automated tooling, offer side-by-side period), and removal (clean up after migration window). Unlike non-breaking value changes, structural changes demand action from implementers and erode trust if mishandled.
Detail: Key distinction between breaking and non-breaking: changing a color value from #0066CC to #0052A3 is non-breaking (consumers don't need code changes), but renaming color-primary-base to color-brand-base or converting a color token to a gradient type is breaking. The deprecation flag in token definitions ($deprecated) serves as machine-readable signal for tooling to surface warnings automatically.
Sources
Related: existing entry "Design tokens as API layer for AI" in external/design-tokens.md — COMPLEMENTS