How to Give Your AI Coding Agent a Real Design System
Your coding agent already writes the CSS. The problem is what it designs to. Give it a real spec to build to instead of the trained-mean average it otherwise guesses at.
Ask Cursor or Claude Code for a "clean pricing page" and it builds to the trained mean: the average of everything it saw in training. Safe blue, 8px radius, 16px body, a shadow that could belong to any of ten thousand sites. Competent, and completely generic.
A design system fixes that by giving the agent a real spec to build to instead of an average to guess at. This guide covers what that means, the two honest ways to get one, and how to wire it into Cursor, Claude Code, Codex, Windsurf, or VS Code over MCP in about a minute.
For grounding, the numbers come from The Measured Web, a live corpus of 579 real products (548 decoded into full design systems, 3,784 sections sliced with per-section specs). It is curated toward products people admire (Stripe, Vercel, Linear, Mercury, Raycast), so its norms describe good design, not average design. That is the point: you want your agent building toward the former.
Why AI agents design generic UIs
An agent has no house style. Left to itself it reaches for the statistical center of its training data. You can see that center in the measured corpus: the median product scores 82 out of 100, ships an 8px border radius, sets 16px body text and a 64px hero, uses a blue accent (34% of them), and runs a 250ms transition. None of that is wrong. It is just the middle. When your agent defaults to the middle on every decision, the result reads as a template even when every individual choice is defensible.
The weakest measured dimension in the corpus is spacing (a 68 median, versus 88 for typography). Agents inherit that weakness, because rhythm and density are exactly the kind of thing that averages into mush. A design system pins these decisions down so the agent stops averaging.
What a design system for an agent actually is
For a human, a design system is a Figma library and a doc. For an agent, it has to be machine-readable. In practice that means a small, structured spec the agent can read while it works:
- Color roles, not just hex values: background, text, primary, accent, link, plus real button foreground and background.
- A type scale: the heading and body families, and the actual size ladder (h1, h2, body) with weights.
- A spacing grid: the base unit and the step scale. 53% of the measured corpus is on a 4px grid and 41% on 8px, so this is a real, decidable choice.
- Radii, shadows, and motion: the corner scale, the elevation ramp, and the transition durations and easings.
- Component specs: the real anatomy of a primary button, a card, a modal, including hover, focus, and active states.
Delivered as a file (DESIGN.md, Tailwind config, CSS variables, or W3C design tokens) or over a live connection, this is what lets the agent build to a spec instead of a vibe.
Two honest ways to get one
Option 1: build your own (and when that is the right call)
If you have a brand and a design team, encode your own system. The clean path today is either Figma's Dev Mode MCP server (so the agent reads your real frames, variables, and tokens) or structured JSON tokens plus usage rules in an AGENTS.md file the agent consults automatically. Do not invent a new format; the W3C design token spec is the safe target.
Be clear with yourself here: if you already maintain a real design system, build-your-own is the right answer and you do not need anything else in this guide. It keeps the source of truth in your hands. The cost is that it is real work to set up and keep current, and it only covers your own system.
Option 2: decode a real one
You do not always have a maintained system, and you are not limited to what lives in your Figma. Any live product on the web already ships a real, working design system. You can decode it and hand the measured spec to your agent.
That is what Mozaika does. It reads a site's design system straight from the live DOM (measured colors, type ladder, spacing, radii, shadows, motion, and component states, measured rather than inferred from a screenshot) and serves it to your agent over MCP while it builds. It has done this for 579 real products, and you can decode any URL yourself.
Pick by your situation. Build your own when the system is yours and maintained. Decode when you want to match a real product, learn from one, or start from a real spec fast.
Wire it into your agent over MCP
MCP (the Model Context Protocol) is an open standard, so the same connection works across Cursor, Claude Code, Codex, Windsurf, and VS Code. To connect Mozaika:
claude mcp add --transport http mozaika https://mozaika.design/mcp \ --header "Authorization: Bearer <YOUR_MOZAIKA_KEY>"
Grab a free key at mozaika.design/connect. No card, 25 tool calls a month on the free tier. Calls without a valid key return 401.
Then add one rule to your AGENTS.md or .cursor/rules so the agent consults it without being told each time:
## Design When building or restyling UI, pull the target design system with the Mozaika MCP (get_design_system) and build to those exact roles, type scale, spacing, and radii. Do not invent tokens.
Now, mid-build, the agent can call get_design_system("linear.app") and get back a DESIGN.md it constructs the UI against. Ask it to "design like Linear" and it works from Linear's measured spec, not its memory of what Linear roughly looks like.
What "measured" buys you over screenshots
Most "AI-readable" design references are still screenshots or hand-tagged libraries. A screenshot cannot tell an agent the exact WCAG contrast pair, the real hover state, the easing curve, or whether the grid is 4px or 8px. Measured specs can, because they are read from the running page:
- Contrast and color roles come from the actual computed styles, so the agent uses colors by role and keeps text legible.
- The type ladder is the detected scale, not an eyeballed guess.
- Motion is the real duration and easing (the measured median transition is 250ms in a tight 150 to 300ms band), so animations feel like the source instead of a default ease.
- Component states include the hover, focus, and active specs a static image never carries.
You can also point the same measurement at your own site. get_score("yourdomain.com") returns a 0 to 100 audit from the live DOM with an evidence-anchored fix list, ranked against the measured corpus, so the agent knows not just what to build but where the current build is weak.
A quick worked example
Say you are building a settings page and you want it to feel like Vercel.
- In your agent:
get_design_system("vercel.com"). - The agent receives Vercel's measured roles, type scale, radii, and button spec as a DESIGN.md.
- You prompt: "Build the settings page. Use this design system exactly, colors by role, the real type scale and radii. Do not invent values."
- The agent builds to the spec. The primary button matches the real radius and foreground, the spacing follows the real grid, the type ladder is the real one.
The difference from a screenshot prompt is that nothing is approximated. The agent is not interpreting an image. It is reading numbers.
Frequently asked questions
Can AI coding agents use a design system?
Yes. Agents like Cursor, Claude Code, and Codex can read a machine-readable design system (structured tokens plus rules) over MCP or from an AGENTS.md file, and build UI to those specs instead of to trained-mean defaults.
How do I give Cursor or Claude Code a design system?
Either encode your own as JSON tokens plus rules and connect it via AGENTS.md or Figma's Dev Mode MCP, or connect a service like Mozaika over MCP that serves measured design systems decoded from real products. Add a short rule so the agent consults it automatically.
What is the difference between a screenshot and a measured design system?
A screenshot is an image the agent has to interpret. A measured design system is the structured spec (color roles, type scale, spacing grid, radii, motion, component states) read from the live DOM, so the agent builds to exact values rather than guessing from pixels.
How is this different from Mobbin or Refero?
Mobbin and Refero are excellent research libraries for humans, and Refero also has an MCP. The difference is what the MCP returns. A screenshot library hands your agent references to look at. Mozaika hands it measured specs to build with: hex tokens, type scales, spacing, per section. If you are doing visual research or need mobile app coverage, use Mobbin or Refero. If your output is code an agent writes, you want the measured spec.
Do I need Figma?
No. Figma with the Dev Mode MCP works well when the design lives in Figma. If you want to match or learn from a real shipped product, decoding its live design system does not require Figma at all.
Is it free?
Mozaika has a free tier: a key with 25 tool calls a month, no card, at mozaika.design/connect. The Measured Web dataset is free to cite under CC BY 4.0.
Start here
Give your agent something real to build to. Grab a free key at mozaika.design/connect, add the MCP line above, and tell your agent to design like any product you admire. It will build to a measured spec, not the average of its training data.