Book a call

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

How AI coding agents use your design system, and where they go wrong

Ask a coding agent to build a screen and it reads, searches, opens files, writes code and runs checks, in a loop. Follow one real task through that loop, see exactly where design systems lose control of the result, and learn how to watch your own agents.

Diagram of the agent loop: read, plan, act, observe, write and check, with the design system's rules files, types and tools feeding the loop.
On this pageThe agent loop, in plain words
  1. The agent loop, in plain words
  2. A real task, step by step
  3. Where an agent gets design system knowledge
  4. The context window, and why less is more
  5. Six failure modes and what causes each
  6. The same task, with an AI-ready Harbor
  7. Not all agents are coding agents
  8. Try it: an "agent's-eye" audit in one hour
  9. Common questions when teams start
  10. The short version
  11. Frequently asked questions
  12. Further reading

The short answer

A coding agent builds UI in a loop: it reads instructions (your prompt plus any rules files), searches the repository, opens the files that look relevant, writes code, and runs checks such as the type checker. It only knows your design system through what it finds during that loop. If it can't find something quickly and unambiguously, it falls back on what it learned in training, which means generic Tailwind classes, Material UI habits and invented props. To steer it, put the right information where the agent looks first: a rules file, typed component APIs, tools that answer design system questions, and checks that fail loudly.

  • Agents trust whatever they find first. Deprecated code that's easy to find gets copied.
  • Types and lint errors are the clearest feedback an agent gets. Use them.
  • Part 2 of 20 in the series on AI-ready design systems.

The agent loop, in plain words

In part 1 we described an AI agent as a language model that can take actions in a loop. Here's what that loop looks like when you ask a coding agent to build a screen. Every agent product implements it differently, but the shape is the same in Claude Code, Cursor, GitHub Copilot's agent mode and OpenAI Codex.

1 · ReadYour prompt, the system instructions, and rules files like AGENTS.md
→
2 · PlanDecide what to look for: "a card component, the currency formatter, the page layout"
→
3 · ActCall a tool: search files, open a file, query an MCP server, run a command
→
4 · ObserveRead the result. Does it answer the question? Is more needed?
→
5 · WriteEdit code, then run type checks, lint and tests
→
6 · Repeat or finishErrors go back into step 4. No errors: report back
The agent loop. Steps 3–5 repeat many times on a single task. Your design system influences the result only at the points where it appears in steps 1, 3 and 5.
New words

Tool: an action the agent can ask for, described to the model by a name, a short description and the inputs it takes. "Read file", "search for text" and "run a terminal command" are built-in tools. Context: everything the model can see while it decides the next step. Each file it opens and each tool result is added to it, until the window fills up.

A real task, step by step

Let's follow one task through Harbor, the made-up design system from part 1. An engineer at Kestrel types this into a coding agent in the payroll web app's repository:

Add a "Pay run summary" card to the dashboard. It should show the
next pay date, total gross pay and number of employees, with a
"Review pay run" button. Use our design system.

Below is a simplified transcript of what the agent does in the repo as it was before any AI-readiness work. Tool names are generic; every product names them a little differently.

Agent · thinkingI need a card component, a button, and a way to format currency. "Our design system" probably means a package. Let me search.
Tool call · searchgrep -r "Card" src/ --include=*.tsx -l
Resultsrc/legacy/components/Card.tsx src/features/billing/BillingCard.tsx src/features/team/TeamCard.tsx … 31 more files
Tool call · read filesrc/features/team/TeamCard.tsx
Resultimport { Card } from "../../legacy/components/Card"; import { BtnPrimary } from "@kestrel/ui-old"; … <div style={{ color: "#1D4ED8", padding: 20 }}>
What went wrongThe agent learned the codebase's conventions from the first example it opened. That example happened to use the legacy Card, the old button package and a hard-coded blue.
Agent · writes codeCreates PayRunCard.tsx using legacy Card, BtnPrimary, a hard-coded #1D4ED8 and its own formatCurrency() helper.
Tool call · runnpm run typecheck
Result✓ No errors
Agent · reports"Done. I added a Pay run summary card using the existing Card and button components, following the patterns in TeamCard."
Illustration The agent did exactly what a reasonable newcomer would: copy the nearest example. Every check passed, so it had no reason to doubt itself.

Nothing here is a model failure. The agent searched, read a real file, followed the code it found, and verified its work with the only check available. The design system failed it in three ways:

  • Nothing told the agent which package was current. @kestrel/harbor and @kestrel/ui-old both exist, and the old one is used more often.
  • The legacy code was easy to find and looked legitimate. No @deprecated tag, no lint warning, no comment.
  • The checks didn't check the design system. Type checking passed because the legacy code is valid TypeScript. Nothing flagged the hard-coded colour.

Where an agent gets design system knowledge

An agent can learn about your system from six places. They differ a lot in how reliably the agent sees them and how much you control them. This ranking is the single most useful thing to understand when deciding where to invest.

SourceWhen the agent sees itYour controlTypical problem
Rules files (AGENTS.md, CLAUDE.md, Cursor rules)Loaded automatically at the start of every taskFullToo long, so key rules get lost; or missing entirely
Type definitions (.d.ts, prop types)When it opens a component or when the type checker runsFullProps typed as string instead of a list of allowed values
Tool results (MCP servers)When the agent decides to call the toolFullTool descriptions so vague the agent doesn't know when to call it
Existing code in the repoWhen search happens to surface itPartialOld patterns outnumber new ones, so they get copied
Web docsOnly if the agent can browse and chooses toPartialPrivate docs can't be reached; public ones may be outdated
Training dataAlways, as a fallbackNoneKnows popular open-source libraries, not yours
Sources ranked from most to least reliable. Invest at the top of the table first: rules files, types and tools are always seen and fully under your control.
Watch out

Existing code is the source agents rely on most and the one teams think about least. In a repo where 70% of buttons are the legacy one, an agent copying "the codebase's conventions" will choose the legacy one 70% of the time. Retiring or clearly marking legacy code is AI-readiness work.

The context window, and why less is more

Every file the agent opens takes up space in its context window. Modern models have large windows (hundreds of thousands of tokens, where a token is roughly three-quarters of a word), but bigger isn't the same as better. Research and practical experience both show models pay less attention to information buried in the middle of long contexts, and every irrelevant file is a chance to copy the wrong thing.

EXPENSIVE

Dumping everything

Pasting your whole 300-page docs site, or a 6,000-line token file, into the prompt. The agent has to find the needle itself, and old pages compete with new ones.

  • ~150,000 tokens used
  • Contradictions are all visible at once
EFFECTIVE

Just enough, on demand

A short rules file that says where things are, then tools the agent calls for exactly the component or token it needs.

  • ~3,000 tokens used
  • Only current information arrives
Illustration Token counts are illustrative. The principle holds whatever the model: give the agent a map and a way to ask, not the whole library.

This principle, sometimes called progressive disclosure, shapes the rest of this series. Rules files (part 6) are the map. Component metadata (part 4), token files (part 3) and docs (part 5) are what the agent asks for. MCP servers (part 7) are a precise way to ask.

Six failure modes and what causes each

Once you know the loop, agent mistakes become predictable. Here are the ones we see most, with the step of the loop where each goes wrong.

FailureExampleLoop stepRoot cause
Copying the nearest exampleLegacy Card copied from TeamCard3 · ActSearch returns old code first; nothing marks it as old
Training-data fallbackclassName="bg-blue-600 rounded-lg"2 · PlanAgent never found your tokens, so it used what it knows
Invented API<Button variant="destructive"> when the value is danger5 · WriteAgent guessed the value; the prop was typed as string, so nothing caught it
Wrong variantPrimary button for "Delete account"5 · WriteThe variant exists; the rule for when to use it isn't written anywhere the agent looked
Reinventing helpersA new formatCurrency() beside the system's formatMoney()2 · PlanUtilities aren't listed with the components
Silent success"Done!" with off-system UI6 · FinishNo check failed, so the agent had no signal
Each failure points to a specific fix. Silent success is the most damaging, because it hides all the others.

The same task, with an AI-ready Harbor

Now the same prompt, after Kestrel's team completed the work described in this series: an AGENTS.md in the repo, typed and described components, a small design system MCP server, and lint rules. Watch where each change shows up.

Agent · reads AGENTS.md (automatic)"UI must use @kestrel/harbor. Never import from @kestrel/ui-old or src/legacy. Look up components with the harbor MCP tools before writing UI. Format money with formatMoney() from @kestrel/harbor/format."
Tool call · harbor.search_components{ "query": "card with summary stats and an action" }
ResultStatCard: "Shows 1–4 key figures with an optional action. Use for dashboard summaries." · Card: "Generic container. Prefer StatCard for figures."
Tool call · harbor.get_component{ "name": "StatCard" }
Resultprops: title (string, required), stats (Stat[] 1–4), action (ReactNode) … usage: "One primary action at most. Use Button variant=secondary unless it's the page's main task." example: <StatCard title="…" stats={[…]} action={<Button variant="secondary">…</Button>} />
Agent · writes codeCreates PayRunCard.tsx with StatCard, Button variant="secondary" and formatMoney().
Tool call · runnpm run lint && npm run typecheck
Result✓ No errors
Agent · reports"Added PayRunCard using Harbor's StatCard (recommended for dashboard summaries) and a secondary Button, since the card's action isn't the page's main task."
Illustration Same model, same prompt. The difference: the rules file pointed the agent at the right package, a tool returned one clear answer with a usage rule, and lint would have caught a regression.

Notice that the agent's final message now explains why it chose the secondary variant. That happened because the usage rule was in the tool result. When the reasoning behind a decision is written down where agents can reach it, agents repeat it, and reviewers can check it.

Not all agents are coding agents

"AI agent" covers several kinds of tool, and each one reaches your design system differently. Know which ones your teams use, because the preparation differs.

KindExamplesWhat it reads from your systemPrepare by
Coding agentsClaude Code, Cursor, Copilot, CodexRepo files, rules files, types, MCP tools, terminal outputRules files, types, MCP server, lint (parts 4, 6, 7, 9)
Design-to-codeFigma's MCP server used from a coding agentFigma layers, variables, component names, Code Connect mappingsVariables, naming, Code Connect (part 8)
AI app buildersv0, Lovable, Bolt, Figma MakeUsually a component registry or uploaded package and a promptA registry or package with clear docs; check each tool's import options
Docs assistants"Ask the design system" chatbotsYour docs through search and retrievalStructured, chunkable docs (part 5)
Four kinds of agent. The source of truth underneath is the same for all of them; only the door differs.

Try it: an "agent's-eye" audit in one hour

The fastest way to learn how agents use your system is to watch one. You don't need any setup beyond a coding agent and a product repo.

  1. Pick three everyday tasks

    Choose tasks your teams actually do: a form with validation, a data table with a filter, a confirmation dialog for a destructive action. Write each as a one-paragraph prompt ending with "use our design system".

  2. Run each in a fresh session

    Start a new conversation for each so earlier context doesn't leak in. Don't help the agent. You're watching how it finds things on its own.

  3. Read the transcript, not just the code

    Most agents show their tool calls. Write down every file it opened and every search it ran. Which design system files did it never find?

  4. Ask it to explain its sources

    Follow up with: "List every design system component, token and helper you used, and where you learned about each." Agents are usually honest about this, and the answers are revealing.

  5. Score the output

    Count: off-system components, hard-coded values, wrong variants, invented props. Keep the numbers. They're your baseline for part 9.

TaskOff-system componentsHard-coded valuesWrong variantsInvented propsFound the system?
Settings form1402Partly
Employees table2710No
Delete dialog0111Yes
Illustration A baseline scorecard from Harbor's first audit. The "Found the system?" column usually explains the rest.

Common questions when teams start

"Can't we just tell it in the prompt?"

You can, and it helps for one task. But people forget, phrase it differently each time, and can't remember fifty components. Rules files and tools make the guidance automatic and consistent.

"Which model is best at design systems?"

Newer models follow instructions and use tools better, but no model can use information it never sees. The system-side work in this series pays off with every model.

"Should agents read our Storybook?"

Storybook stories are excellent examples. Storybook now offers an MCP addon that exposes a component manifest to agents (React first). We cover it in part 7.

"Why did it work yesterday and not today?"

Agents aren't deterministic: the same prompt can take a different search path. That's why one good run proves little, and why part 9 runs each task several times.

The short version

  • Agents work in a loop: read, plan, act, observe, write, check. Your system only matters where it appears in that loop.
  • Rules files, types and tool results are seen reliably; existing code and training data are where off-system habits come from.
  • Give the agent a short map and a precise way to ask, not your entire docs site.
  • Most failures trace to something findable: unmarked legacy code, undescribed tokens, unwritten usage rules, missing checks.
  • Watch an agent do three real tasks before you change anything.

Next: Design tokens for AI agents, where we fix the most common failure of all: hard-coded values.

Frequently asked questions

How do AI coding agents find components in a design system?

They read rules files loaded at the start of a task, search the repository, open files that look relevant, and call any tools they've been given, such as an MCP server. If none of these surface your system clearly, they copy nearby code or fall back on popular libraries from their training data.

Why does an AI agent use deprecated components?

Usually because deprecated code is easy to find (it's used in many files) and nothing marks it as deprecated. Add @deprecated tags, a "never use" list in the rules file, and a lint rule blocking new imports.

Why does AI generate hard-coded colours instead of design tokens?

The agent didn't find your tokens, or found them without explanations and couldn't choose. It falls back on values it saw nearby or on Tailwind defaults it knows from training. Describe tokens, point to them in the rules file and add a lint rule for raw values.

Is a bigger context window enough to solve this?

No. Large contexts full of conflicting or outdated information make mistakes more likely. Short, current, specific information retrieved when needed works better.

Do AI agents remember our design system between sessions?

Generally not, unless the product has a memory feature. Assume every session starts from zero, which is why rules files and tools matter: they give the same starting knowledge every time.

Further reading