Agent-ready design systems: the rules AI agents and AI mock-ups need to follow

To make a design system usable by AI coding agents and AI design tools, give them the system in the forms they actually read, put it where each tool looks on every task, and enforce the rules that matter most with checks that fail the build. In practice that means tokens in a standard format, components with clear names and usage notes, a short set of rules files written as instructions (with a do, a don't and a reason for each hard decision), real examples of finished screens, and lint and visual tests that reject off-system output whether or not the agent read the rules.

A system written for people to read gets skimmed. A system written for agents to follow can be enforced. The rest of this page shows how to write one.

Why AI made the design system matter more

AI tools did not make design systems less important. They made the system the only thing standing between twenty people's prompts and a product that looks like twenty products.

Before agents, a design system was mostly read by designers and front-end engineers, who absorbed its conventions over time and asked each other when unsure. Now product managers, engineers and founders make screens with AI design and coding tools, and each tool starts from whatever context it is given. When that context is thin, the output drifts. Atlassian's design system team describes the failure plainly: agents working from scattered sources "find outdated patterns, miss accessibility requirements, or invent components that don't exist in our system."

The market has moved to meet this. Figma now lets teams attach guidelines files to published libraries so its agent follows existing patterns, an open beta listed in its Config India 2026 release notes alongside updates to its MCP server. Google Labs published DESIGN.md, an open format for describing a visual identity to coding agents. The tools are ready to read your system. The question is whether your system is written so they can.

What an agent reads, and what it ignores

An agent works only from what is in its context for the task in front of it. For a design system, that means:

• Tokens and variables: colour, type, spacing and radius values with names an agent can reference instead of typing raw values.
• Components and their APIs: names, variants and props, in the library and in code.
• Descriptions attached to assets: the notes on a Figma component, variable or style, or the doc comment on a coded component.
• Rules files and instruction files: Markdown the tool loads automatically, such as library guidelines or a repository's instruction file.
• Examples: complete screens that show how the pieces combine.
• Whatever an MCP server returns: structured answers fetched on demand.

What it misses is just as predictable. Atlassian's team found most of their documentation was "designed for people to view, not for machines to read effectively", with pages heavy on images and visual information that code cannot read. Figma's MCP best practices point at the same gaps inside design files: default layer names such as Frame1268 say nothing about what a layer is for, absolute positioning leaves the agent guessing how a layout should respond, and without a link between a design component and its code the agent "has to guess which code component matches."

Two more gaps catch teams out. First, a rule pasted into one chat is gone in the next unless it lives in a file the tool loads every time. Second, more context is not always better. When Atlassian tested a single DESIGN.md file as the only guidance in production, the agents generally read through component implementations to find usage guidance the file had to leave out, and were more likely to re-create components than import the shared ones.

What to give agents, and where it lives

Each artefact closes a specific gap. Ship the ones that close the gaps you see most.

A few notes on the standards behind the table. The W3C Design Tokens Community Group published its Design Tokens Format Module 2025.10 on 28 October 2025 as a Final Community Group Report (a community group report, not a W3C Standard), and states that the specification "is considered stable." Each token carries a $value, an optional $type and an optional $description, and the description is where the token's purpose goes, in words an agent can read. If tokens are new to your leadership team, our plain-language guide to design tokens covers the basics.

Figma's Code Connect links design components to components in your repositories, and its MCP best practices call that link "the most effective way to get your agent to reuse your real components." AGENTS.md, stewarded by the Agentic AI Foundation under the Linux Foundation, is an open format for instructions to coding agents; the nearest file in the directory tree takes precedence, so a design system package can carry its own rules.

How to write rules an agent will follow

Most design system documentation describes options. Agents need decisions. Figma's guidance on writing guidelines files is the clearest primary advice we have found, and it applies well beyond Figma:

• Write for the decisions people get wrong. Start with the mistakes your team keeps correcting, and the places people struggle to choose a component, variant or pattern.
• Use scenarios. For each hard decision, describe the situation, an example of what to do, an example of what not to do, and the reason.
• Recommend, do not list. Give one clear recommendation rather than only describing the options. Say what the agent must never do when a rule has no exceptions, and spell out the exceptions when it does.
• Start where the effect is largest. Figma suggests colours, spacing and corner radius first: which variables to use and their semantic roles, how the spacing scale applies inside and between components, and which radius belongs to which surface.
• Keep it small. Figma recommends three to eight focused files with a combined size under 100 KB, without repeating guidance across files; the hard limit per library is 200 KB.
• Learn from bad output. Use the agent's previous outputs to find conventions that are obvious to experienced designers but that the agent cannot infer, such as the order in which a screen is composed or which of two similarly named components to use.

Here is the difference in practice. These rules are our own illustrations, with placeholder names.

Written badly: "Use colour thoughtfully and stay consistent with the brand. Destructive actions should feel serious."

Written well:

Scenario: a confirmation dialogue for an action that deletes data. Do: use Button with variant="danger" for the confirming action, and variant="secondary" for Cancel. Don't: recolour a primary button with a red hex value, or put the destructive action on the left. Why: the danger variant carries tested focus, hover and contrast states in both themes; a recoloured button carries none of them.

Written badly: "Buttons can be disabled where appropriate."

Written well: a single, checkable answer to a question people actually ask. Atlassian's structured content, asked whether a button should be disabled in a form, surfaced the system's guidance to keep it enabled during validation. One decision, stated as an instruction, retrievable when the question comes up.

An anti-patterns file follows the same shape: name the tempting mistake, say what to use instead, and say why. Two habits keep these files honest. Never let an agent invent token or component names while drafting them (Figma's own drafting prompt says to mark missing information as a question instead). And remove generic design advice that any model already knows: every line should say something only your system can say.

Guidelines can carry more than visual rules. Figma's help centre guide to teaching its agent shows a rule about the product's audience, telling the agent which placeholder savings goals suit young first-time savers. Audience, tone and realistic content are where an unguided mock-up looks generic.

Where the rules live: library, repository, MCP server

Each tool reads from a different place, so the same rule may need to reach all three.

In the design library. In Figma, guidelines files are attached to a published library and are "automatically provided to the agent in the background" whenever someone asks the agent to design with that library. Put guidance about one component, style or variable in that asset's description, and use guidelines files for conventions the agent cannot work out from the assets alone. Examples count too: add a page named Examples, or add _example to a component's name, and the agent can reference up to 200 examples per library.

In the repository. Coding agents load instruction files from the repository: AGENTS.md, CLAUDE.md for Claude Code, or a rules folder for Cursor. Figma's MCP guidance suggests rules such as always using components from the design system path, avoiding hard-coded values in favour of tokens, and never adding new icon packages. Its MCP server even includes a create_design_system_rules prompt that drafts a rules file from your codebase; treat the draft as a starting point to correct, not a finished rule set.

Behind an MCP server. The Model Context Protocol lets an agent fetch context when it needs it rather than loading everything up front. Atlassian built schemas for its components, icons, tokens, lint rules and foundational guidelines, kept in TypeScript files next to the code, and serves them through its own MCP server. Compared with agents working without an MCP, it reports 4.9% more accurate code, 11% fewer errors, tasks completed 34% faster, 16% fewer tokens and 26% fewer tool calls. Smaller systems can start lighter: Cloudscape publishes every documentation page as Markdown with an llms.txt index that agents and MCP servers use to find pages, and the shadcn MCP server can browse and install components from a company's private registry. If your system is built on shadcn/ui, our piece on what your design system still needs to define covers the gaps the registry leaves.

In a DESIGN.md file. DESIGN.md pairs machine-readable tokens in YAML with prose rationale under sections in a set order, ending in Do's and Don'ts. It is at version alpha, and its command-line tool can lint the file, diff two versions and export tokens to Tailwind or the W3C token format. Atlassian's test is the most useful evidence on where it fits. It turned a one-shot dashboard prototype from generic output into something recognisably Atlassian. In a production codebase, as the only guidance for a simple log-in screen, it needed about 92% more tokens than their MCP server and showed about 2.7 times the variance in token use between runs; the authors say the results "should not be seen as conclusive." Their file had to shrink to 80 KB from about 2.5 MB of guidance, which meant cutting much of the usage guidance for their components. Our reading: use DESIGN.md for prototyping tools and visual direction, and keep production agents on your real components.

Keep one source. The pattern worth copying from Atlassian is not any single format but the pipeline: one structured source generates the MCP content, the agent skill and the DESIGN.md file. Their warning applies to every team: "Documentation that drifts from the codebase is worse than no documentation at all."

How to review AI-made mock-ups by non-designers

When a product manager brings an AI-made mock-up, treat it as a well-formed question about what they need, not as a specification. Review it against the system, not against taste:

1. Is it built from the library? Components should be instances from the published library, not detached copies or look-alikes.
2. Does it use variables? Colours, spacing, radius and type should resolve to tokens, with no raw values.
3. Does the composition match an example? If the screen is a form or a dashboard, compare it with the library's example of one.
4. Are the states there? Empty, loading, error and permission states are where generated screens are thinnest.
5. Is the content real? Placeholder copy, data and audience should fit the product, which guidelines can steer.
6. Is it accessible? Contrast, focus order and labels still need a person's check.

The most important step comes after the review. When the same correction appears twice, fix it at the source. Figma's advice is to update an asset description for a single component, add or revise an example for a composition, or update a guidelines file for a decision that applies across the library, then rerun a similar task. Deciding who owns those updates is a governance question; our guide to design system governance models covers who decides and how.

Checks that fail a build

Rules files make good output more likely. Checks make bad output impossible to merge. As Atlassian puts it, lint rules "enforce quality frontend coding standards for humans and agents alike with no token spend at all." Turn your most important rules into checks like these:

• Token-only styles. Reject raw values in styles. Stylelint's built-in color-no-hex disallows hex colours, and Atlassian's ensure-design-token-usage treats hard-coded values as violations and expects a token instead: colour by default, and spacing values such as padding: '16px' once spacing is added to the rule's domains option.
• System components only. ESLint's no-restricted-imports blocks imports you name, with a custom message, so an agent that reaches for a raw UI package is told which system component to use.
• Typed component APIs. Variants defined as a fixed set of allowed values in TypeScript turn an invented variant name into a type error.
• Visual regression tests. Playwright's toHaveScreenshot compares each run with reference screenshots; run it in the same environment that produced the baselines, because rendering varies with operating system, hardware and settings.
• Lint the design file itself. The DESIGN.md linter exits with an error on broken token references and warns on component colour pairs below the WCAG AA contrast minimum of 4.5:1; its diff command fails when a new version has more errors or warnings than the last.

Checks also feed the loop. An agent that runs the linter sees the failure and fixes it, which is cheaper than a reviewer finding it later. What review is still for, once checks catch the mechanical problems, is covered in our piece on accepting AI-generated front-end code.

What to do this quarter

Where you start depends on what your system already has.

If the system itself is not yet settled, that comes first: no rules file fixes a system nobody has agreed on, which is the work of design system strategy. For teams whose Figma library and code have drifted apart, building the coded side with token-only styles is front-end design system work. For choosing among the tools themselves, see our guide to AI design-to-code tools for product teams; this page stays on rules and checks.

A five-step plan for a team starting this month:

1. Collect the evidence. Gather a sample of recent AI-made screens and list every correction you made to them. That list is your first guidelines file.
2. Write the first rules. Cover colours, spacing and radius, plus an anti-patterns file, as scenarios with a do, a don't and a reason.
3. Put them where tools look. Attach them to the library, add an instruction file at the repository root that points to your tokens and components, and link design components to code.
4. Enforce the top three. Pick the three rules at the top of your correction list and make each one a check that fails the build.
5. Rerun and assign. Run the same prompts again, compare the output, and name the person who updates the source whenever a correction repeats.