Token Breaking Changes

Token breaking changes are modifications to the token system that can cause consuming applications to fail or behave incorrectly. Managing breaking changes responsibly is critical to maintaining consumer trust. Poor handling of breaking changes creates upgrade friction and can discourage token adoption.

What Are Token Breaking Changes

Token breaking changes are modifications that require consumer code changes to maintain correct functionality. This includes removing tokens, renaming tokens, changing token types, or significantly altering token values in ways that affect application behavior.

The definition of “breaking” can vary. Some organizations consider any visible change breaking, while others limit the definition to changes that cause errors. Clear policies help set expectations.

How Token Breaking Changes Work

Types of breaking changes:

Removal breaks any code referencing the removed token:

/* Before: Token exists */
.element { color: var(--color-brand); }

/* After: Token removed */
.element { color: var(--color-brand); } /* Fails - undefined */

Renaming breaks existing references:

// Before
const color = tokens.color.brandPrimary;

// After - renamed to color.primary
const color = tokens.color.brandPrimary; // undefined

Type changes break usage patterns:

// Before: string value
background: tokens.color.primary // "#3B82F6"

// After: object value
background: tokens.color.primary // { light: "#...", dark: "#..." }

Significant value changes may not cause errors but break visual expectations:

/* spacing.md changed from 16px to 8px */
/* Layouts designed for 16px now look wrong */

Breaking change workflow:

1. Identify the need for breaking change
2. Evaluate alternatives that avoid breaking
3. Plan migration path
4. Deprecate rather than immediately remove
5. Communicate to consumers
6. Provide migration support
7. Execute change in major version

Key Considerations

• Breaking changes should be rare and justified
• Deprecation periods allow gradual migration
• Major versions signal breaking changes
• Migration tooling reduces consumer burden
• Communication should reach all affected teams
• Documentation should explain rationale
• Support should be available during transition
• Metrics can track migration progress

Common Questions

How should breaking changes be minimized?

Many potential breaking changes can be avoided with alternative approaches.

Additive changes instead of modifications:

// Instead of renaming
// Old: color.brand → New: color.primary

// Add new while keeping old
{
  "color": {
    "brand": { "$value": "{color.primary}" }, // Alias to new
    "primary": { "$value": "#3B82F6" }
  }
}

The old name continues working while new name is preferred.

Soft deprecation before hard removal:

// Token metadata
{
  "color.brand": {
    "$value": "#3B82F6",
    "$deprecated": true,
    "$deprecationMessage": "Use color.primary instead"
  }
}

Build warnings alert consumers without breaking functionality.

Value change isolation for significant modifications:

// Instead of changing existing token
{
  "spacing": {
    "md": { "$value": "16px" },
    "md-v2": { "$value": "8px" } // New scale available
  }
}

New values can be adopted incrementally.

How should breaking changes be communicated?

Communication should be early, clear, and repeated.

Advance notice:

## Upcoming Breaking Changes (v3.0 - Q2 2024)

The following tokens will be removed in version 3.0:
- `color.brand` - Use `color.primary` instead
- `spacing.tiny` - Use `spacing.xs` instead

Begin migrating now to prepare for the update.

Multiple channels:

• Changelog and release notes
• Documentation site announcements
• Team communication (Slack, email)
• Design system office hours
• Direct outreach to major consumers

Migration documentation:

## Migrating from v2 to v3

### Step 1: Update token references
Replace deprecated tokens with their replacements:

| Find | Replace with |
|------|--------------|
| `color.brand` | `color.primary` |

### Step 2: Run validation
\`\`\`bash
npx @company/tokens validate --deprecated-warning
\`\`\`

### Step 3: Update dependencies
\`\`\`bash
npm update @company/tokens@3.0.0
\`\`\`

How should migration support be provided?

Migration support reduces friction and demonstrates commitment to consumers.

Codemods automate straightforward changes:

// Token rename codemod
module.exports = function(file, api) {
  const j = api.jscodeshift;
  return j(file.source)
    .find(j.Literal, { value: 'color.brand' })
    .forEach(path => {
      path.replace(j.literal('color.primary'));
    })
    .toSource();
};

Validation tools identify migration needs:

$ npx @company/tokens validate ./src

Found 23 uses of deprecated tokens:
  src/Button.tsx:15 - color.brand (use color.primary)
  src/Card.tsx:8 - spacing.tiny (use spacing.xs)
  ...

Migration office hours provide direct help:

• Scheduled sessions for migration questions
• Pair programming for complex migrations
• Priority support during transition period

Phased rollout allows gradual adoption:

v3.0.0-alpha.1 - Early adopter testing
v3.0.0-beta.1 - Broader testing
v3.0.0 - General availability

Summary

Token breaking changes require careful management to maintain consumer trust. Minimizing breaking changes through additive approaches and deprecation periods reduces upgrade friction. When breaking changes are necessary, clear communication through multiple channels, comprehensive migration documentation, and active support smooth the transition. Major version numbers signal breaking changes following semantic versioning conventions.