DESIGN.md template

A starter DESIGN.md that follows Google’s DESIGN.md spec: design tokens in YAML frontmatter at the top, all eight written sections below in the spec’s order. Swap in your own colors and fonts, then preview it to check it looks right.

Download DESIGN.md Preview this template

The template

DESIGN.md

---
version: alpha
name: Your Brand
description: One line on how the product should feel.
colors:
  primary: "#2F6FEB"
  on-primary: "#FFFFFF"
  surface: "#FAFAFA"
  surface-container: "#FFFFFF"
  on-surface: "#18181B"
  on-surface-variant: "#71717A"
  outline: "#E4E4E7"
  error: "#B42318"
  on-error: "#FFFFFF"
  success: "#1F7A45"
  on-success: "#FFFFFF"
typography:
  h1:
    fontFamily: Inter
    fontSize: 2.5rem
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: -0.02em
  h2:
    fontFamily: Inter
    fontSize: 1.5rem
    fontWeight: 600
    lineHeight: 1.25
  body-md:
    fontFamily: Inter
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.6
  label:
    fontFamily: Inter
    fontSize: 0.75rem
    fontWeight: 600
    letterSpacing: 0.06em
  mono:
    fontFamily: JetBrains Mono
    fontSize: 0.875rem
    fontWeight: 400
rounded:
  sm: 6px
  md: 12px
  full: 9999px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 32px
  xl: 64px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.on-surface}"
    textColor: "{colors.on-primary}"
  button-secondary:
    backgroundColor: "{colors.surface-container}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.sm}"
    padding: 12px
  card:
    backgroundColor: "{colors.surface-container}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.md}"
    padding: 24px
  input:
    backgroundColor: "{colors.surface-container}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.sm}"
    padding: 12px
  caption:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.on-surface-variant}"
  badge-success:
    backgroundColor: "{colors.success}"
    textColor: "{colors.on-success}"
    rounded: "{rounded.full}"
  badge-error:
    backgroundColor: "{colors.error}"
    textColor: "{colors.on-error}"
    rounded: "{rounded.full}"
---

## Overview

Two or three sentences on the personality of the product: who uses it, where, and what it should feel like. An agent reads this first, so lead with what matters most.

## Colors

| Token | Hex | Role |
|-------|-----|------|
| primary | #2F6FEB | The one thing to click: primary buttons, links, focus |
| on-primary | #FFFFFF | Text and icons on primary |
| surface | #FAFAFA | Page background |
| surface-container | #FFFFFF | Cards, inputs, panels |
| on-surface | #18181B | Headlines and body text |
| on-surface-variant | #71717A | Supporting copy and labels |
| outline | #E4E4E7 | Borders and dividers |
| error | #B42318 | Errors and destructive actions |
| success | #1F7A45 | Confirmations |

Use primary sparingly: one primary action per screen.

## Typography

Inter for everything readable, JetBrains Mono for numbers and code. Headlines are tight and bold; body text is relaxed and never smaller than 16px.

## Layout

- **Max width:** 1200px for app screens, 720px for reading
- **Spacing:** use the spacing scale only (4, 8, 16, 32, 64)
- **Grid:** 12 columns on desktop, 4 on mobile, 16px gutters

## Elevation & Depth

Mostly flat. Separate surfaces with the outline color, not shadows. Use one soft shadow only for things that float: menus, dialogs, toasts.

## Shapes

Small radius (6px) for buttons and inputs, medium (12px) for cards, full for badges and avatars. Never mix rounded and square corners on the same screen.

## Components

- **Primary button:** primary fill, on-primary label, darkens to on-surface on hover
- **Secondary button:** surface-container fill, on-surface label, 1px outline
- **Card:** surface-container fill, 1px outline, 24px padding
- **Input:** surface-container fill, 1px outline, primary focus ring
- **Badges:** success or error fill, full radius, label type

## Do's and Don'ts

- Do keep one primary action per screen.
- Do write labels in sentence case.
- Don't use pure black (#000000) for text; use on-surface.
- Don't add gradients or glows unless this file says so.

What goes in each part

colors: Every color as hex, named by job. Google’s spec uses Material-style names: primary for the main action, on-primary for text on it, surface and on-surface for page and text, outline for borders, error for problems.
typography: One entry per text style (h1, h2, body, label) with font family, size, weight, line height and letter spacing.
rounded and spacing: Your corner radii and spacing steps. Small, fixed sets keep generated UI consistent.
components: Buttons, cards, inputs and badges, pointing back at your tokens with {colors.primary}-style references. Hover and pressed states are separate entries, like button-primary-hover.
Overview: Two or three sentences on personality and audience. Agents read this first.
Colors, Typography, Layout: The reasoning behind the tokens: what each color is for, when to use which type size, max widths and grid.
Elevation & Depth, Shapes: How surfaces separate (borders or shadows) and which corner radius goes where.
Do’s and Don’ts: Short rules that stop the most common mistakes, like a second accent color or pure black text.

Why it’s built this way

A primary color is defined, so agents don’t invent their own key colors.
Every color is used by a component or is a standard role, so nothing is left orphaned.
Every component’s text and background pass WCAG AA contrast (4.5:1 or better).
Sections run in the spec’s order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts.
Components only use spec properties: backgroundColor, textColor, typography, rounded, padding, size, height, width.

Where to put it

Save it as DESIGN.md in the root of your repo, next to README.md. Mention it from AGENTS.md or CLAUDE.md (or in your prompt) so your coding agent reads it before building UI.

What this template looks like

Style guide

Your Brand

One line on how the product should feel.

Color

primary

#2F6FEB

4.38:1 on bg

surface-container

#FFFFFF

1.04:1 on bg

surface

#FAFAFA

1.00:1 on bg

on-surface

#18181B

17.0:1 on bg

on-surface-variant

#71717A

4.63:1 on bg

outline

#E4E4E7

1.22:1 on bg

error

#B42318

6.30:1 on bg

success

#1F7A45

5.12:1 on bg