Claude Code and Cursor ship off-brand UI when your design system isn't machine-readable. What actually needs to change, with a real before/after.
Claude Code and Cursor don't know your design system unless you've made it legible to them. An agent has two sources: the code already in the repo, and whatever docs are linked from there. No teammate to ask, no Figma file to squint at, no institutional memory of "we don't actually use that component anymore." If the answer to "what token do I use here" isn't written down in a form the agent can parse, it does what any capable pattern-matcher does with a gap — it guesses, confidently, in valid syntax.
This isn't a Claude Code problem or a Cursor problem specifically. It's what happens when documentation built for humans — who infer, ask, or eyeball a comp — gets handed to something that has none of those options.
An agent generating a component doesn't reason about brand intent. It reasons about the nearest match: what does existing code in this repo look like, what does the prompt ask for, what's the statistically likely completion. When your system is consistent and well-labeled, that's an asset — the agent converges on the right pattern fast. When it isn't, the agent converges just as fast on the wrong one, because "wrong" isn't a category it can detect on its own.
In practice this shows up in four recurring ways, and they compound:
Token semantics. A token named blue-500 or a raw value like #2E5BFF tells an agent what a color looks like, not what it's for. It can't distinguish an action color from a decorative one, so it applies either wherever a color is needed. color-action-primary isn't just a better name — it's the difference between a rule the agent can follow and one it has to guess at.
Component parity. Figma has a Card. Code has three things that resemble it — Card, CardLegacy, a one-off <div> styled to match. Nothing states which is canonical, so the agent either duplicates or picks arbitrarily.
Naming drift. The same thing is called primary in one file, brand in another, blue-2 in a third. Every reader — human or agent — has to reverse-engineer which name is current.
No machine-readable source of truth. The real rules live in a PDF, a Slack thread, or a departed designer's head. There's nothing in the repo an agent could read even if it wanted to follow the rules exactly.
None of this is new — design systems have always had drift. What's new is who's reading them at volume. A human developer hits an inconsistency once, asks in Slack, and moves on. An agent hits it on every single task, at whatever pace you're running it, and it doesn't ask — it ships.
To make the failure mode concrete, here's an illustrative version of what that looks like end to end:
Prompt: "Add a warning banner above the checkout form."
Without a legible system: the agent finds no semantic warning token, no Banner component in the index, and no rule against inventing one. It writes a new <div> with an inline background: #FFF3CD, borrows padding values from the nearest component it can see, and ships a banner that is visually close but on-system in name only — a fourteenth variant nobody asked for.
With a legible system: the agent resolves Banner from the component index, finds it takes a variant="warning" prop mapped to color-feedback-warning-bg, and reuses it. Zero new CSS, zero new token, one line of code.
The difference isn't that the second agent is smarter. It's that the second agent had somewhere to look.
Three things close most of the gap, and they're the same three things a new hire would need — except a new hire can survive without them by asking around, and an agent can't.
Semantic tokens, not raw values. The token layer is the first thing an agent touches on almost any UI task, so it's the highest-leverage fix. A hierarchy that goes primitive → semantic → component — where components are only allowed to reference the semantic layer — gives the agent a name that encodes intent (color-action-primary, space-inset-md) instead of a value that encodes only appearance (blue-500, 16px). The same discipline applies to renaming drift away: one name, color-action, not three competing ones.
Documentation the agent can execute, not just read. "Follow our brand guidelines" is a value statement — nothing to check code against. "Components reference semantic tokens only; a raw hex in a component is a bug" is a rule an agent can test itself against before it finishes a task. The difference is phrasing things as constraints instead of preferences: agents weigh "prefer" loosely and "bug" or "must" literally. This is also where a component index earns its keep — a table of component → code path → Figma key → variants means the agent can look up whether something already exists instead of writing a new one because it didn't know to check.
An explicit Figma ↔ code mapping. This is what Code Connect (or an equivalent mapping layer) is for: it turns "these two things happen to look alike" into "this Figma node is this code component, full stop." Without it, an agent asked to build a screen from a Figma link is translating by resemblance — and resemblance is exactly where Card_v2_final, Button-FINAL-v3, and Group 128 come from. With the mapping in place, the agent resolves a node to a component the same way every time.
We've done this at product scale, not just component scale: re-architecting an enterprise platform's design system to be machine-readable meant rebuilding 180+ components and 800+ tokens into four disciplined tiers, with an explicit Figma ↔ code mapping replacing the informal "these look similar" relationship that existed before. Every engagement like that ends with a consumability test — an agent is asked to build agreed screens from the system alone, unaided, and where it guesses, that's the gap that still needs closing. On that engagement, the system's AI-readiness score moved from 38 to 91 out of 100. We don't publish the scoring method here — it's proprietary to the audit — but the test itself is simple to describe: can an agent build the thing correctly without asking a human. Before, no. After, yes.
Once the underlying system is legible, you still need to decide where to write that down for an agent to find — and it's tempting to put everything in one file. Don't. The two documents serve different readers and should stay separate.
DESIGN.md (or your existing design system documentation) is the full reference. Rationale, history, the complete token catalog, accessibility guidelines, deprecated patterns and why they were deprecated, links to the Figma file and any governance discussions. This is where a human — a new designer, a new engineer, an auditor — goes to understand why the system is shaped the way it is. It can be as long as it needs to be.
CLAUDE.md is the operational subset an agent reads on every task. Sources of truth (paths, not descriptions), the token rule, the component index, naming conventions, and what to do when unsure. No philosophy, no history — just the constraints and the lookups an agent needs to act correctly right now. It should be short enough that reading it doesn't cost more than the task itself; we keep these under roughly 200 lines.
The relationship between them only works in one direction: CLAUDE.md is a distilled, always-current pointer into DESIGN.md and the real system artifacts, not a parallel description of them. If a token is renamed in Figma and DESIGN.md updates but CLAUDE.md doesn't, the agent is now working from a file that lies — confidently. We wrote the full annotated structure for this file, with a copyable template, in Writing a CLAUDE.md your design system respects.
You don't need a formal audit to get a first read on where your system stands. These are the questions worth asking before you hand a repo to an agent and expect on-system output:
Does every component have one name, and is it the same name in Figma, in code, and in the docs?
Are your tokens semantic (color-action-primary) rather than raw (blue-500, #2E5BFF)?
Does every Figma component map to exactly one code component — not "resembles," maps?
Is there a single file an agent reads before writing code, and does it state rules as constraints ("is a bug") rather than preferences ("we prefer")?
Is there a component index an agent can search before it decides to write something new?
Does the system have an owner — someone who approves a new token or component before it enters the system?
Have you actually tested it: has an agent tried to build a known screen from the system alone, with no human filling in gaps?
If more than one or two of these come back "no," that's not a documentation problem you can write your way out of with a longer CLAUDE.md. It's a signal the underlying system — the tokens, the parity, the mapping — needs work before the file describing it can be honest.
That's what a proper AI-readiness audit is built to find: a scored read across the dimensions above, backed by the same consumability test described here, so you know exactly where the guessing starts before an agent finds out for you. It's the natural next step whether the checklist above came back clean or came back rough.