DESIGN.md template and examples: four starter files to fork

A blank DESIGN.md is one of the worst writing prompts in software. You know the file is supposed to make your AI tools build on-brand UI. You know it has tokens at the top and prose below. The cursor blinks. The first decision you have to make is also the hardest one (what is this brand, in one sentence?), and there is no scaffolding to lean against.

Templates fix the blank-page problem. They also create a new one: a generic template applied to a specific brand produces a generic DESIGN.md, which produces generic UI. The whole point of the file is to be your taste, not a placeholder.

This post solves for both. The first half is a structural scaffold you can fork, with placeholders and a comment on what earns its place inside each section. The second half is four real client DESIGN.md files, summarised down to the load-bearing decisions, across the four brand archetypes we see most often:

1. Editorial Authority (Taste Profile itself, "Authoritative BUT warm")
2. Warm Capable (Rosie, "Capable BUT warm")
3. Professional Friendly (Churnkey, "Professional BUT friendly")
4. Clinical Human (Connect the Doc, "Clinical BUT human")

Pick the archetype closest to your brand. Fork the template. Fill in the prose with your own specifics, not the example's. The structural shape is shared. The taste isn't.

The starter template

Below is a minimal, spec-conformant DESIGN.md scaffold. It is opinionated about which sections to keep, which tokens to declare, and what the prose under each section should look like. Drop it in design-system/DESIGN.md (or wherever your tools expect it) and fill in the bracketed placeholders.

---
version: alpha
name: __BRAND_NAME__
description: "__TENSION_LINE__. __ONE_SENTENCE_AESTHETIC__."
 
colors:
  base-white: "#FFFFFF"
  base-black: "__DARKEST_BRAND_INK__"
 
  # Brand hue: full Tailwind-style scale lifted from your existing palette.
  brand-25: "#__"
  brand-50: "#__"
  brand-100: "#__"
  brand-200: "#__"
  brand-300: "#__"
  brand-400: "#__"
  brand-500: "#__"
  brand-600: "#__"  # canonical accent
  brand-700: "#__"  # canonical accent-hover
  brand-800: "#__"
  brand-900: "#__"
  brand-950: "#__"
 
  # Neutral: warm-tinted, cool, or true grey. Pick deliberately.
  gray-25: "#__"
  gray-50: "#__"
  gray-100: "#__"
  gray-200: "#__"
  gray-300: "#__"
  gray-400: "#__"
  gray-500: "#__"
  gray-600: "#__"
  gray-700: "#__"
  gray-800: "#__"
  gray-900: "#__"
  gray-950: "#__"
 
  # Danger: Tailwind Rose by default. Replace if your brand requires.
  rose-50: "#FFF1F2"
  rose-100: "#FFE4E6"
  rose-200: "#FECDD3"
  rose-300: "#FDA4AF"
  rose-400: "#FB7185"
  rose-500: "#F43F5E"
  rose-600: "#E11D48"
  rose-700: "#BE123C"
 
  # Semantic roles: the names UI code should reach for.
  background: "{colors.base-white}"
  background-subtle: "{colors.brand-25}"
  foreground: "{colors.base-black}"
  foreground-secondary: "{colors.gray-700}"
  foreground-muted: "{colors.gray-500}"
  border: "{colors.gray-200}"
  accent: "{colors.brand-600}"
  accent-hover: "{colors.brand-700}"
  accent-subtle: "{colors.brand-100}"
  danger: "{colors.rose-700}"
 
typography:
  display:
    family: "__DISPLAY_FAMILY__"
    weight: __DISPLAY_WEIGHT__
  body:
    family: "__BODY_FAMILY__"
    weight: 400
 
rounded:
  button: __BUTTON_RADIUS__
  card: __CARD_RADIUS__
  input: __INPUT_RADIUS__
 
components:
  button-primary:
    backgroundColor: "{colors.accent}"
    textColor: "{colors.base-white}"
    rounded: "{rounded.button}"
    padding: 14px 24px
  button-primary-hover:
    backgroundColor: "{colors.accent-hover}"
    textColor: "{colors.base-white}"
    rounded: "{rounded.button}"
    padding: 14px 24px
---
 
## Overview
 
**Tension:** *__ADJECTIVE_ONE__ BUT __ADJECTIVE_TWO__.*
 
[One paragraph. What is this brand fighting against? What is the aesthetic
in one breath? Name the contrast. Do not hedge.]
 
### Essence
 
[A short identity name, then the one-line "this is what we are." Should
fit on a Post-it.]
 
### Personality
 
[A person, not a vibe. Age, occupation, what they wear, how they speak
under pressure. The model can render specifics. It cannot render
"approachable yet authoritative."]
 
## Colors
 
[Three sentences on palette role. Which scale is the accent? Which is
the neutral? What is each one for? Then the semantic mapping table.]
 
## Typography
 
[Display family and weight. Body family. The one rule about weight that
keeps your headlines from defaulting to bold. The reason for it.]
 
## Shapes
 
[Three radii, three jobs. Buttons. Cards. Inputs. Whether you go pill,
soft, or sharp. The reasoning in one line.]
 
## Components
 
[Recipes, in token references. Primary button. Card. Input. Badge. Each
with hover as a separate variant.]
 
## Do's and Don'ts
 
### Always
1. [Specific rule with a why.]
2. [Specific rule with a why.]
3. [Specific rule with a why.]
 
### Never
1. [Specific failure mode with a why.]
2. [Specific failure mode with a why.]
3. [Specific failure mode with a why.]
4. [Specific failure mode with a why.]
5. [Specific failure mode with a why.]
 
## Voice & tone
 
[Active over passive. Contractions. Numbers over adjectives. An in-brand
vs off-brand table with four to six rows, taken from your real product
strings.]

Two notes on the scaffold before we hit the examples:

The front matter follows the Google Labs DESIGN.md open standard. Top-level colors, typography, rounded, and components keys. References like "{colors.brand-600}" compose, so a primitive change cascades. Hover states live as their own component keys (button-primary-hover), not as backgroundColorHover fields, because the spec's recognised sub-token set is small and the linter will flag anything outside it.

The prose sections are stubs, not text to copy. Every bracketed line is a writing prompt. If you fill it with hedged abstractions ("modern, clean, professional") the file lints clean and produces shadcn output. The whole job is to write the specifics underneath.

Archetype 1: Editorial Authority

"Authoritative BUT warm."

The reference brand for this archetype is the site you are reading. It is the right starting point if your audience is technical, your voice is opinionated, and your category is crowded with B2B SaaS dashboards. Linear and Vercel sit in this region too.

The load-bearing decisions:

• Accent: a single editorial blue (#2563EB). One accent. Reserved for interactive elements only. Never decorative.
• Neutrals: cool slate. neutral-900 (#0F172A) doubles as both the headline ink and the dark-section background. Two roles, one hex. The system collapses into two tonal worlds.
• Typography: Source Serif 4 at light weight (400 to 600, never 700+) for headlines. Inter for body. The headline weight is what carries the editorial signal. A 700-weight serif reads as a law firm. A 400-weight serif reads as a magazine.
• Shape: pill buttons (rounded-full) with a blue glow shadow. 16px cards. The combination of editorial serif headlines and pill buttons is the signature.
• Voice: "Specific over general, warm over cold, calm over loud. Says 'Here's what I'd do' instead of 'It depends.'"

The five nevers that do the most work:

1. No warm colours.
2. No italic headlines.
3. No blue as decoration.
4. No 700-weight serif for marketing copy.
5. No grey shadows on the primary button. (The blue glow is a signature element.)

When you fork this archetype, the trap to avoid is hedging on the accent rule. A confident brand has one accent. If you find yourself reaching for a second, you are reaching for warmth where authority should sit. Add a neutral instead.

Archetype 2: Warm Capable

"Capable BUT warm."

The reference brand here is Rosie, an AI answering service whose entire premise is that the customer should not notice it is AI. The voice on the phone should feel like the friendly person at your front desk. This archetype is right for consumer products, anything voice-first, and any AI product whose category has a coldness problem to solve.

The load-bearing decisions:

• Accent: a warm purple (purple-600 = #9332E0). The purple scale runs from purple-25 (#FBF7FF) to purple-950 (#3D0B60). Twelve stops. Every one named.
• Neutrals: warm purple-tinted greys, not Tailwind's slate-blue defaults. gray-600 becomes #94899F instead of #475467. The cumulative effect across a whole page is what sells the warmth.
• Typography: Outfit, used confidently across weights. Headlines are bold; body is light. One family, leaned on for personality through weight contrast.
• Shape: full pill on buttons (50px radius), 16px on cards, full pill on inputs. No rectangles with sharp corners anywhere. The pills do half the warmth work.
• Voice: active, conversational, no exclamation marks unless something is genuinely worth celebrating. "Answered in 2 rings" beats "lightning-fast pickup."

The five nevers:

1. No cold blues or greys as primary colours.
2. No robotic or clinical UI aesthetics.
3. No sharp corners on buttons or cards.
4. No dense, overwhelming layouts.
5. No corporate jargon over conversational tone.

The trap when forking this one is using a neutral grey from Tailwind. Tailwind's default greys lean slate-blue, which fights any warm accent at every step. If your accent is warm, your greys have to be tinted to match. Two values, linearly interpolated between their warm-tinted neighbours. The eye barely registers any single swatch and absolutely registers the page-wide effect.

Archetype 3: Professional Friendly

"Professional BUT friendly."

The reference brand here is Churnkey, a retention platform for SaaS. The category (money is leaving, customers are leaving) is serious and most tools in it lean cold and corporate. Churnkey does not. The signature yellow shows up generously. The greyscale is sand, not slate. Headlines are set in a humanist serif, not another geometric sans. The result feels capable without feeling sterile.

The load-bearing decisions:

• Accent: brand yellow (yellow-400 = #F7B200). Yellow is generous in display contexts (gradients, badges, accents) and disciplined in body contexts. Inline links use accent-deep (yellow-700) for legibility because yellow-400 text on white fails WCAG contrast.
• Neutrals: sand. Warm, not cool. gray-25 is #FFFBF8 instead of Tailwind's #FAFAFA. The page reads inviting even when no yellow is on screen.
• Typography: two families. Tiempos Headline (humanist serif) for display, General Sans for body. Both warm, both humanist. The contrast between the editorial serif and the quiet utility sans is the typographic story. Never use weight 700+ for General Sans; semibold is the ceiling.
• Shape: subtle 8px rounding everywhere. Buttons and inputs both. Cards lift to 16px to feel like surfaces. Never full pills; the rectangle is part of the brand's seriousness.
• Voice: sentence case everywhere except product names. Period at the end of every headline. No exclamation marks ever. "Recover more revenue. Automatically." beats "Recover More Revenue Automatically!"

The contrast caveat unique to this archetype: yellow on white is a contrast trap. Text on a yellow surface is always ink black, never white. Inline yellow links shift one full stop darker. Wire the rule into your tokens so the AI tool inherits it on every screen.

When forking this archetype, the trap is treating the yellow as a wash. The whole signature depends on sand carrying the weight and the yellow appearing as punctuation. Most surfaces are neutral. Yellow is a punctuation mark, not a background.

Archetype 4: Clinical Human

"Clinical BUT human."

The reference brand is Connect the Doc, an AI visibility platform for dental practices. The aesthetic is calm, confident, deeply blue. Headlines sit in deep navy on near-white surfaces. CTAs use a vibrant action blue with generous whitespace around them. The page never crowds the next decision. The through-line is signals: data, scores, and gauges visualised as cleanly as type. Right for fintech, healthcare-adjacent tools, anything that has to be trusted with a customer's money or compliance.

The load-bearing decisions:

• Accent: an action blue (blue-600 = #1570EF) with a gradient-lit primary button. The gradient top-stop is one shade lighter than the rest fill, so the button feels lit from above rather than flat.
• Neutrals: Gray modern (cool, clean). gray-950 (#0D121C) for headlines. gray-700 for body. gray-500 for captions. The greys do not fight the blue; they reinforce it.
• Typography: Inter, full stop. One family across display, body, and stat. Personality comes from weight and tracking, not from mixing families. Stat headlines (Display-stat) hit Inter 700 at 96px with -0.02em tracking and a sub-1 line-height for bento composition.
• Shape: four radii, four jobs. Soft 12px on buttons. 16px on cards. 28px on bento (the big composition blocks). Full pill (9999px) on badges only. The variety is deliberate; each radius has a single role.
• Voice: "References real numbers. Knows the difference between marketing that works for SaaS and marketing that works for a four-chair practice in a competitive metro. Confident, never loud."

The trap when forking this archetype is over-pilling. The pill is reserved for badges and chips. Buttons and inputs are soft rectangles. If you let buttons go full pill, the brand drifts toward the Warm Capable archetype and the precision signal blurs.

What to change first when you fork

When you copy one of these archetypes and start filling in your own brand, here is the order of operations that has the highest signal-to-effort ratio.

1. The tension line. Replace the example's two adjectives with your own. They must be in tension with each other. "Authoritative BUT warm" works because the model has to defend both sides. "Confident and approachable" averages. The tension is the file's load-bearing sentence; everything else explains how you resolve it.

2. The five nevers. Rewrite all five to reflect your specific failure modes. The nevers list is the highest-leverage section in the file because it removes whole regions of the model's output space in one line. Specific failure modes ("blob people and rainbow gradients") beat categories ("avoid generic illustrations") because the model has to imagine the bad version before it can avoid it.

3. The accent and its hover. One accent. Pick the hex. Pick the hover (usually one stop deeper). Wire the semantic names (accent, accent-hover, accent-subtle) to your scale. If you skip this step and leave the template's placeholders, every chat session will produce generic indigo until you fix it.

4. The voice table. Steal four to six strings from your real product. The microcopy table (in-brand vs off-brand) is what reshapes generated voice on its own, without any other instruction. Empty states. Error messages. CTA text. Real strings from your real product. The model reads them and inherits the difference.

5. The personality paragraph. A person, not a vibe. Specifics the model can render: occupation, age range, what they wear, how they speak under pressure. "A 35-year-old strategist with a strong point of view, communicated quietly" gives the model a fork to disambiguate against. "Approachable yet authoritative" gives it nothing.

The token shade scales can wait. They are the part that takes the longest to get right and the part where mistakes hurt the least; the model will still produce on-brand work if your primitives are mid and your prose is sharp. The reverse is not true.

The lint pass before you ship

Before you commit a forked DESIGN.md, run the official linter:

npx @google/design.md lint DESIGN.md

It catches the structural failures that don't look broken to humans but reduce the file's leverage on the model. Unrecognised sub-tokens (backgroundColorHover, border, chipTextColor). Missing top-level primary palette. WCAG contrast violations on stated component pairs. Orphan primitives that are defined but never referenced. Each finding has a path and a category. Three of the four files we audit on first review come back with double-digit warnings before we clean them up. None of them look broken to a human; all of them bleed the model's output through gaps in the spec.

Zero structural warnings is a one-line check. The prose is the part you have to read and rewrite.

When a template isn't enough

Two situations where a forked archetype will not get you all the way:

Your brand sits between two archetypes. Some brands are "Authoritative BUT playful" or "Clinical BUT generous." The four archetypes here are common shapes; they are not a complete typology. If your tension line does not match any of the four, fork the closest one and rewrite the personality, voice, and nevers from scratch. Keep the scaffold; replace the taste.

You are starting from no existing brand. Templates work best when you have an existing palette, an existing voice, and an existing aesthetic to translate. If your brand is new (no Figma, no past site, no founder taste already converging), forking a template will produce a working DESIGN.md that is also somebody else's taste. That is when a brand discovery workshop helps more than a fork. Two hours of structured questions, a tension line you defended yourself, and the template gets filled with your reasoning, not ours.

The template is a scaffold. The taste is the work. The four archetypes are starting points, not finish lines. The point of a DESIGN.md is to make every generation start from your taste, not the model's training mean, and the only way the file does that job is when the prose underneath the YAML is unmistakably you.

Related reading: Anatomy of a great DESIGN.md, DESIGN.md is now an open standard, and the Rosie case study, where one of these archetypes was built in detail.