Legacy Token Migration

Legacy token migration moves from outdated or problematic token systems to improved architectures. Legacy systems may have emerged organically without planning, predate modern tooling, or follow deprecated patterns. Migration modernizes these systems while preserving the design decisions they encode.

What Is Legacy Token Migration

Legacy token migration is the process of transitioning from an existing token implementation to a new, improved system. This involves analyzing the legacy system, designing the target architecture, mapping old to new, migrating consumers, and eventually decommissioning the legacy system.

Migration differs from refactoring in scope: refactoring improves within an existing paradigm, while migration may involve fundamental architecture changes.

How Legacy Token Migration Works

Legacy system characteristics:

Common legacy patterns:

// Sass variables (no runtime theming)
$color-primary: #3B82F6;
$spacing-medium: 16px;

// Flat structure (no hierarchy)
$primary: #3B82F6;
$secondary: #6B7280;
$medium: 16px;

// No semantic layer (values used directly)
.button { background: $blue-500; }

Modern target:

{
  "color": {
    "primitive": {
      "blue": { "500": { "$value": "#3B82F6" } }
    },
    "semantic": {
      "action": { "primary": { "$value": "{color.primitive.blue.500}" } }
    }
  }
}

Migration phases:

1. Assessment:

Legacy system audit:
- Format: Sass variables
- Token count: 127
- Consumers: 8 applications
- Pain points: No theming, inconsistent naming
- Value to preserve: Color palette, spacing scale

2. Design target:

Target architecture:
- Format: JSON with Style Dictionary
- Layers: Primitive → Semantic → Component
- Theming: Light/dark support
- Outputs: CSS, iOS, Android

3. Create mapping:

const migration = {
  '$color-primary': 'color.action.primary',
  '$spacing-medium': 'spacing.md',
  '$blue-500': 'color.primitive.blue.500'
};

Key Considerations

• Preserve design intent, not just values
• Plan for parallel operation during transition
• Prioritize consumer migration by impact
• Maintain documentation of mapping
• Support rollback if issues emerge
• Communicate timeline clearly
• Budget adequate time for migration
• Celebrate migration completion

Common Questions

How should legacy systems be assessed?

Assessment reveals what exists and informs target design.

Inventory analysis:

Token inventory:
- Total tokens: 127
- Colors: 45 (12 duplicates)
- Spacing: 18 (5 off-scale)
- Typography: 24
- Shadows: 8
- Other: 32

Format analysis:
- Sass variables: 89 tokens
- CSS custom properties: 38 tokens
- Mixed usage patterns

Usage analysis:

# Find all token usages across codebase
grep -r "\$color" ./src --include="*.scss" | wc -l
# Result: 1,247 usages

Problem identification:

Issues found:
1. No semantic layer - primitive values everywhere
2. Duplicate colors with different names
3. Spacing values not on consistent scale
4. No dark mode support
5. Manual updates to native platforms

How should parallel operation be managed?

Parallel operation allows gradual migration without big-bang cutover.

Compatibility layer:

// Legacy variable that references new token
$color-primary: var(--color-action-primary);

// Components using $color-primary continue working
// But value now comes from new system

Feature flags:

// Toggle between systems
const useNewTokens = process.env.TOKEN_VERSION === 'v2';

const tokens = useNewTokens
  ? require('./tokens-v2')
  : require('./tokens-legacy');

Gradual rollout:

Migration phases:
Week 1-2: App A migrates (pilot)
Week 3-4: App B, C migrate
Week 5-6: Remaining apps
Week 7: Legacy system deprecated
Week 8: Legacy system removed

How should success be measured?

Success metrics track migration progress and outcomes.

Progress metrics:

Migration progress:
- Tokens migrated: 127/127 (100%)
- Applications migrated: 6/8 (75%)
- Legacy usages remaining: 312/1247 (25%)

Quality metrics:

Post-migration quality:
- Theming support: ✓ Light/dark working
- Platform outputs: ✓ Web, iOS, Android
- Build time: 2.3s (was 4.7s)
- Token validation: All passing

Outcome metrics:

Migration outcomes:
- Developer satisfaction: 4.2/5 (up from 2.8)
- Theme switch capability: New functionality
- Maintenance time: -40%
- Bug reports: -60%

Summary

Legacy token migration transitions outdated token systems to modern architectures. Assessment reveals existing tokens, formats, and problems. Target architecture design addresses identified issues. Parallel operation through compatibility layers enables gradual migration without disruption. Success measurement tracks progress and validates outcomes. Thorough planning and patient execution produce sustainable modern token systems.