Toolbox

Token Migration Playbook

Step-by-step guide for migrating to semantic tokens.

What it is

Purpose and scope.

A playbook for transitioning from hard-coded values or core tokens to a semantic token architecture.

When to use

Signals this is the right tool.

When theming, dark mode or brand changes are blocked by raw values in code.

How to use

Minimum steps to get value quickly.

Audit token usage: grep codebase for hex codes (#[0-9a-f]{3,6}), rgb values, px values
Map findings: create spreadsheet with columns [file, line, raw value, semantic token replacement]
Add enforcement: ESLint no-restricted-imports rule blocking core token imports
Write codemod: jscodeshift transform for JS/TS, postcss plugin for CSS — start with colors
Run codemod on one feature: review diff, fix edge cases, run visual regression
Migrate remaining features in batches: one per sprint until complete

Before you start

Prerequisites and when to skip this.

Prerequisites

When NOT to use this

Consider instead

Only need dark mode for new features: Use semantic tokens going forward, leave legacy as-is
Legacy codebase scheduled for rewrite: Don't migrate — build new code with semantic tokens

Downloads

Grab the files and ship.

Keep the loop tight.