Skip to content

DESIGN.md: The Missing File Between AI Agents and Consistent UI

7 min read
AI Design Systems Developer Tools Claude Code Agents

Tell any AI agent to “build me a landing page” and you already know what you’ll get. Rounded cards. A purple-blue gradient. A centered hero. A “Get Started” button. It works. It also looks like everything else on the internet.

The reason is simple. The agent’s idea of “good design” is an average of averages. It has no clue why Vercel uses borders instead of shadows, why Linear keeps its letter-spacing tight at -2.4px, or why Stripe goes easy on gradients. Even if it did know, cramming all of that into a prompt is borderline impossible.

So you end up with two bad options:

  1. Write 40 lines of prompt every time (“use #0070f3 for links, -0.02em letter-spacing on headings, 8px border-radius, no shadows, just 1px borders…”) and still get half of it wrong.
  2. Screenshot a site, paste it, say “make it look like this.” The agent copies pixels but misses the system behind them.

Neither scales. DESIGN.md is a different approach entirely.

What DESIGN.md Actually Is

DESIGN.md originated in Google Stitch, an AI-native design tool that generates UIs and design systems from natural language and examples. Google announced the format as a way to bridge Stitch’s design output with external coding agents. Inside Stitch projects, DESIGN.md is a plain Markdown file stored alongside your work that acts as a machine-readable design system manifest.

Think of it as the design equivalent of CLAUDE.md or AGENTS.md. Those files tell an agent how to build and run your project. DESIGN.md tells it how your project should look and feel. Same idea: structured text that lives in your repo, gets version-controlled, and doesn’t lock you into any canvas, plugin, or export pipeline.

Google and early adopters describe it as an “agent-friendly” format. The file is optimized so LLM-based coding agents can parse visual rules directly, without needing Figma exports or custom JSON schemas. It’s a portable bridge between design tools and AI code tools. You can export one from Stitch and feed it into Claude Code, Cursor, Gemini CLI, or anything else that reads text.

Why it exists: AI design tools are inconsistent because the model has to infer your brand and visual rules from vague prompts or scattered examples. DESIGN.md attacks this by putting all design decisions into one structured text file that every agent reads first. The model stops hallucinating random colors and styles because the constraints are explicit.

Google has now open-sourced the spec for the format, and community repos like awesome-design-md already collect dozens of files extracted from real-world sites.

What Lives Inside a DESIGN.md

A DESIGN.md has two layers: a structured token block (YAML front matter) and human-readable Markdown documentation below it. The open spec describes 9 standard sections. Each one maps to a layer the agent walks through when making a UI decision.

SectionWhat It AnswersExample Content
Visual theme & atmosphere”What should this feel like?""Opinionated calm. Muted palettes, tight spacing.”
Color palette & roles”Which color, and why?”#5E6AD2 = brand accent, used for interactive elements
Typography rules”Which font, which size?”Inter for UI, JetBrains Mono for code, -2.4px tracking on display
Component styles”What does this element look like?”Button: 6px 12px padding, 6px radius, brightness(1.15) on hover
Layout principles”Where does it go?“4px base unit, spacing scale of 4/8/12/16/24/32/48/64
Depth & elevation”Which layer?”Level 1: 0 1px 2px rgba(0,0,0,0.3), Level 2: 0 4px 12px rgba(0,0,0,0.4)
Do’s and don’ts”What should I avoid?”Don’t use rounded-full on rectangular buttons. Don’t mix warm and cool grays.
Responsive behavior”What changes on small screens?”Mobile < 640px single column, touch targets min 44x44px
Agent prompt guide”How do I start?”Quick palette summary + ready-to-use component prompts

The key insight: a token tells you what to use but not where. A rule tells you where but not when to bend it. The rationale is what lets an agent make the right call when it hits a situation the file never explicitly covers.

That’s why DESIGN.md keeps all three in the same file. It’s not just a token list. It’s closer to a document where an experienced designer explains a brand’s visual language to a developer who’s seeing it for the first time.

A Minimal Skeleton You Can Drop Into Any Repo

Here’s a trimmed version based on the open spec. Paste it into your project root and customize:

---
brandName: "Acme Analytics"
description: "Calm, minimal B2B dashboard with strong data legibility."
primaryColor: "#0F172A"
accentColor: "#3B82F6"
errorColor: "#EF4444"
borderRadiusScale: [0, 4, 8, 12, 9999]
spacingScale: [0, 4, 8, 12, 16, 24, 32, 40]
fontFamilies:
  sans: "Inter, system-ui, sans-serif"
  mono: "JetBrains Mono, ui-monospace, monospace"
typography:
  h1: { fontSize: 32, fontWeight: 600, lineHeight: 40 }
  body: { fontSize: 14, fontWeight: 400, lineHeight: 20 }
---

Below the front matter, the Markdown body explains the system:

# Overview
Calm, data-forward dashboard UI. No playful or saturated colors.

## Colors
- Use `primaryColor` for app chrome: header, sidebar, primary buttons.
- Neutral grays for surfaces with clear elevation differences.
- Never introduce new brand colors beyond this palette.

| Token          | Usage                              |
|----------------|------------------------------------|
| primary.bg     | App header, primary nav background |
| surface.base   | Page background                    |
| surface.raised | Cards, panels                      |
| border.subtle  | Hairline dividers, table borders   |
| state.error    | Error text and icons               |

## Typography
- `sans` family for all UI text.
- Headings: medium weight. Body: regular.
- Never mix more than three font sizes in a single view.

## Layout & Spacing
- Base unit: 4px. Only use values from `spacingScale`.
- 24px padding inside cards and panels.
- Page content max-width: 1200px, centered on large screens.

## Components

### PrimaryButton
- Height: 40px, horizontal padding: 16px
- Radius: 9999 (pill-shaped)
- Background: `primaryColor`
- Hover: lighten background. Focus: 2px ring with `accentColor`.
- Disabled: opacity 40%, no hover.
- Rule: one primary button per view. Label is a concise verb.

## Do's and Don'ts

Do:
- Keep layouts spacious with generous whitespace.
- Use color primarily for data and actions.

Don't:
- Add drop shadows to buttons.
- Introduce gradients or glassmorphism.

That’s roughly 50 lines and already enough for an agent to generate on-brand components without guessing.

Three Ways to Get a DESIGN.md Today

You don’t have to write one from scratch. There are three realistic paths.

1. Export from Google Stitch

Stitch lets you extract a design system from any URL or build your own UI and export a DESIGN.md from it. The file is portable. You can import it into other Stitch projects or copy it into your codebase and point your coding agents at it.

2. Copy an Existing Open-Source File

The awesome-design-md repo collects DESIGN.md files extracted from real-world sites: Stripe, Linear, Vercel, Notion, Supabase, and more. The workflow is literally “drop a DESIGN.md into your project root, tell your agent to match it.”

getdesign.md is the web version of that repo. Browse, preview, and copy any file without cloning anything. Most teams don’t write design systems from scratch. They say “make it look like Linear” or “give it that Stripe feel.” These files formalize those references.

3. Hand-Author Using the Open Spec

Google Labs has opened the format, so you can write your own without ever touching Stitch. The process looks like this:

  1. Inventory your current UI. Screenshot representative screens. Identify the real palette, typography, spacing scale, and components you actually use.
  2. Extract tokens into front matter. Normalize colors into a small set of named tokens. Define a limited spacing scale and typography styles.
  3. Document components as patterns. For each core component, define purpose, anatomy, states, and usage rules in Markdown prose.
  4. Add guardrails. Include Do/Don’t lists so the agent stays within your taste even when it interpolates.

This is likely the right path if you already have a product with an established visual identity. You’re not designing from scratch. You’re formalizing what already exists.

Wiring DESIGN.md Into Your Agent Workflow

The integration pattern is the same regardless of which tool you use:

1. Place DESIGN.md at your project root (alongside README.md, CLAUDE.md, etc.)
2. Tell the agent: "Before writing any UI, read DESIGN.md and strictly
   adhere to its tokens, components, and rules."
3. When you change your design system, update DESIGN.md first.

For Claude Code, you can reference DESIGN.md directly in your CLAUDE.md:

## Design System
Before writing any UI component, read DESIGN.md at the project root.
Use only the tokens, colors, and component patterns defined there.
Do not introduce new colors or spacing values.

For Cursor, add the same instruction to your .cursorrules file. For Gemini CLI or custom agent frameworks, inject DESIGN.md into the system prompt or retrieve it as a document before any UI-generation task.

The update flow matters too. When your design system evolves, DESIGN.md gets a PR just like any other code change. Every agent reads the latest version. No Figma sync plugins. No token export scripts. Just a Markdown file in version control.

What DESIGN.md Is Not

The name is easy to misread, so this matters.

It is not a finished theme. DESIGN.md is a dictionary, not an implementation. It describes what a button looks like. You or your agent still build the button. There is no code inside, just rules.

It is not a brand guideline PDF. Brand guidelines speak too loosely for agents to act on (“our brand feels approachable yet premium”). A DESIGN.md has to be specific enough for an agent to make its next decision. Hex values, not vibes.

It is not a Figma token export. Figma exports tell you “what” but skip “why.” A DESIGN.md carries the rationale. That rationale is what lets an agent handle edge cases the file never explicitly covers.

It is not static. When the brand evolves, the file evolves. It gets versioned, PR’d, discussed. It behaves like code.

The Mental Model

You used to hire a designer and say “you know Linear, right? Give me that feel.” It worked because the designer already carried the reference in their head. That shared context sat underneath every conversation you had with them.

An AI agent doesn’t have that shared context. DESIGN.md writes it into a file and puts it in the agent’s context window. The reference pool you built with a designer over months, you set up with an agent in two minutes.

We’ve been through this cycle before. README.md taught agents how to understand a project. AGENTS.md and CLAUDE.md taught them how to build it. DESIGN.md teaches them how to make it look right. Each file is a layer of context that used to live only in people’s heads.

The pattern is clear: text-native specifications are a natural fit for LLM-first workflows. Markdown isn’t the most expressive format. But it’s the one AI agents read best. And for design systems, “reads well” beats “looks pretty” every time.

Working with AI agents on UI? I’d love to hear how you handle design consistency across generated code. Reach out on LinkedIn.

Back to top