design.md is not just a file. It's a contract b/w PMs, UXDs & Devs

# design.md Is Not Just a File. It's a Contract.

And most designers are still treating it like a sticky note.

The Problem Nobody Is Naming Clearly

When MCP servers started becoming a real conversation in the design and engineering world, a lot of noise followed. Everyone had a take.

And somewhere inside all of that noise, a quiet file format started showing up.

design.md

I started noticing it first in developer repos. Then in Figma community discussions. Then someone in a design systems Slack I'm part of dropped it casually, like it was already standard practice. It wasn't. At least not in the way people were implying.

So I did what I do - I dug in. Read the articles. Watched the tutorials. Went past the surface. And here's what I found: most people are fundamentally misunderstanding what this file is for.

They're treating design.md like a fancier version of a style guide. Or a README for designers. Or a prompt template you hand off to an AI agent so it can generate UI.

It's none of those things. And it's all of them. But only if you understand why it exists in the first place.

---

A Bit of Context: Where This Actually Came From

The concept didn't emerge from a design team. It emerged from the intersection of two things happening simultaneously:

First: AI coding agents - Cursor, Copilot, Claude in your terminal - started being used seriously for product development. Not just for boilerplate. For real UI, real component logic, real product decisions.

Second: These agents had no design memory. Every session was cold. Every prompt was stateless. You'd spend twenty minutes explaining your design language to an agent, get something decent, close the session, and the next day you'd start from zero. The agent didn't know your tokens. Didn't know your spacing philosophy. Didn't know that you never use border-radius greater than 8px because your product is enterprise, not consumer.

The design.md file was, at its core, a solution to this problem. It gave the agent persistent design context. A source of truth it could read before it wrote a single line of code.

But here's what the tutorials missed: it's not just for agents.

---

What I Actually Discovered

When I started looking at how designers were actually creating these files - not how engineers were documenting them, but how designers were thinking about them - something clicked.

The best design.md files I came across weren't just token dumps or component inventories. They were written with intent. They had a voice. They explained not just the what but the why.

One file I studied had a section that just said:

"We don't use shadows to create depth. We use space. If a component needs a shadow to feel elevated, reconsider the layout."

That's not a token. That's not a component spec. That's a design philosophy - written in a way that a developer could read, an agent could parse, and a new designer joining the team could internalize in thirty seconds.

That's the real power. design.md is a shared language between humans and machines.

And that changes everything about how you should write one.

design.md ≠ Design System

This is the distinction I want to land clearly, because I keep seeing them conflated.

Your design system is the library. The design.md is the briefing document you hand someone before they walk into the room.

The design system says: here are all the buttons.

The design.md says: here's how we think about interaction, here's our token structure, here's what matters most.

One is exhaustive. The other is essential.

Both need to exist. But only one of them an AI agent - or a new contractor, or a developer working at 11pm without Figma access - can act on immediately.

The Figma Angle (This Is Where It Gets Interesting)

Here's the part that genuinely caught me off guard.

Some designers aren't just using design.md as a handoff document. They're using it to set the tone of their Figma file before they design anything.