AI-Ready Design Systems

A design system is only as useful as its ability to be consumed. In a traditional workflow, the consumer is a human engineer who reads the docs and applies the rules. In an AI-assisted workflow, the consumer is an agent that needs machine-readable rules — not prose, not screenshots, not tribal knowledge shared over Slack.

Making your design system AI-ready means enriching tokens with metadata that agents can query and enforce at build time. This is one of the highest-leverage investments a design engineer can make: teams that do it report 70-80% fewer AI code-generation issues and dramatically less post-generation cleanup.

The Token Schema

Standard design tokens store a name, value, and type. AI-ready tokens add semantic metadata for agent consumption:

{
  "tokens": {
    "button-bg-primary": {
      "value": "#3b82f6",
      "type": "color",
      "description": "Primary button background in light mode",
      "semanticRole": "brand",
      "doNotPairWith": ["surface-error"],
      "minContrast": "4.5:1",
      "darkModeAlias": "button-bg-primary-dark",
      "componentMapping": {
        "react": "bg-primary",
        "css": "var(--color-primary)"
      }
    },
    "surface-error": {
      "value": "#fef2f2",
      "type": "color",
      "description": "Error surface background",
      "semanticRole": "surface",
      "doNotPairWith": ["button-bg-primary"],
      "minContrast": "3:1"
    }
  },
  "generativeRules": [
    {
      "if": { "variant": "primary", "mode": "dark" },
      "then": { "useToken": "button-bg-primary-dark" }
    },
    {
      "if": { "variant": "destructive", "mode": "light" },
      "then": { "useToken": "button-bg-destructive" }
    }
  ]
}

How Agents Consume Design Systems

There are three tiers of integration, each progressively more powerful:

Tier 1: Rules files (AGENTS.md / .cursorrules / CLAUDE.md)

The simplest approach. Embed token rules and constraints in the project's context file. Every agent reads this before writing code.

# Design system rules
- All colors come from globals.css --color-* variables — no inline values
- Never pair --color-primary with --color-surface-error
- Buttons use variant prop: "primary" | "secondary" | "ghost" | "destructive"
- Every interactive element needs visible focus styles (ring-2)
- Respect prefers-reduced-motion — wrap animations in motion-safe:

Pros: Zero setup, works everywhere. Cons: No dynamic queries, static context only.

Tier 2: Token JSON + Style Dictionary

Export your tokens to a structured JSON file the agent can reference. Style Dictionary or the W3C Design Token Format are the standard.

Prompt: "Read the tokens from design-tokens/tokens.json
and generate a button component. Use only tokens from that file."

Pros: Machine-readable, single source of truth. Cons: Agent must have the file path; no query interface.

Tier 3: Design System MCP Server

An MCP (Model Context Protocol) server exposes your tokens, rules, and component metadata as a set of tools the agent can call on demand. This is the production-grade approach used by teams at Miro, Spotify, and Figma.

Agent queries the MCP server:
→ getTokens("button-*") returns all button-related tokens
→ getRules() returns generative constraints
→ validateComponent(componentCode) checks for token violations

Pros: Dynamic queries, real-time validation, low context overhead. Cons: Requires setup (but Figma MCP + Code Connect covers most needs).

Enforcement in Practice

How Cursor and Claude Code use design system data

Case study: Miro's "Aura" AI teammate

Miro enriched their icon and token libraries with useCases, doNotPairWith, and deprecationFlags metadata. Their AI teammate queries the MCP server before generating any UI — it automatically refuses invalid token pairings and suggests the correct alternative. The result: AI-generated components that match the design system on first attempt ~90% of the time.

Case study: Spotify Encore

Spotify's Encore design system saw AI agents systematically bypassing their tokens — generating hard-coded green #1DB954 instead of using the semantic token. After adding machine-readable metadata and exposing it through an MCP endpoint, token hallucination dropped dramatically and design-system support questions fell 70-80%.

Foundations

1. Add metadata to your existing tokens — start with doNotPairWith and minContrast. These catch the most common AI errors.
2. Export to a structured JSON file — use Style Dictionary or the W3C Design Token Format.
3. Add token rules to AGENTS.md — the simple path that works immediately.
4. Evaluate the Figma MCP server — if you use Figma, this alone covers most of your needs.
5. Consider a lightweight Design System MCP — if you need advanced constraint enforcement or have a large component library.