The design.md Starter Pack: Fix Your AI's Ugly UI

Your AI coding agent keeps shipping the same generic UI. Purple gradients. Default Tailwind spacing. A landing page that looks like every other AI demo. You blame the model. The model isn't the problem.

The problem is that your agent has no idea what your product is supposed to look like. So it guesses. And the average of every website it ever saw is exactly the bland UI you keep deleting.

The fix is one file: a design.md. This is the full starter pack to create one, drop it in, and point your agent at it so it builds on-brand UI instead of guessing.

Why one markdown file fixes ugly AI UI

A design.md (also written DESIGN.md) is a single markdown file that holds your design system in plain text: your colors, type, spacing, components, and the rules for using them. Your coding agent reads it before it writes a line of UI, so the output matches your product instead of a random demo.

It's an open format from Google Labs, released under the Apache-2.0 license out of Google's Stitch design tool. The format does two things at once:

• Machine-readable design tokens in a YAML block at the top of the file (the exact colors, fonts, and sizes).
• Human-readable design rationale in markdown below it (the rules and the why).

That combination is what makes it work. The tokens give the agent precise values. The prose tells it when and how to use them.

Think of it as the design twin of CLAUDE.md or AGENTS.md. Those files give an agent engineering context that survives every session. design.md does the same for design context. It lives in your repo, follows your project, and any AI tool that reads it applies the same visual identity.

One note: the spec is still in alpha. The schema and tooling are moving. The core idea, a single file your agent reads, is stable and already worth using today.

What's actually inside a design.md

A good design.md is short and opinionated. Here's the anatomy:

• Colors — your palette as named tokens (primary, background, text, borders, states).
• Typography — font families, a size scale, weights, and line height.
• Spacing — a base unit and the gaps/radius built from it.
• Components — how a button, card, and input are styled.
• Layout — max width, breakpoints, and grid.
• Accessibility — contrast minimums, focus states, tap target sizes.
• Rules — the directives that tell the agent how to use all of the above.

Here is a complete starter template. Copy it, fill in your values, and you have a working design.md today.

markdownCopy
---
# DESIGN.md — design tokens (machine-readable, YAML front matter)
meta:
  name: "Your Product"
  version: "0.1"

colors:
  primary: "#1a3a52"
  secondary: "#3b6ea5"
  background: "#f7f3ec"
  surface: "#ffffff"
  text: "#11181c"
  muted: "#5c6b73"
  border: "#e3ddd1"
  success: "#1f9d55"
  warning: "#d97706"
  danger: "#c0392b"

typography:
  font_family_base: "Inter, system-ui, sans-serif"
  font_family_mono: "JetBrains Mono, monospace"
  scale:
    h1: "48px"
    h2: "32px"
    h3: "24px"
    body: "16px"
    small: "14px"
  weight_heading: 600
  weight_body: 400
  line_height_body: 1.6

spacing:
  unit: "4px"          # every gap and pad is a multiple of this
  page_gutter: "24px"
  section_gap: "64px"
  radius: "12px"
  radius_full: "9999px"

components:
  button:
    background: "primary"
    text: "#ffffff"
    radius: "radius"
    padding: "12px 20px"
  card:
    background: "surface"
    border: "1px solid border"
    radius: "radius"
    shadow: "0 1px 2px rgba(0,0,0,0.06)"
  input:
    background: "surface"
    border: "1px solid border"
    radius: "8px"

layout:
  max_width: "1200px"
  breakpoints:
    sm: "640px"
    md: "768px"
    lg: "1024px"
  grid: "12-column"

accessibility:
  min_contrast: "4.5:1"
  focus_visible: true
  min_tap_target: "44px"
---

# Design rationale (human + agent readable)

## Voice
Calm, confident, uncluttered. White space is a feature, not wasted room.

## Color rules
- `primary` is for primary actions and active states only. Never a large background.
- `background` is the default page color. `surface` sits on top for cards and panels.
- Body text is always `text` on `background` or `surface`. Never put text on `primary`.

## Typography rules
- One `h1` per page. Headings step down in order. Never skip a level for styling.
- Body copy stays at `body` size. Do not shrink readable text below `small`.

## Layout rules
- Center content inside `max_width`. Keep a consistent `page_gutter` on mobile.
- Every gap and padding is a multiple of `spacing.unit`. No arbitrary pixel values.

## Component rules
- Reuse `button`, `card`, and `input`. Do not invent a new variant without adding
  it here first.
- Every interactive element shows a visible focus ring.

You can read the full open format and its docs at the Google Labs spec repo and the spec home.

Rip a design.md straight off any live website

Don't want to write one from scratch? Like the look of a site you admire? You can extract a design.md from a live website and use it as your reference. These tools analyze a real page and hand you a file your agent reads natively.

• Masumi DESIGN.md Generator — Paste a URL. It extracts the brand colors, typography, layout, components, and logo, lets you edit them visually, and exports a clean DESIGN.md in the canonical 8-section format. Try it on Stripe, Linear, Vercel, or Notion.
• Context.dev Design.md Generator — Enter any domain and get a design.md back: the colors, fonts, components, and visual rules an agent needs to match that site's look. It parses CSS variables, Tailwind classes, Google Fonts, and hero selectors under the hood.

Use these to study how a site you respect is built, then adapt the tokens to your own brand. Don't clone a competitor outright. Use the structure as a reference and swap in your colors and type.

Generators, grouped by how you start

There are three ways to generate a design.md, depending on what you have in hand.

1. Domain-based (you have a URL). Point the tool at a live site and it returns the colors, fonts, and components. This is the Context.dev and Masumi path above. Fastest when a real site already shows the look you want.

2. Brief-based (you have an idea, not a site). Some generators take a plain-language product brief and turn it into a structured DESIGN.md. You describe the product and feel; it outputs YAML design tokens plus landmark guidance for layout, components, and accessibility checks. This is the best route for a brand-new product with no existing UI to scrape.

3. Balanced-system (you want spec-clean output). Other generators build a balanced design system that follows the open DESIGN.md spec directly, so the file is well-formed and consistent before you ever hand it to an agent. Reach for this when you care about the file being correct and complete, not just pulled from one page.

Pick by your starting point: a site to copy from, a brief in your head, or a clean spec-first build.

Free libraries to steal from

You don't always need to generate anything. There are open collections of ready-made design.md files you can grab and drop in.

• VoltAgent Awesome DESIGN.md Collection — A curated set of DESIGN.md files inspired by developer-focused websites, plus a built-in "What is DESIGN.md?" primer to get you oriented if you're brand new to the format. Good first stop.
• Design AI Systems library — A curated library of DESIGN.md files extracted from real public websites, built so AI agents can generate UI matching a known visual style. Browse it for a system close to your taste, then tweak the tokens.

Grab a file whose look is close to what you want, change the colors and fonts to yours, and you've skipped most of the setup.

How to write a design.md your agent actually follows

Here's the trap: most people write their design file like a polite style guide. The agent reads "we prefer rounded corners" as a suggestion and ignores it the moment something is easier. A design system write-up from designproject.io makes the key point well: rules have to read as directives, not preferences.

Three things make an agent obey:

1. Write rules as commands. Use ALWAYS and NEVER and MUST. No hedging.
2. Scope it tight. A short, sharp file beats a sprawling one. The agent has to hold it in context, so cut anything it doesn't need to make UI decisions.
3. Place it where the agent looks. Put it at the repo root and reference it from your agent instructions (more on that below).

Here's what enforceable rules look like. Add a block like this to the rationale section of your file:

markdownCopy
## Rules (directives, not suggestions)

- ALWAYS use tokens from the `colors` block. NEVER hardcode a hex value in a component.
- ALWAYS use the `button` component for actions. NEVER style a raw <button> inline.
- Spacing MUST be a multiple of 4px. Reject any value that isn't.
- Headings MUST follow document order (h1 → h2 → h3). Do not jump levels.
- Text contrast MUST meet 4.5:1. If a color pair fails, pick the next darker token.
- If a style you need isn't defined here, STOP and ask. Do not invent one.

Drop it in and point your agent at it

A design.md does nothing sitting in a folder. You have to make your agent read it first.

Step 1 — Put the file at your repo root. Name it DESIGN.md and place it alongside package.json, the same spot you'd keep CLAUDE.md or AGENTS.md. Agents look there by default.

Step 2 — Reference it from your agent instructions. If you use a CLAUDE.md or AGENTS.md, add a short pointer so the rule applies to every session:

markdownCopy
## Design
This project has a DESIGN.md at the root. Read it before generating or editing any
UI. All visual decisions — color, type, spacing, components — come from that file.
Never fall back to default framework styling when a token exists.

Step 3 — Tell the agent to read it before each UI task. Whether you're vibe coding a side project in a chat window or running an agent on a SaaS, lead the request with this:

textCopy
Before you write any UI, read DESIGN.md at the repo root and treat it as law.

- Use only the colors, fonts, spacing, and components defined there.
- Follow every rule in the "Rules" section as a hard requirement, not a suggestion.
- If something you need isn't in DESIGN.md, ask me. Do not invent a new style.

Now build: <describe the screen or component you want>.

That's the whole loop. File at root, pointer in your agent instructions, read-first prompt on the task. From here on, your generated UI looks like your product.

Pick the right tool fast

Tool	Type	Input	Output	Price
Masumi DESIGN.md Generator	Extract	Live URL	Editable DESIGN.md, downloadable	Free
Context.dev Design.md Generator	Extract / Generate	Domain	design.md (colors, fonts, components)	Free
Brief-based DESIGN.md Generator	Generate	Plain-language brief	DESIGN.md with YAML tokens + landmark guidance	Free
Balanced-system DESIGN.md Generator	Generate	Spec inputs	Spec-compliant DESIGN.md	Free
VoltAgent Awesome DESIGN.md Collection	Library	Browse	Ready-made files + primer	Free (open source)
Design AI Systems library	Library	Browse	DESIGN.md files from real sites	Free
Google Labs design.md spec	Reference	Read	The format itself	Free (Apache-2.0)

Quick rule of thumb: have a site you love, use an extractor. Have only an idea, use a brief-based generator. Want a head start, grab from a library.

FAQ

Do I need design.md if I already have a CLAUDE.md or AGENTS.md? Yes, they cover different things. CLAUDE.md and AGENTS.md carry engineering context: how to build, test, and structure the project. design.md carries visual context: how it should look. Keep both at the root and have your agent files point to the design file.

Is design.md only for one AI tool? No. It's an open format from Google Labs under the Apache-2.0 license, so any tool that supports it reads the same file. Google's Stitch is the reference consumer, but the value is that one file follows your repo and applies across whatever coding agent you use.

What if I'm not a designer and don't know my colors yet? Start by extracting one. Run a site you admire through a domain-based generator, or pull a ready-made file from a library, then change the colors and fonts to yours. You don't need to design from a blank page. You need a starting file your agent can read.

---

A design.md is the cheapest upgrade to your AI build quality: one file, written once, that turns "generic AI demo" into "looks like our product." Grab a generator, fill in the starter template, drop it at your root, and tell your agent to read it first.

For more practical AI build systems like this one, that's exactly what we share at Hypd.