CSS to Token Migration — Converting Hardcoded Values to Design Tokens

Migrating from CSS to Design Tokens

Most projects start with hardcoded values scattered across stylesheets. Migrating to design tokens is a multi-step process that can be done incrementally.

Step 1: Audit Existing Values

Scan your codebase for hardcoded values. Look for:

• Colors: Hex codes, RGB values, named colors
• Spacing: Pixel values in margin, padding, gap
• Font sizes: Arbitrary px/rem values
• Border radii: Mixed corner values
• Shadows: Inline box-shadow declarations

Step 2: Group and Deduplicate

You'll likely find many near-duplicates:

#333333 used 47 times
#323232 used 12 times  -> consolidate to one token
#2d2d2d used 8 times

Step 3: Define Token Names

Map groups to semantic names:

/* Before */
.header { color: #333333; }
.sidebar { color: #333333; }
.footer { color: #323232; }

/* After */
:root { --colors-text: #333333; }
.header { color: var(--colors-text); }
.sidebar { color: var(--colors-text); }
.footer { color: var(--colors-text); }

Step 4: Incremental Rollout

Don't refactor everything at once. Migrate category by category:

1. Colors first (most impactful, easiest to audit)
2. Spacing (second most common hardcoded values)
3. Typography (font sizes, weights, line heights)
4. Borders and shadows (least frequent)

Step 5: Enforce Token Usage

Add lint rules to prevent new hardcoded values:

• stylelint: Ban hex codes outside :root
• ESLint: Flag inline style objects with raw color values
• PR reviews: Check for token compliance

Common Pitfalls

• Too many tokens: Start with 30-50, not 300
• Too-specific names: --header-text-color is too narrow; --colors-text is better
• Forgetting dark mode: Plan token pairs from the start