Docs / Getting started

Your first file

A valid DESIGN.md has two parts: a YAML front matter block delimited by ---, followed by ## sections with prose guidance. Both parts are optional individually, but together they give AI agents the full picture.

Here is a minimal but complete example. Copy it, replace the values with your own, and drop it at your project root:

---
name: "Pebble Banking"
version: "1.0.0"
colors:
  primary: "#1A1C1E"
  accent:  "#B8422E"
  neutral: "#F7F5F2"
  surface: "#FFFFFF"
typography:
  h1:
    fontFamily: "Public Sans"
    fontSize: 3rem
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: -0.02em
  body:
    fontFamily: "Inter"
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.6
spacing:
  sm: 8px
  md: 16px
  lg: 32px
rounded:
  md: 8px
  lg: 16px
  full: 9999px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#FFFFFF"
    rounded: "{rounded.full}"
    padding: "12px 24px"
  card:
    backgroundColor: "{colors.surface}"
    rounded: "{rounded.lg}"
    padding: "{spacing.lg}"
---

## Overview
Pebble Banking is a mobile-first fintech product for everyday users aged 25–50.
Visual language: clean, trusted, approachable. Emotional response: secure,
calm, and competent.

## Colors
primary (#1A1C1E) is for the single highest-emphasis action per screen.
accent (#B8422E) is reserved for alerts and destructive states only.
neutral (#F7F5F2) is the default page background.

## Typography
Headlines use Public Sans at tight leading. Body copy uses Inter.
Never mix more than two type weights in a single card.

## Components
All buttons are pill-shaped (rounded-full). Cards use 16px radius and
32px internal padding on all sides.

## Do's and Don'ts
Do: use surface (#FFFFFF) for elevated card backgrounds on the neutral base.
Don't: use accent (#B8422E) for primary CTAs — it signals caution.
Don't: mix font families within a single component.

Tip: Start with only the sections you know confidently. A short, accurate DESIGN.md produces better AI output than a long, aspirational one. You can always expand it later.

Once you have the file, validate it:

npx @google/design.md lint DESIGN.md

Then move on to the Format spec to understand every field in detail, or jump straight to Integrations to start using it with your AI tool.

Installation Frontmatter