Book a call

WritingAI-ready design systemsPart 1 of 20 in Making your design system AI-ready

What is an AI-ready design system? A complete guide for design system teams

AI agents are now some of your design system's busiest users. They read literally, can't ask questions and copy whatever they find first. What AI-ready actually means, the architecture behind it, a readiness score and a 30-day plan to start.

Diagram: a person's request flows to an AI agent, which reads rules files, MCP servers and docs built on one source of truth of tokens, components and Figma, checked by guardrails.
On this pageWhy this matters now
  1. Why this matters now
  2. The running example used in this series
  3. What "AI-ready" actually means
  4. The architecture of an AI-ready design system
  5. How agents get information: a five-minute primer
  6. The six most common reasons agents go off-system
  7. A readiness self-assessment
  8. Four levels of AI-readiness
  9. Where to start: a 30-day plan
  10. Common misconceptions
  11. The series, in order
  12. The short version
  13. Frequently asked questions
  14. Further reading

The short answer

An AI-ready design system is one an AI agent can find, read and follow without a person explaining it. In practice that means four things: one source of truth for tokens, components and docs; machine-readable formats (DTCG token JSON, component metadata, structured docs); a way for agents to reach it (rules files like AGENTS.md, and often an MCP server); and checks that catch mistakes (lint rules, tests and evals). Most teams don't need new technology to start. They need to fix the ambiguity people have been working around for years: duplicate components, unexplained tokens, out-of-date docs.

  • If a new engineer can't tell which of three buttons to use, an agent can't either. It will just guess faster.
  • Start by writing things down and removing duplicates. Add MCP servers and retrieval later.
  • This is part 1 of a 20-part series. Parts 2–10 cover one layer each; parts 11–20 answer the questions teams ask most.

Why this matters now

Until recently, everyone who used a design system was a person. People are good at filling gaps. When the docs say nothing about which button to use on a confirmation dialog, a designer asks on Slack, checks a similar screen, or remembers what the system lead said last quarter. A design system can survive a lot of ambiguity because its users absorb it.

That's changing. Engineers now ask coding assistants such as Claude Code, Cursor, GitHub Copilot and Codex to build screens. Designers use tools that generate UI from a prompt or a Figma frame. Product managers prototype with AI app builders. Each of these tools is a new user of your design system. It's a user that reads everything literally, can't ask a colleague, forgets everything between sessions, and works very fast.

An illustration: the same request, two systems

The request

An engineer asks a coding agent: "Add a settings page with a form for the company's name, payroll currency and a save button. Use our design system."

System A: not ready

The agent searches the repo and finds Button, BtnPrimary and LegacyButton. It picks the one that appears most often, which is the deprecated one. It hard-codes #2563EB because it saw it in an old file, and invents a currency dropdown.

System B: ready

The agent reads the repo's AGENTS.md, which points it to the component list. It asks the design system's MCP server for "form", gets the Form, TextField and Select components with their props and examples, uses color.action.primary.bg, and the lint check passes on the first try.

The difference isn't the AI model. It's the system. That's the most important idea in this series: agents amplify whatever your design system already is. A clear, consistent system becomes faster to use. An ambiguous one produces wrong UI faster than any human could.

New words

AI agent: a program built around a large language model (LLM) that can take actions in a loop: read files, run commands, call tools, look at the results, and decide what to do next. A chatbot only answers; an agent does work. Coding agent: an agent that works in a code repository, like Claude Code, Cursor's agent, GitHub Copilot's agent mode or OpenAI Codex.

The running example used in this series

To keep things concrete, all ten articles follow one made-up design system through the work of becoming AI-ready. It is an illustration, but every problem in it is one we've seen in real systems.

THE COMPANY

Kestrel, a payroll SaaS

Four product teams, about 40 engineers and 9 designers. A web app in React, an admin console, and a marketing site.

THE SYSTEM

Harbor, five years old

Published as @kestrel/harbor. A Figma library, a Storybook, docs in Confluence, tokens in a SCSS file. Two part-time maintainers.

WHAT'S MESSY

The usual history

  • Three button components from three eras
  • 14 blues, 6 of them named
  • Figma components called "Card copy 2"
  • Docs last updated in 2024
THE GOAL

Agents build on-system UI

An engineer or designer asking an agent for a screen should get one built from Harbor's real parts, using real tokens, that passes review.

Illustration Harbor and Kestrel are made up. Numbers are illustrative.

What "AI-ready" actually means

"AI-ready" gets used loosely, so here is a definition you can check against. A design system is AI-ready when an agent with no prior knowledge of it can do four things reliably:

  1. Find the right thing

    Given a task ("a destructive confirmation dialog"), it can discover which components, tokens and patterns apply, without stumbling onto deprecated or duplicate versions first.

  2. Understand how to use it

    It can read each part's purpose, its props and allowed values, when to use it and when not to, and see a correct example.

  3. Use it correctly

    It produces code (or a design) that uses those parts the way the system intends: correct variants, semantic tokens, accessible markup.

  4. Know when it got it wrong

    Automated checks tell it, and the person reviewing, when the output drifts off-system, so it can fix the problem before anyone else sees it.

Notice that none of these mention a specific AI product. Tools change every few months. These four abilities stay the same. They're also exactly what a new human team member needs, which is why work on AI-readiness almost always improves the system for people too.

The architecture of an AI-ready design system

Here's the whole picture in one diagram. Read it from the top: a person asks for something, an agent does the work, and the agent reaches into the design system through a few well-defined doors. Everything below the agent is your design system, arranged so a machine can use it.

Person
Designer, engineer or PM"Build a payroll settings page using Harbor"
Agent
Coding or design agentClaude Code, Cursor, Copilot, Codex, Figma's tools
Access layer
Rules filesAGENTS.md, CLAUDE.md, Cursor rules · part 6
MCP serversYour own, Storybook's, Figma's · parts 7–8
RetrievalSearch over the docs · part 5
Source of truth
TokensDTCG JSON with descriptions · part 3
Component metadataProps, variants, rules · part 4
DocsStructured, current · part 5
Figma libraryVariables, Code Connect · part 8
Guardrails
Lint · tests · evalsCatch off-system output before review · part 9
An AI-ready design system, layer by layer. Each layer is covered by one article in this series; part 10 shows how to get an existing system there in phases.

Three things about this diagram are worth noticing:

  • The source of truth is at the bottom, not the AI. If the tokens, metadata and docs disagree with each other, no amount of clever tooling on top will make the agent reliable.
  • The access layer is thin. Rules files are plain text. An MCP server is usually a few hundred lines of code that reads the files below it. Neither should contain design decisions of its own.
  • Guardrails close the loop. Without checks, you find out the agent used the wrong button when a customer does.

How agents get information: a five-minute primer

You don't need to know how language models work inside to make a system AI-ready. You need four ideas, because every decision in this series follows from them. We'll go deeper in part 2.

IdeaIn plain wordsWhat it means for your system
Context windowThe text the model can "see" at one time: the prompt, files it opened, tool results. Everything else might as well not exist.Your system has to be found and loaded into that window. Clear, compact information wins over long, rambling pages.
Training dataWhat the model learned before you ever used it: public code, docs, websites.The model knows Material UI and Tailwind well. It has never seen your private system. Without guidance, it falls back to what it knows.
Tool callingThe model can ask the program running it to do something, like "read this file" or "search the component list", and get the result back.You can give agents tools that answer design system questions exactly, instead of hoping they find the right file. This is what MCP standardises.
Retrieval (RAG)Searching a knowledge base for the passages most relevant to a question, then putting just those into the context window.Your docs need to be split into self-contained sections that make sense when read alone.
Four ideas that explain almost every agent behaviour. Documented See Anthropic's and OpenAI's tool-use guides in further reading.
New words

MCP (Model Context Protocol): an open standard, first published by Anthropic in November 2024 and now stewarded by the Linux Foundation's Agentic AI Foundation, for connecting AI tools to data and actions. Write one MCP server for your design system and any MCP-capable agent can use it. RAG (retrieval-augmented generation): look up relevant information first, then generate an answer using it.

The six most common reasons agents go off-system

When teams first try agents on their design system, the same failures appear again and again. Each one traces back to something in the system, not the model. Use this table to diagnose what you're seeing.

What you seeThe real causeThe fixArticle
Agent uses a deprecated componentOld and new versions both look valid; nothing marks one as retiredDeprecation metadata, rules file "never use" list, lint4, 6, 9
Hard-coded colours and spacingTokens have no descriptions, or the agent can't find the token listDTCG tokens with $description, a token lookup tool3, 7
Wrong variant (primary button for "Delete")The docs show variants but don't say when to use eachUsage rules in component metadata4, 5
Invented components or propsThe agent never saw the real list, so it fell back on training dataAn inventory the agent can query; type-checking4, 7, 9
Correct parts, wrong layoutPatterns (forms, empty states) aren't written downPattern docs with examples, retrievable by task5
Figma-to-code output ignores the systemFigma layers use raw values; no mapping from Figma components to codeVariables, clean names, Code Connect8
Diagnose before you buy tools. Practitioner view In our experience the first two rows account for most of the problems teams report.

A readiness self-assessment

Before changing anything, score your system. Give each statement 0 (not true), 1 (partly) or 2 (true). Be honest; the point is to find your weakest layer, because that's where an agent will fail first.

LayerStatementScore
TokensAll colours, spacing, type and radius in code come from named tokens, stored in one source file0–2
Semantic tokens have a written description of their job0–2
ComponentsThere is exactly one current component for each job; old ones are marked deprecated0–2
Each component's props, variants and allowed values are available as data (types, JSON), not only prose0–2
DocsEvery component page says when to use it and when not to0–2
Docs are generated from, or checked against, the code, so they can't silently go stale0–2
AccessProduct repos have a rules file (AGENTS.md or similar) that points to the design system0–2
Agents can query components and tokens through a tool (MCP or similar)0–2
FigmaLibrary components use variables, not raw values, and have clear names0–2
Figma components are mapped to code components (Code Connect or equivalent)0–2
GuardrailsLint rules flag hard-coded values and deprecated imports0–2
You have a repeatable test of how well agents build with the system0–2
Twelve statements, 24 points. Under 8: start with the foundations (parts 3–5). 8–16: add access and guardrails (parts 6–9). Over 16: you're ready to measure and tune.

Four levels of AI-readiness

You don't need to reach the top level in one go. Most teams move up one level at a time, and each level is useful on its own.

0Human-onlyKnowledge lives in people's heads, Slack threads and old files. Agents guess.
1Written downOne current component per job. Tokens named and described. A rules file in each repo.
2Machine-readableDTCG tokens, component metadata, structured docs. Agents can query them through MCP.
3VerifiedLint, tests and evals measure how often agents stay on-system, and the numbers improve over time.
Most teams can reach level 1 in a few weeks of cleanup. Level 2 is where agents start to be reliably useful.

Where to start: a 30-day plan

If you only do one thing after reading this, do this sequence. It's ordered so each step makes the next one easier, and so you get value even if you stop halfway.

  1. Week 1: watch an agent fail

    Pick three real tasks from your backlog (a form, a table, a dialog). Ask a coding agent to build each with your design system and save the results. Note every off-system choice. This is your baseline, and it tells you which layer to fix first.

  2. Week 1: write a rules file

    Add an AGENTS.md to one product repo with the package name, the "never use" list of deprecated components, and where tokens live. It takes an hour and usually fixes the worst failures. See part 6.

  3. Week 2: describe your semantic tokens

    Add a one-sentence $description to every semantic token: what it's for and when not to use it. See part 3.

  4. Week 3: mark what's deprecated

    Every old component gets a @deprecated tag pointing to its replacement, and a lint rule blocks new imports of it. See part 4 and part 9.

  5. Week 4: rerun the three tasks

    Same prompts, same agent. Compare. If things improved, you have your case for investing in metadata, an MCP server and Figma cleanup next.

Tip

Keep the three baseline prompts and outputs in a folder in your design system repo. They become your first evaluation set in part 9, and they're the most convincing evidence you can show a sponsor.

Common misconceptions

MYTH

"We need to fine-tune a model on our design system"

Almost never. Fine-tuning is expensive and goes stale with every release. Giving the agent your current system at the moment it works (through files, tools and retrieval) is cheaper and always up to date.

MYTH

"An MCP server will fix it"

An MCP server is a door. If what's behind it is three conflicting button docs, the agent gets three conflicting answers, faster. Clean the source first.

MYTH

"AI-ready means writing docs for robots"

The structure that helps agents (clear purpose, when-not-to-use, examples, one version) is what people have always needed. You write it once, for both.

MYTH

"Agents will replace the design system team"

Agents make the system's decisions more important, not less: every unclear decision now gets copied at machine speed. Someone has to own those decisions.

The series, in order

Each article stands on its own, but they're written to be read in sequence. Parts 1–10 build an AI-ready system layer by layer; parts 11–20 answer the questions and problems teams run into along the way.

PartArticleYou'll be able to…
1What is an AI-ready design system? (this article)Explain the goal and score your system
2How AI coding agents use your design systemPredict what an agent will read and where it will go wrong
3Design tokens for AI agentsWrite DTCG tokens an agent can choose between correctly
4Component metadata for AI agentsDescribe each component as data an agent can check against
5Documentation AI agents can useStructure docs so search and retrieval return the right section
6AGENTS.md, llms.txt and rules filesGive every agent the essentials before it starts
7Build an MCP server for your design systemLet agents query components and tokens directly
8Figma to code with AIPrepare your Figma library for agents
9Guardrails for AI-generated UICatch and measure off-system output
10Make a legacy design system AI-readyPlan the whole change for an existing system
11Why does AI ignore my design system?Diagnose and fix the ten most common causes
12How much context does an agent need?Keep rules and tools small; load detail on demand
13Why is AI-generated UI inaccessible?Build accessibility into components and checks
14Figma variables out of sync with tokens?Reconcile, automate one direction, check for drift
15Figma Make, v0 and Lovable with your systemSet up kits, registries and guidelines
16Is shadcn/ui better for AI?Decide whether to switch, and publish a registry
17Can designers do this without coding?Own the decisions agents need written down
18Who owns the AI rules?Assign owners, review rules, use agent feedback
19Is it safe to connect AI tools?Manage data, prompt injection and credentials
20How do you prove the ROI?Build a business case from your own numbers

The short version

  • An AI-ready design system is one an agent can find, understand, use correctly and get checked against.
  • Agents amplify what your system already is: clarity becomes speed; ambiguity becomes fast mistakes.
  • The layers: one source of truth, machine-readable formats, an access layer (rules files, MCP, retrieval), and guardrails.
  • Start by watching an agent fail on three real tasks, then fix the cheapest causes: a rules file, token descriptions, deprecations.
  • Everything that helps agents also helps new people on your team.

Next: How AI coding agents use your design system, a step-by-step look at what an agent actually does when you ask it to build a screen.

Frequently asked questions

What is an AI-ready design system?

A design system that AI agents can discover, understand and use correctly without human help: one source of truth for tokens, components and docs, stored in machine-readable formats, reachable through rules files or an MCP server, and backed by automated checks.

Do I need an MCP server to make my design system AI-ready?

Not to start. A rules file such as AGENTS.md, described tokens and clear deprecations fix most early failures. An MCP server becomes worthwhile when you have many components, several repos, or want agents to look things up precisely rather than search files.

Should we fine-tune a model on our design system?

Rarely. Fine-tuning is costly and goes out of date with every release. Supplying current information at the time of the task, through files, tools and retrieval, is cheaper and stays accurate.

How long does it take to make a design system AI-ready?

A first useful level (a rules file, token descriptions, deprecations) takes a few weeks. Machine-readable metadata, an MCP server and Figma cleanup typically take one to three months for a mid-sized system, done in phases alongside normal work.

Does making a design system AI-ready help human users too?

Yes. Clear purposes, when-not-to-use guidance, one current version of each component and automated checks are what new designers and engineers need as well.

Further reading