Toolbox

Token Migration Playbook

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

What it is

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

When to use

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

How to use

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

Semantic token architecture is defined (you know what to migrate TO)
Visual regression testing exists (Chromatic, Percy or screenshot comparison)
At least one developer can write jscodeshift transforms

When NOT to use this

Token architecture isn't settled (migrating to moving target wastes effort)
No visual regression tests (you'll ship undetected visual bugs)
Codebase is small enough to find-replace manually (<50 files)

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

Token Migration Playbook (PDF)Token Migration Playbook (accessible HTML)

Alignment HandbookToken architecture that scales

The share link includes source tracking so LinkedIn traffic stays measurable in analytics.

Share on LinkedIn

Toolbox

Token Migration Playbook

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

What it is

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

When to use

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

How to use

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

Semantic token architecture is defined (you know what to migrate TO)
Visual regression testing exists (Chromatic, Percy or screenshot comparison)
At least one developer can write jscodeshift transforms

When NOT to use this

Token architecture isn't settled (migrating to moving target wastes effort)
No visual regression tests (you'll ship undetected visual bugs)
Codebase is small enough to find-replace manually (<50 files)

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

Token Migration Playbook (PDF)Token Migration Playbook (accessible HTML)

Alignment HandbookToken architecture that scales

The share link includes source tracking so LinkedIn traffic stays measurable in analytics.

Share on LinkedIn

Token Migration Playbook

What it is

When to use

How to use

Before you start

Downloads

Related

Token Migration Playbook

What it is

When to use

How to use

Before you start

Downloads

Related

What it is

When to use

How to use

Before you start

Downloads

Related

Share this resource

What it is

When to use

How to use

Before you start

Downloads

Related

Share this resource