Back to Work
Cover · token map, before and after (16:9)
Every hex value in the codebase, traced and mapped to a semantic role.

Design Systems · Tokens · 2025

The theming migration — AI as a craft multiplier, not a shortcut

Migrating a product’s color layer from accumulated hex values to a semantic token system — and using AI to do the repetitive work without letting it make the taste decisions.

Problem

300 files, and no way to gate it

Our design token system needed a full architectural overhaul — moving from an aging, inconsistent structure to a proper semantic taxonomy, across 300+ files touching every corner of the application.

A change that size, with no way to gate it behind a feature flag, is exactly the kind of project that quietly balloons from weeks into months if the approach isn’t right from the start.

Process

Plan like the plan is the work

I treated the AI-assisted planning phase as seriously as the implementation itself. Before touching a single line of code, I went through extensive back-and-forth with an AI agent to work out the right approach, then prototyped the migration on a single page first — deliberately, so I wasn’t burning tokens or time if the strategy needed to change.

Once the approach was validated, I broke the full rollout into smaller iterative passes instead of one big-bang migration, which kept the risk manageable even though the change touched the entire application. I stayed mindful of budget throughout, since the work did tap into our limit for AI tooling spend.

Token map — hex values mapped to semantic roles
The token map, before and after.
AI did the mechanical half. Not the taste.

I didn’t stop at getting it working. I followed up by building debugging and audit tooling — an agent skill that now catches token compliance issues at write time instead of catching them later in code review, so the system stays maintainable for the roughly seven engineers who work in it, not just for me.

Prototyping the migration on one page first is what kept a three-week problem from becoming a three-month one.

Technical depth

What the work actually involved

  • Directed AI to identify every token in use across the codebase, trace each to its hex value, and map it to the correct token in the new semantic system.
  • Designed and validated the migration approach on a single page before scaling it to the full application.
  • Built a follow-up compliance tool (an agent skill) that shifts token governance from code-review-time to write-time.

Outcome

Cut what would have been three to four weeks of manual rework down to about five days — roughly a 75% reduction. The resulting token system is now expected practice on every new feature across the product.

Screens — the same surface on the old and new token system