DESIGN.md template

How to fill it in

1. Start with the overview. Two or three sentences on the mood and what makes the product recognizable. Agents use it to settle anything the rest of the file doesn't cover.
2. Replace every value. Use the exact hex codes, sizes and radii from your product. Delete any token you don't use rather than leaving the example in.
3. Explain the rules. "Blue only on the main action" helps an agent more than a list of twenty colors.
4. Keep the don'ts. Saying what not to do stops the generic choices agents fall back on, like extra gradients and shadows.
5. Save it as DESIGN.md at the root of your project, and point your agent at it. Here's how for each agent.

Rather start from a real design? Pick one of the 1,186 DESIGN.md files in the library and edit it, for example apple.com, about.instagram.com, bugatti.com, evilmartians.com, landonorris.com or artsandculture.google.com.

The template

---
# Optional design tokens. Guides that name values like {colors.primary} read them from here.
name: Your product
colors:
  canvas: "#FFFFFF"
  ink: "#0A0A0A"
  muted: "#6B7280"
  primary: "#2563EB"
  on-primary: "#FFFFFF"
  hairline: "#E5E7EB"
typography:
  family: "Inter, system-ui, sans-serif"
  display: { size: 56px, weight: 700, line-height: 1.05, tracking: -0.03em }
  body: { size: 16px, weight: 400, line-height: 1.5 }
rounded:
  sm: 6px
  md: 10px
  full: 9999px
spacing: [4, 8, 12, 16, 24, 32, 48, 64, 96]
---

# How Your product is designed

## Overview

Describe the overall feel in two or three sentences: who it is for, the mood, and what
makes it recognizable. Then list the key characteristics.

- Light canvas with near-black text. One blue accent, used only for primary actions.
- Large, tight display headlines; small, quiet body text.
- Flat surfaces separated by space, not borders or shadows.

## Colors

| Token | Value | Use |
|---|---|---|
| canvas | #FFFFFF | Page background |
| ink | #0A0A0A | Headings and body text |
| muted | #6B7280 | Secondary text, captions, placeholders |
| primary | #2563EB | Primary buttons, links, focus rings |
| on-primary | #FFFFFF | Text and icons on primary |
| hairline | #E5E7EB | Dividers and input borders |

Explain the rules, not just the values: where the accent may appear, how much of each
color to use, and which pairs must never be combined.

## Typography

- Family: Inter, falling back to system-ui. Name a licensed alternative for custom fonts.
- Display: 56px / 1.05, weight 700, tracking -0.03em. One per page.
- Heading: 24px / 1.25, weight 600.
- Body: 16px / 1.5, weight 400.
- Small: 13px / 1.4, weight 400, muted color.

## Layout

- Content width: 1200px max, 24px side padding on mobile.
- Spacing scale: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
- Section rhythm: 96px between sections on desktop, 64px on mobile.
- Grid: 12 columns on desktop, 4 on mobile.

## Elevation & depth

Say how layers are separated: shadows, borders, tints or blur. Give the exact shadow
values for each level, and say what never gets a shadow.

## Shapes

- Buttons and inputs: 10px radius. Pills: full radius.
- Cards: 16px radius. Images inside cards follow the card's radius.

## Components

### Buttons
Primary: primary fill, on-primary text, 40px tall, 16px horizontal padding.
Secondary: transparent with a hairline border. Hover, pressed and disabled states.

### Cards
Background, padding, radius, and what a card contains.

### Navigation
Header height, link style, active state, and the mobile menu.

### Forms
Input height, border, focus ring, label and error styles.

## Responsive behavior

Breakpoints, what stacks or hides on small screens, and how type scales down.

## Do's and don'ts

Do:
- Use primary for one main action per screen.
- Keep body text at 16px or larger.

Don't:
- Add gradients, glows or extra accent colors.
- Put text on photos without a scrim.

## Notes for coding agents

- Use the tokens above instead of new values. If a value is missing, pick the nearest one.
- Match the existing components before inventing new ones.
- When unsure, choose the quieter option.

What each section is for

• Frontmatter tokens (optional): the values in YAML, for tools and for guides that refer to them by name, like {colors.primary}.
• Overview: the character of the design, in words.
• Colors: every color with its value and its job.
• Typography: families, the type scale, weights and line heights.
• Layout: widths, spacing scale, grid and section rhythm.
• Elevation and shapes: shadows, borders and corner radii.
• Components: buttons, cards, navigation and forms, with their states.
• Responsive behavior: what changes on small screens.
• Do's and don'ts: the rules that keep the design from drifting.

New to the format? Read what a DESIGN.md is and how agents use it.