Skip to the case study

[Design systems][AI][Tokens]

How I prepared my design system for its newest user, AI

Design-to-code accuracy from 60% to 90%, by making design systems machine-readable.

Design-to-code accuracy went from 60% to 90%.

Role
Design Systems Lead
Timeline
3 months
Toolkit
Design tokens · Figma Variables API · AI / LLM tooling (Figma MCP) · JSON schema design · Technical documentation
A Figma-style semantic tokens panel listing AI-readable token names such as Color/Brand/Primary and Spacing/Button/Horizontal

Problem

AI tools could read a Figma file but not the design system inside it. They guessed at colors, rebuilt components from scratch, and produced code that broke the moment a token changed.

Approach

Restructured the design system into a 3-tier token architecture (primitive → semantic → component) plus a JSON bridge file AI could actually parse, the same way an API documents itself for another program.

Result

Figma-to-React accuracy went from 60% to 90% average across three AI tools, with a 60% drop in design-to-code iteration cycles.

Every design system speaks two languages: one for humans, one for machines. I built the bridge between them and cut design-to-code conversion error rate from 40% to 10%.

The problem: AI tools like Figma MCP could convert designs to React code, but the output looked nothing like the actual design system: hardcoded colors, wrong spacing, generic components instead of the real ones. The insight: AI doesn't see your Figma file the way a developer does. It needs structured tokens, named variables, and a machine-readable JSON mapping to produce accurate output. The result: 90% accuracy in Figma-to-React conversion, components that AI can instantiate correctly on the first try, and a design system that speaks to both humans and machines.

01The gap nobody was talking about

Every design team I'd worked with had the same problem, stated differently. Engineers would open a Figma file, see a beautiful component library, and then rebuild it from scratch using hardcoded values. The design system existed in Figma. It existed in code. They were never the same thing.

Then AI entered the picture. Figma MCP, Cursor, Claude, Cline: tools that could read a Figma file and generate React components. The promise was thrilling. The reality was not.

This isn't just my problem. Figma's own AI report found that 68% of developers are now using AI to write code. But only 32% of designers and developers say they trust the output. The conclusion, drawn from that data by one of Figma's Designer Advocates, was the same one I kept running into by trial and error: context is everything.

Screenshot of a Figma blog post by a Figma Designer Advocate, citing Figma's AI report that 68% of developers use AI to write code but only 32% trust the output, and comparing an AI agent without design system context to a new engineer shipping code before onboarding
Source: Figma Blog, “Design systems and AI: Why MCP servers are the unlock”

I ran the same test across three AI tools. I gave each one a Figma file with a fully built design system: components, variants, auto-layout. The output:

  • Colors: AI picked the nearest hex value instead of using the actual design token. #1A73E8 became #1976D2. Close enough for a human eye. Wrong enough to break a theme.

  • Spacing: Padding was 23px instead of the 24px defined in our 4px base grid. Margins were arbitrary. The spatial rhythm was gone.

  • Components: AI created new components from scratch instead of referencing the existing ones. A button was built from divs and spans instead of using the Button component from the library.

  • Typography: Font sizes were pixel values instead of token references. Line heights were computed, not semantic.

The output looked almost right. But “almost right” in a design system is broken. Tokens exist so that one change propagates everywhere. If AI bypasses the token system, the entire point of the design system collapses.

The AI generated a button that looked perfect. Then we changed our primary color in the design system, and the AI-generated button didn't update. It was a fossil, a snapshot of a system it never actually used.

Try it

Change the brand colour

Pick a new value for Color/Brand/Primary. Everything on this page that reads the token follows it. The AI-generated button doesn't: it copied a hex value instead of referencing the token.

Value of Color/Brand/Primary

References the token

Get started
background: var(--color-brand-primary);

Up to date

Generated with a hardcoded hex

Get started
background-color: #1976D2;

Still #1976D2: a fossil of the old system

Looks right, for now

02Reframing the problem

I spent two weeks debugging AI output before I realised I was solving the wrong problem. The issue wasn't the AI tools. The issue was that my design system was designed for human eyes, not machine parsing.

Humans can look at a Figma file and intuitively understand that a blue button uses the primary brand color. AI reads the file as a data structure. If the data structure says fill: #1A73E8, that's what it uses, regardless of whether a variable called Color/Brand/Primary exists in the file.

The realisation was simple but fundamental: AI needs the same kind of structured, named, machine-readable system that APIs provide for code. Design tokens aren't just a consistency tool for humans. They're an interface for machines.

I reframed the work: I wasn't building a design system. I was building an API that happened to be expressed in Figma.

Screenshot from The Design System Guide newsletter stating that tokens are the API contract between design and code, and that well-documented tokens tell AI what each value means and where it belongs
Source: The Design System Guide by Romina Kavcic, “Design tokens that AI can actually read”

Figma has since shipped its own version of this idea: Dev Mode MCP Server and Code Connect link a design component directly to its real code implementation. My token/JSON layer solves the step before that: it makes sure the values feeding into any of it (Code Connect included) are ones AI can actually trust, instead of guessing at colors and spacing from a static file.

To be precise about what actually changed: I didn't make the AI smarter. I gave it a system precise enough that it stopped needing to guess.

03The process: five phases

  1. Phase 1Audit what exists

    Before changing anything, I mapped every component, every style, every value across the existing design system. The audit revealed three categories:

    CategoryCountAI-friendly?
    Components with proper variants12Partially: variants existed but weren't named for machine parsing
    Hardcoded style values847No: colors, spacing, typography all inline
    Components without variants38No: single-state, no structured data

    847 hardcoded values. Each one a potential point of failure when AI tries to convert the design.

  2. Phase 2Build the variable architecture

    Figma's variable system is the foundation. I restructured the entire design system around three tiers:

    Tier 1Primitive tokens (Global)

    The raw values. Color primitives, spacing numbers, font sizes. These never get used directly in components.

    TokenValue
    Color/Blue/50#E3F2FD
    Color/Blue/100#BBDEFB
    Color/Blue/500#1A73E8
    Color/Blue/900#0D47A1
    Spacing/00px
    Spacing/14px
    Spacing/28px
    Spacing/312px
    Spacing/416px
    Spacing/624px
    Spacing/832px
    Spacing/1248px

    Tier 2Semantic tokens

    Purpose-driven names that map to primitives. This is where AI gets its context.

    TokenMaps to
    Color/Brand/Primary→ Color/Blue/500
    Color/Brand/Primary/Hover→ Color/Blue/600
    Color/Brand/Primary/Active→ Color/Blue/700
    Color/Text/Primary→ Color/Gray/900
    Color/Text/Secondary→ Color/Gray/600
    Color/Text/Disabled→ Color/Gray/400
    Color/Surface/Base→ Color/White
    Color/Surface/Raised→ Color/Gray/50
    Color/Surface/Overlay→ Color/Black/20
    Spacing/Button/Horizontal→ Spacing/4
    Spacing/Button/Vertical→ Spacing/2
    Spacing/Card/Padding→ Spacing/6
    Spacing/Section/Gap→ Spacing/8

    Tier 3Component tokens

    The most specific layer. These reference semantic tokens and map directly to component properties.

    TokenMaps to
    Button/Primary/Background→ Color/Brand/Primary
    Button/Primary/Background/Hover→ Color/Brand/Primary/Hover
    Button/Primary/Text→ Color/White
    Button/Primary/Radius→ Radius/md
    Button/Primary/Height→ Size/10
    Input/Border/Default→ Color/Gray/300
    Input/Border/Focus→ Color/Brand/Primary
    Input/Background→ Color/Surface/Base
    Input/Height→ Size/10

    Why three tiers, not two? Because AI needs the semantic layer to make decisions. If it only sees primitives, it picks the wrong blue for a text color. If it only sees component tokens, it can't adapt when the brand changes. The semantic layer gives AI the intent behind each value.

  3. Phase 3Name everything for machine consumption

    This was the most time-consuming phase and the most important. I renamed every variable, every component, every property with a consistent, parseable naming convention.

    The naming rules:

    • Slash-separated hierarchy: Category/Context/State (AI can parse this as a path)
    • No spaces, no special characters in Figma: underscores for multi-word segments there. The generated JSON and CSS output follow their own ecosystem conventions instead (camelCase keys, kebab-case custom properties), so the same token can be named correctly in both places.
    • State as suffix: Button/Primary/Hover, not Hover/Button/Primary
    • Consistent vocabulary: Background not Bg, Disabled not Inactive, Default not Normal
    BeforeAfter
    blue-500Color/Blue/500
    button_blueButton/Primary/Background
    hover stateButton/Primary/Background/Hover
    16px paddingSpacing/Button/Horizontal

    The naming convention isn't aesthetic. It's an interface contract. Every slash is a level of hierarchy that AI can navigate. Every consistent suffix tells AI what state it's looking at.

  4. Phase 4Create the JSON bridge

    Figma variables live in Figma. React code lives in code. The JSON file is the translation layer.

    I exported every variable collection from Figma and structured it as a hierarchical JSON file that maps directly to CSS custom properties and React component props.

    figma-tokens.json

    {
      "colors": {
        "brand": {
          "primary": {
            "value": "#1A73E8",
            "cssVar": "--color-brand-primary",
            "figmaVariable": "Color/Brand/Primary",
            "usedIn": ["Button/Primary", "Link/Default", "Checkbox/Checked"]
          },
          "primary-hover": {
            "value": "#1557B0",
            "cssVar": "--color-brand-primary-hover",
            "figmaVariable": "Color/Brand/Primary/Hover",
            "usedIn": ["Button/Primary/Hover"]
          }
        }
      },
      "spacing": {
        "button": {
          "horizontal": {
            "value": "16px",
            "cssVar": "--spacing-button-horizontal",
            "figmaVariable": "Spacing/Button/Horizontal"
          }
        }
      }
    }

    What makes this JSON different from a simple token export:

    figmaVariable
    the exact path in Figma, so AI can cross-reference
    cssVar
    the generated CSS custom property name
    usedIn
    which components reference this token, so AI knows the context
    value
    the actual value as fallback

    This file is the single source of truth. Figma reads it. React reads it. AI reads it. When I update a token in Figma, I update it in the JSON, and the change propagates to both the design file and the codebase.

  5. Phase 5Validate with AI tools

    I tested the new system across multiple AI tools and LLMs:

    Figma-to-React accuracy by AI tool
    ToolBefore (generic DS)After (AI-friendly DS)Improvement
    Figma MCP + Cursor55%88%+33 points
    Figma MCP + Claude65%93%+28 points
    Figma MCP + Cline60%89%+29 points
    Average60%90%+30 points

    What “accuracy” means here: correct colors (actual token, not nearest hex), correct spacing (token-based, not arbitrary), correct component references (library component, not rebuilt), correct typography tokens (semantic sizes, not pixels), correct responsive behavior (breakpoint-aware).

04What changed in the AI output

Before: AI guessed based on visual proximity

// AI-generated button (before)
<div style="background-color: #1976D2; padding: 10px 16px; border-radius: 4px;">
  <span style="color: white; font-size: 14px; font-weight: 500;">Click me</span>
</div>
Hardcoded values. Wrong blue. No component reference. No token system.

After: AI referenced the actual design system

// AI-generated button (after)
import { Button } from '@/components/ui/button';

<Button variant="primary" size="default">
  Click me
</Button>
Uses the real component. Tokens flow through the component's internal styling. One change to the token updates this everywhere.

The JSON made AI think in systems, not pixels

The breakthrough wasn't just better naming. It was that the JSON file gave AI a system to reference. Without it, AI looked at a blue rectangle and tried to reproduce the blue rectangle. With it, AI looked at Button/Primary and understood: this is a component, it has states, it uses these tokens, it appears in these contexts.

AI stopped being a pixel copier and started being a system participant.

05The ripple effects

Designers benefit too

The structured naming convention improved human work as well. New designers onboarding to the system could understand the token hierarchy by reading the names. Color/Text/Secondary tells you exactly what it's for and where it belongs. gray-600 doesn't.

Engineering handoff got faster

Engineers stopped asking “what color is this?” and “what spacing did you use?” The JSON file answered both questions. Pull requests that previously needed 3–4 rounds of design review dropped to 1–2.

The system compounds

Every new component I add follows the same token architecture. Every new token I add gets the JSON entry. The AI accuracy improves with each addition because the mapping gets richer. Of the original 50 audited components, 12 already had proper variants and the other 38 got retrofitted onto the new tiers; the rest of the growth came from building new components on that same architecture as the product kept shipping.

After three months:

  • 156components with proper variants and tokens
  • 320variables across all three tiers
  • 90%average accuracy across AI tools
  • 60%reduction in design-to-code iteration cycles

06What I'd do differently

  1. Start with the JSON, not end with it

    I built the Figma variables first, then exported to JSON. If I'd designed the JSON schema first (thinking about what AI needs to see), the Figma variable structure would have been cleaner from the start. The JSON is the contract. Design the contract first.

  2. Name for AI before naming for humans

    I initially named variables the way I thought designers would expect: Primary Blue, Small Padding, Body Text. Then I renamed for machine parsing: Color/Brand/Primary, Spacing/Button/Horizontal, Font/Size/Base. The machine-friendly names turned out to be more readable for humans too. Hierarchy via slashes beats naming via adjectives.

  3. Validate with AI tools at every phase, not just the end

    I built the entire variable system before testing with AI. Several naming patterns that seemed logical to me were confusing to AI. A naming convention is only as good as the tools that consume it. Test early, test often.

  4. Document the naming convention as a living spec, not a README

    The naming rules live in a document that AI reads before generating code. This document is the most important artifact in the system, more important than the tokens themselves. A naming convention without documentation is just vibes.

07What this means for design systems

Design systems were built for two audiences: designers and developers. There's a third audience now, and it's growing fast: AI tools that read, interpret, and generate from your design files.

If your design system is optimized only for human eyes, AI will bypass it. It'll pick the wrong tokens, rebuild your components, and produce output that looks right but breaks the moment you update a value.

The design systems that will thrive in an AI-native workflow are the ones that treat their token structure as an API: well-documented, consistently named, machine-readable, and validated against the tools that consume it.

I built that system. The 90% accuracy number isn't the end: it's the baseline. Every token I add, every component I structure, every naming convention I enforce pushes that number higher. The design system isn't just a source of truth for the team anymore. It's a source of truth for the machines that build with the team.

  • 40% → 10%Design-code error rate
  • 3–4 → 1–2Design review rounds per PR
  • 1st tryAI component instantiation

The best design system is one that both humans and AI can use without asking questions. I built the version that makes that possible.