AI-Friendly Design System

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.

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, Clore — tools that could read a Figma file and generate React components. The promise was thrilling. The reality was not.

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.

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.

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

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

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

Tier 1 — Primitive tokens (Global): The raw values. Color primitives, spacing numbers, font sizes. These never get used directly in components.

Tier 2 — Semantic tokens: Purpose-driven names that map to primitives. This is where AI gets its context.

Tier 3 — Component tokens: The most specific layer. These reference semantic tokens and map directly to component properties.

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.

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:

1. Slash-separated hierarchy: Category/Context/State — AI can parse this as a path
2. No spaces, no special characters: Underscores for multi-word, no hyphens (inconsistent across tools)
3. State as suffix: Button/Primary/Hover, not Hover/Button/Primary
4. Consistent vocabulary: Background not Bg, Disabled not Inactive, Default not Normal

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.

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.

{
  "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.

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

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).

// 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.

// 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 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.

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.

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.

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.

After three months:

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

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.

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.

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.

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.

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.