Borrowing a DESIGN.md from the catalog is the fastest path. But sometimes your product has its own identity, your own colors, your own font choices. You want to write the file yourself.

This is the 20-minute version. By the end, you will have a DESIGN.md your AI coding tools can use immediately.

Step 1: Start with the template

Copy this. Replace the placeholder values. Do not overthink it. You can always come back and refine.

---
version: alpha
name: Your Product Name
description: "A [adjective] [adjective] design system for [what your product does]. [One sentence on the aesthetic intent.]"

colors:
  primary: "#REPLACE_WITH_YOUR_PRIMARY"
  on-primary: "#FFFFFF"
  primary-hover: "#REPLACE_SLIGHTLY_DARKER"
  background: "#REPLACE_PAGE_BACKGROUND"
  surface: "#REPLACE_CARD_BACKGROUND"
  surface-2: "#REPLACE_SECONDARY_SURFACE"
  text: "#REPLACE_BODY_TEXT"
  text-muted: "#REPLACE_SECONDARY_TEXT"
  border: "#REPLACE_BORDER_COLOR"
  accent: "#REPLACE_SAME_AS_PRIMARY"
  success: "#16A34A"
  danger: "#DC2626"
  warning: "#D97706"

typography:
  display:
    fontFamily: "'Inter', system-ui, sans-serif"
    fontSize: "48px"
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: "-0.03em"
  heading:
    fontFamily: "'Inter', system-ui, sans-serif"
    fontSize: "24px"
    fontWeight: 600
    lineHeight: 1.3
    letterSpacing: "-0.02em"
  body:
    fontFamily: "'Inter', system-ui, sans-serif"
    fontSize: "15px"
    fontWeight: 400
    lineHeight: 1.6
    letterSpacing: "0em"
  code:
    fontFamily: "'JetBrains Mono', 'Fira Code', monospace"
    fontSize: "13px"
    fontWeight: 400
    lineHeight: 1.5

spacing:
  base: "4px"
  scale: [4, 8, 12, 16, 24, 32, 48, 64, 96]

radius:
  sm: "4px"
  md: "8px"
  lg: "12px"
  xl: "16px"
  pill: "9999px"

shadows:
  card: "0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.08)"
  elevated: "0 4px 12px rgba(0,0,0,0.15)"
  modal: "0 20px 60px rgba(0,0,0,0.3)"

motion:
  duration-fast: "120ms"
  duration-base: "200ms"
  easing: "cubic-bezier(0.16, 1, 0.3, 1)"
---

## Design Philosophy
[2-3 sentences on the design intent. What feeling should users have? What should they trust?]

## Color Usage
- Primary is used for CTAs, active states, and key interactive elements only
- Background is the page canvas
- Surface is for cards and elevated containers
- Text-muted is for secondary information, timestamps, metadata

## Component Guidelines

### Buttons
- Primary CTA: primary background, on-primary text, md radius
- Secondary: transparent background, border color, text color
- Hover states: primary-hover background for primary, slight opacity change for secondary

### Cards
- Surface background with card shadow
- lg border radius
- 16-24px padding
- Border using border color

### Typography Hierarchy
- Page titles: display size
- Section headers: heading size
- Body content: body size
- Captions and metadata: 13px, text-muted color

Step 2: Pick your primary color first

Everything else in your palette follows from the primary. Here is the mental model:

What does your product do?

Technical, data-heavy products: cool colors (blue, indigo, purple). Consumer, warm products: warm colors (orange, amber, rose).

Who is your user?

Developers and technical users trust blues and purples. Consumers respond to warmer, more saturated colors.

What is the trust level required?

High trust (fintech, security, health): stay in the cool, desaturated range. Lower stakes: you can go more expressive.

Once you have your primary, use it to derive the hover state (5-10% darker) and the on-primary color (white if it is dark enough, dark text if it is not).

Step 3: Build your background stack

You need three levels of background:

+Background: the page canvas. Dark mode: #0A0A0A to #111827. Light mode: #FFFFFF to #FAFAFA.
+Surface: for cards, panels, and elevated content. One step above background.
+Surface-2: for nested elements, dropdowns, tooltips. One step above surface.

The progression is: background to surface to surface-2 should feel like depth, not just different shades of the same color.

Step 4: Typography is two decisions

Pick one font (maybe two). Define the scale. That is 90% of the job.

For the font: Inter is the safe default. Geist is the modern developer choice. Anything from the Google Fonts catalog with variable weight support will work. Avoid anything that has strong personality unless your brand explicitly calls for it.

For the scale, you need four sizes at minimum:

+Display (48px+): page titles, hero text, only used once or twice per page
+Heading (24px): section titles, card headings
+Body (15-16px): paragraph text, form labels, most UI copy
+Small (12-13px): metadata, timestamps, captions, helper text

Step 5: Add component guidance in plain text

The YAML frontmatter handles the tokens. The markdown after the frontmatter is where you give the AI behavioral guidance: how components should feel, when to use what, what to avoid.

Write it like you are briefing a junior designer. Short sentences. Specific rules. No ambiguity.

## Buttons

Primary buttons: filled, primary background, white text.

Only one primary button per screen.

Secondary buttons: transparent, border only, text color.

Destructive actions: danger color, never primary color.

Icons in buttons: 16px, left side only, 8px gap.

That kind of guidance, for your 5-6 most common components, gives the AI everything it needs to make consistent decisions.

The 20-minute version, honestly

Fill out the template above. Spend 5 minutes on colors, 5 minutes on typography, 5 minutes on component guidelines, 5 minutes reviewing. Ship it.

A good enough DESIGN.md you use is worth infinitely more than a perfect one you are still writing. The AI will help you refine it. Give it the file, ask it to build something, look at the output, and update the file based on what looks wrong.

The design system improves as you use it.

Or borrow one that already works

If you want a head start, browse 110 DESIGN.md files from products with proven design systems and customize from there.

Browse the catalog