---
system: design-md
category: overview
topic: overview
content_type: guidance
status: latest
version_label: "Google Stitch (2025)"
retrieved: 2026-05-12
source_url: https://stitch.withgoogle.com/docs/design-md/overview
derived_from: []
tags: [design-md, overview, standards, ai-tooling]
---

# What is DESIGN.md?

**Source:** `stitch.withgoogle.com/docs/design-md/overview`

A design system document that AI agents read to generate consistent UI across a project.

Every project has a visual identity: colors, fonts, spacing, component styles. Traditionally, this lives in a Figma file, a brand PDF, or a designer's head. None of these are readable by an AI agent.

`DESIGN.md` changes that. It's a plain-text design system document that both humans and agents can read, edit, and enforce. Think of it as the design counterpart to `AGENTS.md`:

| File | Who reads it | What it defines |
|---|---|---|
| `README.md` | Humans | What the project is |
| `AGENTS.md` | Coding agents | How to build the project |
| `DESIGN.md` | Design agents | How the project should look and feel |

---

## What it gives you

When a design agent like Stitch reads a `DESIGN.md`, every screen it generates follows the same visual rules: your color palette, your typography, your component patterns. Without it, each screen stands alone. With it, they look like they belong together.

`DESIGN.md` is a **living artifact**, not a static config file. It evolves as the design evolves. The agent generates it, you refine it, and it's re-applied to screens as you iterate.

Under the hood, every `DESIGN.md` has two layers:
- **YAML front matter** — machine-readable design tokens (exact hex values, font properties, spacing scales)
- **Markdown body** — human-readable design rationale

Tokens give agents precise values. Prose tells them *why* those values exist.

---

## The philosophy

The DESIGN.md spec is a **foundation, not a prescription**. It provides a common ground that agents, tools, and teams can rely on — a shared vocabulary for colors, typography, layout, and components — while preserving the freedom to extend the format for domain-specific needs. Unknown sections and custom tokens are accepted, not rejected.

---

## How they're created

There are three paths to a `DESIGN.md`:

**Let the agent generate it.** Describe the vibe. The agent translates your aesthetic intent into tokens and guidelines.

```
PROMPT: A playful coffee shop ordering app with warm colors,
rounded corners, and a friendly feel
```

**Derive from branding.** Provide a URL or image. The agent extracts your palette, typography, and style patterns to build the `DESIGN.md` from what already exists.

**Write it by hand.** Advanced users can author a `DESIGN.md` directly. Every section is just markdown with optional YAML front matter for design tokens. No special syntax beyond standard markdown and YAML.

---

## Minimal example

```
---
name: DevFocus Dark

colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"

typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400

rounded:
  md: 8px
---

# Design System

## Overview

A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors

- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography

- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14–16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components

- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts

- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text
```