I recently helped a client turn a sprawling, inconsistent Figma design system into a lean, token-driven workflow. If you’ve ever opened a file and felt your brain scramble trying to map colors, spacing, and component variants, you know why this feels urgent. In this article I’ll walk you through the practical steps I took — the audits, naming decisions, Figma plugins, and team processes — so you can migrate a messy Figma system into something token-based, predictable, and easy to maintain.

Why migrate to tokens?

Design tokens are the connective tissue between design and code. They turn visual decisions into a single source of truth: color palettes, type scales, spacing units, radii, elevation, and even motion timings. When your Figma file is full of hard-coded styles and duplicate components, maintenance becomes a nightmare. Tokens reduce cognitive load, help enforce consistency, and make handoff to developers far smoother.

Start with an audit (don’t skip this)

The first step is always to map what you actually have. I open the main production file and create an audit page with a simple inventory: colors, text styles, effects, spacing examples, and all ambiguous component states. You can do this manually, but I prefer a hybrid approach: use a plugin to extract tokens then human-verify.

Helpful plugins/tools:

  • Design Lint — finds inconsistent styles and orphaned layers
  • Figma Tokens — extracts styles into token JSON and helps preview
  • Instance Finder — identifies duplicate components/variants

    • My audit checklist contains items like:

  • All color swatches in use (and how many unique values)
  • Text styles (font family, weight, size, line height, letter spacing)
  • Spacing values used across components
  • Shadow/elevation patterns and their usages
  • Component variants and mismatched instance overrides

    • Design decisions: what becomes a token?

    Not every visual value needs to become a token. Tokens should represent decisions that are reused and worth centralizing. I group tokens into categories:

    Token Category Examples When to centralize
    Color primary, accent-500, neutral-100, text-high Always centralize palette and semantic colors
    Typography heading-1, body-14, caption-12 Centralize scales and roles, not every manual weight
    Spacing space-4, space-8, space-16 Use a base scale (4px or 8px) and stop adding ad-hoc values
    Elevation/Shadow elevation-1, elevation-2 Centralize patterns for depth and focus
    Motion duration-fast, easing-standard For consistent micro-interactions

    I prefer semantic tokens (e.g., button-background, text-muted) layered over raw tokens (e.g., blue-500). Semantic tokens let you change the brand palette later without rewriting component logic.

    Naming conventions that actually scale

    Spend time on a naming convention. It’s boring but crucial. My personal pattern is:

  • <category>.color.button.primary.default
  • <type>.<scale> — e.g., space.8, font.size.16

    • Keep names predictable and hierarchical. Avoid overly specific names that bake UI decisions into tokens, like blue-for-hero. Reserve those for component-level overrides if needed.

    Extracting tokens from Figma

    I usually extract tokens in two phases:

  • Auto-extract: Use Figma Tokens or Tokens Studio to pull existing styles into JSON. This gives a fast baseline.
  • Manual curation: Clean duplicates, rationalize near-duplicates (e.g., three slightly different neutral grays), and map raw colors to semantic roles.

    • When cleaning colors, group by perceptual similarity — tools like Adobe Color or even a quick visual swatch board in Figma help. Reduce your palette aggressively: most projects benefit from 6–12 core colors plus neutral scales.

    Refactor components incrementally

    Attempting a big-bang refactor rarely succeeds. I adopt an incremental approach:

  • Create a parallel “tokens” library file or a new team library in Figma.
  • Pick a non-critical set of components — e.g., buttons and form inputs — and rebind them to tokens.
  • Publish the updated library and ask the team to switch instances as they touch screens (or batch replace high-impact pages first).

    • While refactoring, enforce that components reference styles (Figma text styles, color styles) that are themselves linked to tokens. This creates a clean two-way binding: tokens → Figma styles → component instances.

    Bridging design and code

    For the handoff, export tokens in a format developers can ingest: JSON, SCSS variables, CSS custom properties, or platform-specific formats (iOS, Android). Figma Tokens plugin supports multiple output formats and can sync to Git via a simple export workflow.

    Pro tip: Use semantic tokens for CSS custom properties. Example:

  • --color-button-primary: var(--color-brand-500);
  • --space-8: 8px;

    • This lets developers compose tokens in the browser and makes runtime theming feasible.

    Tools that make this tolerable

    My go-to stack for a token migration:

  • Figma Tokens plugin — token authoring, export, and theme switching
  • Design Lint — finds inconsistencies before they cause trouble
  • Storybook (for devs) — verify UI components against tokens in isolation
  • Style Dictionary — for transforming and distributing tokens across platforms

    • Automate exports with CI so token changes run through a review process and publish to a shared package. That prevents silently breaking changes.

    Governance and team workflows

    After the technical migration, the bigger challenge is cultural. I helped my team adopt a few lightweight rules:

  • Make token changes via pull requests and design reviews — no direct edits in production files.
  • Document token intent in the design system handbook (what each token is for and example usage).
  • Set a regular cadence (monthly or quarterly) to review and prune tokens. Less is more.
  • Train folks on how to use the token-based components — short demos go a long way.

    • Testing and validation

    Run visual tests as you migrate components. Visual regression tools (Chromatic for Storybook, Percy) catch accidental visual changes when tokens update. On the design side, maintain a small "canary" page in Figma that showcases token-driven components in common states — primary, hover, disabled, error — so you can spot breakages quickly.

    Common pitfalls to avoid

  • Trying to migrate everything at once — pick a high-impact surface and iterate.
  • Over-tokenizing — not every single pixel needs a token. Focus on reuse.
  • Ignoring semantics — tokens that are color-based only (blue-500) make future theming harder.
  • No governance — without rules, tokens fragment into the same mess you started with.

    • One small hack that saved me: add a meta token called deprecated.* for values you want to retire. Keep them available for a transition period but clearly labeled so designers and devs avoid new usage.

    Migrating to a token-based workflow takes time, but the payoff is real: faster iterations, fewer surprises in production, and a happier collaboration between design and engineering. If you want, I can share a starter token JSON and a checklist I use during audits to speed up your migration.