My trial and error making a design system legible for agents

Vibe coding changed how teams build. Designers, PMs, and engineers describe what they want in plain language and get working UI back. That speed comes with a cost. When everyone is building, the design system is the only thing keeping the product from looking like five different apps.

I use Claude Code and Cursor daily. I pushed my team to do the same.

The first thing I tried: pointing Claude at Figma

As soon as the Claude Code and Figma MCP integration shipped (and even before, with a custom MCP built by the designer community), I was providing the agent with a Figma DSYS file and prompting it to reference it when building prototypes.

It worked, mostly. But every task started with the agent pulling the entire Figma file, reading through it, and then proceeding. That overhead added up. Token costs climbed. Sessions got slower. For a small correction like fixing one color, it felt absurd to burn that much context just to confirm one rule. I ended up going from free, to pro, and ultimately to max. (I need something in between pro and max, but what can I do.)

When errors crept in: re-prompting

On top of the token cost, something else kept going wrong.

I noticed our green slate color showing up on an alert message. Green slate was designated for AI-generated responses only. I had been clear about this. So I went back in and corrected it. Next session, same mistake. I corrected it again. Same mistake again.

I explained the rule in the prompt. I added more context. The agent got it right for that session, then forgot it in the next one.

This is not a prompting problem. Every new session starts with zero memory of previous decisions. The agent doesn't know it used green slate incorrectly last week. It doesn't know which colors belong where. It makes reasonable guesses, and 200 reasonable guesses across a session don't add up to a consistent system.

What actually explained the problem

Hardik Pandya's article Expose your design system to LLMs named what was happening. Agents fabricate values, drift within sessions, and lose all context between sessions. The problem wasn't my prompts or my Figma file. It was that my design system existed in a format optimized for humans, not for agents. Agents need structured, local, readable files they can check at the start of every session without burning through your context window.

That reframe changed how I approached the fix.

What I built

I tested this properly on Lune, a wedding planning app I co-founded. I was the only designer on it, which made it the right place to try: a technical co-founder building alongside me, a real design system, and no tolerance for a prototype that looks like it was built by three different people.

The design system now lives in a /DSYS folder at the project root:

DSYS/
  DESIGN-SYSTEM.md        ← master reference, always read first
  tokens.md               ← flat token quick-reference
  foundations/            ← color, typography, spacing, motion
  components/             ← one .md per component
  patterns/               ← layout and interaction rules

Every design value in the codebase has a named token. Nothing is hard-coded. In Lune, tokens map directly to Tailwind utility classes, so the lookup is fast:

ivory    →  bg-ivory / text-ivory     (#faf6f0)
gold     →  text-gold / bg-gold       (#b8944e)
espresso →  text-espresso / bg-espresso  (#1e1510)

DSYS/tokens.md is a flat file with every token, its hex value, and its utility class in one place. When the agent needs to know what color primary text is, it reads one file and gets one authoritative answer. Not a Figma panel. Not a Storybook story. A plain markdown file.

Each component gets its own spec file in DSYS/components/. Every spec follows the same eight-section format: metadata, overview, anatomy, props, variants, states, usage rules, and code examples. The anatomy section uses ASCII diagrams to show hierarchy and nesting without requiring the agent to parse actual code. The usage rules section lists what not to do. That part matters as much as the positive examples, because it trains the agent away from the most common mistakes before they happen.

Then there is CLAUDE.md, the file Claude Code reads at the start of every session. It sets the rules once:

• Read DSYS/DESIGN-SYSTEM.md and the relevant component spec before any UI work
• Run the design audit script before every commit
• When building a new component, also create DSYS/components/<name>.md
• When modifying a component, update the spec and sync Figma

The agent doesn't need to be reminded of these rules in every prompt. They are part of the project.

The last piece is the commit gate. scripts/design-audit.js scans every .tsx, .ts, and .css file for hardcoded values that should be tokens. If it finds a raw hex color or a pixel value that belongs to the token system, it flags the file, the line number, and the correct class to use instead. The audit runs automatically on every git commit via a pre-commit hook. The commit is blocked until the audit passes. When a collaborator clones the repo and runs npm install, the hook installs automatically. No manual setup, no way to skip it by accident.

Figma still has a role, but a different one. The MD files are the implementation contract: what shipped and what the audit enforces. Figma is the exploration layer, where new screens get designed and stakeholders review. When a component gets a new state or variant, the rule is to update both in the same pass. Claude is instructed to remind you to do this at the end of every component change.

What changed

Green slate now has a rule written in a file: use only for AI-generated response containers. The agent reads the file. The audit catches violations. It doesn't rely on my memory or my prompts.

A contributor with no design background can now build a new screen in Lune. They get code a designer would recognize, not because they studied the design system, but because the system was structured to be readable by the tool doing the work.

The bigger shift is that consistency is no longer something I enforce through reviews or repeated prompts. It's something the system enforces. That's what a design system is supposed to do. It just took me a while to realize agents need it in a completely different format than the one I built it in.

Resources

Expose your design system to LLMs by Hardik Pandya. The article that reframed how I thought about this problem.