Claude Design vs DESIGN.md. Here’s the difference.

One is a tool and the other is foundational for your design org

Last week, two things shipped four days apart.

Anthropic launched Claude Design on April 17. Google open-sourced DESIGN.md on April 21.

Both touched design systems. Both promised to make AI agents respect your brand. Most coverage I read treated them as competitors.

They’re not.

• “Does this replace DESIGN.md?”

• “Why would I write DESIGN.md if Claude Design extracts my system automatically?”

These are good questions. I had the same ones when the launch landed.

The short answer: DESIGN.md is foundational. Claude Design is a tool that becomes more useful when you have a DESIGN.md to point it at. They’re not the same layer of your stack.

Here’s why.

What Claude Design actually does

Claude Design launched April 17. Research preview. Available on Pro, Max, Team, and Enterprise plans.

You describe what you need. It generates a prototype, a slide deck, a landing page, a one-pager. Live HTML. Clickable. Refineable through chat.

The part that made designers pay attention isn’t the generation.

It’s the onboarding.

During setup, Claude Design reads your codebase and your design files and extracts a design system automatically. Colors, typography, components, spacing. It builds a token library from whatever you give it. A Figma file. A GitHub repo. A brand PDF. Even a live website URL.

From that point, every new project inherits the system.

That’s a real shortcut. Genuinely useful, especially if your team has been pasting hex values into prompts for the last year.

What DESIGN.md actually does

DESIGN.md is a different thing entirely.

It’s not a design system itself. It’s not a token format like Style Dictionary or W3C Design Tokens. It’s not a style guide your team reads.

It’s a plain-text file in your repo. YAML at the top for tokens the agent can parse. Markdown below for the rules a human wrote. Every AI agent reads it before generating anything.

It’s a contract.

Version-controlled. Editable by your team. Cursor reads it. Claude Code reads it. Figma Make reads it. Any agent you adopt next year reads it.

Google Labs shipped the spec. We’ve been building an extended version using Nova, botim’s production system, as the worked example.

Why the question keeps coming up

Both are working on the same upstream problem.

Agents drift.

You prompt them today, they get close to your brand. You prompt them again tomorrow, they drift a little. By session four the corner radius is different. The button weight is off. The neutral is too cool.

Quietly, consistently off.

That drift is the context tax we’ve all been paying. Every prompt. Every session. Every project. Paying it again.

The fix is a system the agent reads every time before it generates. Both DESIGN.md and Claude Design are working on that. They just approach it from different angles.

Three things that are actually different

1. Where it lives, who reads it

Claude Design is a single product. The system you upload lives inside it. If you stop paying, change vendors, or Anthropic deprecates the feature, your work goes with it.

That said, it is still early. Anthropic ships fast, and Claude Design has only been out for a week. My prediction: this gets more interesting. I’d expect them to expose Claude Design through MCP soon, which would open up a real range of use cases. Reading your DESIGN.md from the repo. Generating output that respects it. Sitting alongside the rest of your stack instead of inside its own box. If that lands, the picture changes for the better.

For now, though, the system you build inside Claude Design is scoped to Claude Design.

DESIGN.md lives in your repo. It travels with your code. Cursor reads it. Claude Code reads it. Figma Make reads it. The next agent you adopt next year reads it. It is to design what tsconfig.json is to engineering. A small open file in your repo that every tool in your workflow already knows how to consume.

One is product-level memory. The other is a portable contract.

This is the foundational layer. You write it once and every tool, current and future, benefits from it.

2. The principles layer

This is where the split is clearest.

Claude Design extracts what your system is. Colors. Typography. Components. The structural facts.

DESIGN.md carries why it is the way it is.

“Primary is rationed. Used once per screen for the most important action.” “Motion is reassurance, not entertainment. Never animate error states.” “When in doubt, remove an option. Decision paralysis is the silent UX killer.”

These aren’t tokens. They’re the principles and constraints behind the tokens.

An agent that knows your hex codes will still sometimes put two primary buttons on the same screen. An agent that also knows your principles is more likely to catch itself.

The principles are the part you write yourself, and they’re the part that makes a system feel yours.

3. Extraction is fast. Writing is deliberate.

Claude Design infers your system from what it reads. For clean codebases and well-structured Figma files, the inference is good. For messier source code, nested tokens, brand-specific shadows, multi-brand setups, the model is making educated guesses.

Anthropic’s own documentation is honest about this.

“The design system import works best with a clean codebase. Messy source code produces messy output.”

DESIGN.md is written by a human who knows the system. You write the corner radius value, and the sentence that explains when to break it.

Different inputs. Different outputs. Both useful at different stages.

“But Claude Design has a Claude Code handoff. Doesn’t that solve it?”

Claude Design has an export called “Send to Claude Code.” It packages up the design tokens, the component structure, the layout hierarchy, the assets, and a PROMPT.md for Claude Code to read. Claude Code receives the bundle, loads it into context, and builds the feature. It’s a real workflow. It works today.

But it isn’t the same thing as a portable contract.

Two reasons.

One. The handoff is a snapshot, not a live link.

When you export from Claude Design to Claude Code, you’re shipping the system as it exists right now. If the design system updates inside Claude Design tomorrow, the bundle you handed off yesterday doesn’t update with it. You re-export. You re-hand-off. Per project. Every time.

A DESIGN.md in your repo is a single source of truth. Update the file once. Every agent reading it from the repo gets the new version on its next prompt. No re-export. No re-handoff.

Two. The handoff goes to Claude Code. That’s it.

Cursor doesn’t receive the bundle. Figma Make doesn’t receive the bundle. The next agent your team adopts in a year doesn’t receive the bundle. The handoff is built specifically for the Claude Design → Claude Code loop, which is exactly the loop Anthropic is investing in. That’s a fine bet for them. Less fine if your team uses more than just Anthropic products.

DESIGN.md sits in your repo. Every agent already knows how to read a markdown file in a project root. No bundle. No vendor-specific format.

This is the same reason I think the MCP prediction matters. Once Claude Design exposes itself through MCP, the handoff stops being the only way out. The system can be read from the repo, by Claude Design and by anything else. That changes the loop for the better. But it isn’t there yet.

For now, the handoff is one bridge. DESIGN.md is the road.

Where it all fits

A quick mental model before we go to setup, since this is the part that confuses most readers right now.

A while back I wrote about the two modes of design: divergent (explore fast, generate options, find direction) and convergent (refine, build, ship). AI tools belong in one mode or the other.

Here’s where the new layer of products fits:

The thing to notice: DESIGN.md sits underneath everything else.

Claude Skills are a useful adjacent layer worth a quick word. A Skill is a markdown file in .claude/skills/ that an agent loads when the task matches. Your DESIGN.md can be a Skill the agent picks up automatically when it’s working on UI. Or you can author additional Skills that point at it. Either way, the system is still in your repo. Skills are the loading mechanism, DESIGN.md is the load.

Divergent tools generate ideas. Convergent tools ship them. Capability layers tell the agent how to behave. The foundation is what every layer reads to stay on-brand.

Set the foundation first. Everything else stops drifting.

So where do you start?

Start with DESIGN.md.

It’s the foundation. It’s open. It’s free. It works with every engineer’s preferred IDE. It is editable by your team in the same way every other config file in your repo is editable. It will outlast any single AI product, including the one Anthropic shipped last week.

Drafting it forces you to do work no extraction can do for you. You have to articulate why your system is the way it is. You have to write down the principles, the heuristics, the dark mode handling, the RTL rules, the motion constraints. Those are the parts an agent can’t infer from a Figma file. They are also the parts that make a system feel like yours and not like every other AI-generated UI.

Once you have a DESIGN.md, Claude Design becomes more useful, not less. You can point it at the file as part of your project context. The output gets tighter. The drift goes down.

The reverse is not as true. A Claude Design extraction without a DESIGN.md still leaves you without a portable contract for the rest of your stack.

DESIGN.md is the foundation. Claude Design is one of many tools that become better on top of it.

If you want a head start on extraction, Claude Design can produce a useful first-draft token list from a Figma file or repo. Treat the output as raw material. Move it into a DESIGN.md. Add the prose that makes it yours.

One thing worth flagging

If your codebase is proprietary and you point Claude Design at it, you are sending that code to Anthropic.

Figma files are different. Parsed locally in your browser. Never uploaded.

But codebase ingestion goes server-side.

If you’re on an Enterprise plan, it’s worth checking that your contract covers this before pointing Claude at a production repo. Quick conversation with your team. Easy to do, easy to skip.

How to set up DESIGN.md for your design org

Next week’s playbook walks through the full setup. The version that’s working in production at botim, on Nova, today.

Here’s what’s covered:

• The 9+5 framework. Nine canonical sections every DESIGN.md should have, plus five production extensions (iconography, motion, RTL, voice, heuristics) that the official spec doesn’t cover yet

• The principles layer. The part the spec doesn’t have. The part that makes a system feel like yours

• The 10 heuristics every production system needs. Hick’s Law. Decision paralysis. WCAG minimums. Each cited, each enforceable, each written for the agent to follow

• The dark mode build workflow. One source-of-truth file, two Stitch-compliant outputs, a small build script that prevents drift

• The starter template you can fork in five minutes. Same structure, your tokens, your principles

• The wiring across Cursor, Claude Code, and Figma Make. Same prompt, three setups, side-by-side outputs

Built on a public GitHub repo you can clone, fork, or pull from directly. Apache 2.0, like the upstream spec.

Take what helps. Adapt it to your team. Skip what doesn’t fit. The whole point is to give you a foundation you can start writing this week, not a rulebook you have to follow.

If you’ve been hand-rolling your own context files for Cursor or Claude Code, this is the one to subscribe for.