DESIGN.md: what it is, how to use it, and how Vercel's differs

You can generate a dashboard in an afternoon now. Keeping it on-brand is the part that still fails. The output is close: plausible spacing, a familiar card, a button that looks like a button. Then you put it next to the product you already shipped and it is obviously not yours.

Most tutorials explain the DESIGN.md file format. Google and Stitch own that SERP, and they should. This page is the bridge. DESIGN.md is a contract. It is not a full AI-readable design system. Clearly's Taste Profile is the package that makes the contract hold.

The problem: AI UI that is close, but not yours

Coding agents are good at average. Your product is not average on purpose. That gap is the whole issue.

A Cursor session reads tailwind.config.js, a couple of components, and whatever you pasted into chat. It infers the rest. Cool gray instead of your sand neutrals. rounded-xl everywhere when the brand is 6px. A hero that says "Get started" on a product that never uses that phrase. Each miss is small. Together they read as a different company.

Stateless sessions make it worse. Last week's token rename is gone. The PDF in Notion is gone. The Figma comment that said "never use that blue for body text" is gone. The agent starts over and fills gaps with training-set defaults.

Pasting brand guidelines into chat is describing the brand for one session. Next session, someone paraphrases it differently, or skips it, and the UI drifts again.

A DESIGN.md is the first durable fix: a file the agent can load every time. If you do not have one yet, and the product already ships, reverse-specs is how you get there. That workflow is generate design specs from code. The second failure shows up right after you write it. One file still leaves gaps. Gaps are where agents invent.

What DESIGN.md is (briefly)

Google Labs open-sourced Stitch's DESIGN.md format so agents can follow a visual identity across tools. The spec is Apache 2.0 at github.com/google-labs-code/design.md. YAML front matter holds tokens. Markdown prose explains intent. Tokens say what exists. Prose says what to reach for.

That is the contract. We are not going to re-tutorial the section order, the CLI, or how to export from Stitch. Google already did that. Read their spec if you need the format.

What this file is good at: giving Claude Code, Cursor, Stitch, and anything else that reads a repo a persistent, structured read on brand and UI constraints.

What this file is not: tokens.css. A component spec. A voice doc. A skill. Governance. If you try to make it all of those, you get the twelve-page PDF problem in one markdown file. We already ran that experiment. It failed for the same reason the PDF failed. The model reads the top, then guesses.

vs Vercel's public design.md

Vercel's public design.md is a portable judgment layer plus a stylesheet and eval loop for on-brand pages built outside the repo. Use it for reports, proposals, and one-offs when the agent cannot read your codebase. An in-repo DESIGN.md with tokens, specs, and voice governs product and marketing UI your team generates in Cursor or Claude Code session after session.

Vercel wrote how their agents build on-brand pages with design.md. It is a good piece. Read it. Their in-repo product-design skill covers work inside their codebases. The public file is for the other case: artifacts that still have to look like Vercel when the agent cannot read the repo. They paired the file with a public stylesheet (so models stop inventing type and spacing) and an eval loop (so guidance earns its place against frozen scenarios).

We are not going to argue with that architecture. It is the right shape for out-of-repo artifacts.

The job on this page is different. SaaS teams generating marketing and product UI inside the repo, session after session, in Cursor and Claude Code. The Taste Profile lives next to the components it governs. Agents should import your Button, not restyle a div until it reminds them of one. Judgment still matters. It is encoded in specs and voice files the session can load, not only in a public prompt.

Same filename. Different job. Their public design.md is a portable judgment layer plus evals. Ours is an in-repo package that makes DESIGN.md enforceable. If you need both, that is normal: a public file for decks and one-offs, a Taste Profile for the product.

Where DESIGN.md sits in the Clearly stack

In an AI-ready design system, DESIGN.md sits at the root of the design-system folder as the editorial source of truth. It does not replace the folder.

Article 1 is the why. Styleguides drift. AI sessions make the drift loud, because every session is stateless and will re-derive your system from whatever it can see. We tried one oversized DESIGN.md (tokens, specs, voice, layout, all in sequence). It worked for trivial tasks. For real work, Claude would correctly reference a color near the top and miss a voice rule hundreds of lines down. Same failure as the PDF, just version-controlled.

Article 2 is the folder. Foundations, tokens, atoms, molecules, organisms. Each tier has a job. DESIGN.md names the brand and the token vocabulary. tokens.css is the runtime. Specs are contracts for components. Voice lives in its own file so it does not have to be rediscovered in a paragraph the model may not load.

This page will not walk the tree again. The point for this query is simpler: one file alone fails because agents invent in whatever you did not name. Unnamed spacing. Unspecced organism. Unwritten "don't." Each gap is a drift entry.

An AI-readable design system is the structure that removes those gaps. DESIGN.md is the front door, not the building.

Taste Profile: the package agents cannot invent around

Pasting guidelines describes the brand. A Taste Profile is the spec the AI reads so it cannot invent a new one.

On Clearly projects, that package is DESIGN.md plus tokens, component specs, voice, and optional SKILL.md, sitting inside the five-tier folder. Tokens stop the agent picking a nearby hex. Specs stop it rebuilding a Button from vibes when one already exists. Voice stops "Get started" on a brand that does not talk like that. The optional skill is how the methodology loads without stuffing CLAUDE.md until the model skims it.

That is Clearly's packaging language. It is already how we talk about the gap on the Claude Code design skills hub. It is not tasteprofile.io, which is a hosted product. Same two words. Different object. If you came here from a Taste Profile search, this page is about the in-repo bundle, not that app.

Article 5 is the spec half of the package. A spec is a contract, not a museum placard. If a fresh session cannot decide whether to use a component, configure it, avoid documented mistakes, and write copy in the right voice, the spec has not earned its place. We will not rewrite that article here. The Taste Profile is what you get when those contracts exist and the agent is pointed at them.

If AI UI still looks "close" and never yours, you do not need another prompt. You need the brand encoded so agents cannot invent around it.

How to load it (light)

How to use DESIGN.md in an AI-ready design system is mostly a pointer problem. The file does nothing if the agent never opens it, and it still fails if you dump the whole system into always-on context so the model skims.

Claude Code. Put the path in CLAUDE.md. Facts belong there: where the design system lives, which file is normative, what is off limits. Do not paste the token table into CLAUDE.md. Point at DESIGN.md and the folder.

Cursor. Same idea as a project rule: before generating UI, read DESIGN.md and the relevant spec. Do not invent tokens, radii, or component APIs that are not in those files.

## Design system
Before generating UI, read `src/design-system/DESIGN.md` and the matching
spec under `src/design-system/specs/`. Prefer existing components. Do not
invent tokens, radii, or copy voice that are not in those files.

Adjust the path to wherever the folder actually lives. The instruction is the load-bearing part: file and folder, not file alone.

For marketing site pages (resources, landing pages, blog), the same pointer pattern applies. The fuller workflow — pull request previews, protected main, who approves merges — is edit your website with AI agents.

When you need installable structure (audit, plan, confirm, scaffold in place, non-destructive), that is a skill, not a longer CLAUDE.md. The hub is Claude Code design skills for design systems. The packaging story is article 7. This page will not copy the install steps. Clone ClearlyDesign/design-skills if you want the open scaffold this afternoon.

DESIGN.md for your marketing site

The same file is not just for product UI. On a code-based marketing site (Next.js, Astro, static), DESIGN.md lets the team edit pages through Claude or Cursor without breaking the brand. You keep a sections library, tokens, and voice in the repo. Every change goes through a PR preview someone can approve before it ships.

That is how we run clearly.design: agents read the contract and the component specs, then patch MDX and React sections in place. No parallel Webflow layer. No "export the hero as PNG." The site stays one codebase.

If you want that workflow spelled out step by step, read edit your website with AI agents. If you are still on Webflow, Framer, or WordPress and the blocker is migration, the offer is Webflow, Framer, or WordPress to custom.

When the scaffold is enough vs when to partner

Stay on the open skill when one repo needs an AI-ready folder and you can encode brand yourself: flavor, adapter, tokens, the "don'ts" you already know. design-system-scaffold will not invent taste. It will not invent ownership. It will put a structure in place so the next session has something to read.

Partner when the actual gap is the package, the process, or the surface area.

Taste Profile. Someone still has to make the calls a designer makes without being asked, then write them so an agent cannot dodge them. That is encoding, not scaffolding.

Governance. Who can add a component. What happens when a squad ships a one-off. How DESIGN.md, tokens, and specs stay in sync after a rebrand. The folder will not invent that. The commercial path for that process is AI UI brand governance.

Multi-repo. One marketing site is a good skill run. Five products, three stacks, one company feel is a Taste Profile rollout. Adapters help. They do not hold the thread. When the two surfaces are the marketing site and the product, and the question is recognition rather than a new file format, that decision is marketing site and product UI consistency.

If that is the work, we are a design partner for SaaS, not a request queue. Prototype-first. Slack and Looms. Standard $4,995/mo and Advanced $7,495/mo, pause or cancel. Confirm live pricing on clearly.design before you buy. If the scoped job is an AI-ready design system for a team shipping with Cursor, Claude Code, or v0, that offer is $8-12K and 2-4 weeks.

Book a call if the file would only name the easy part, and the hard part is still sitting with a founder. Point agents at the contract either way. Just do not pretend the contract is the system.