DESIGN.md and Taste Profile: keep AI UI on brand

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.

Teams searching design.md file, how to use DESIGN.md, and keep AI-generated UI on-brand mostly land on format tutorials. 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.

On 9 Sep 2026, Google Search Console showed 1 impression for "design.md file" (position 1), 1 impression for "how do i keep ai-generated ui on-brand" (position 4), and 12 impressions for "ai readable design system" (average position 6.25). Small numbers. Cited because they are real, not because they look like a market.

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. 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.

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.

vs Vercel's public design.md

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 at vercel.com/design.md is for the other case: reports, proposals, and one-off pages 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.

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.

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.

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.

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.

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.