Learn more

The DESIGN.md specification

DESIGN.md is a plain-text design system document that both humans and agents can read, edit, and enforce. Google Stitch introduced this convention: treat it as the design counterpart to AGENTS.md. README.md explains what the project is. AGENTS.md tells coding agents how to build it. DESIGN.md tells design agents how it should look and feel.

When a design agent such as Google Stitch reads your DESIGN.md, generated screens can follow one shared palette, typography scale, and component language instead of drifting apart. The file is meant to be a living artifact you refine over time. Under the hood it pairs YAML design tokens with markdown rationale so agents get both exact values and the intent behind them.

Two layers

Every DESIGN.md file has two layers. The YAML front matter contains machine-readable design tokens such as exact hex values, font properties, spacing scales, and component token references. The markdown body provides the human-readable design rationale.

Tokens give agents precise values. Prose tells them why those values exist and how to apply them consistently across screens.

---
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

Section order

Sections can be omitted if they are not relevant, but when present they should follow the canonical sequence below.

Overview. Also known as Brand & Style.
Colors.
Typography.
Layout. Also known as Layout & Spacing.
Elevation & Depth. Also known as Elevation.
Shapes.
Components.
Do's and Don'ts.

Canonical sections in practice

A compact markdown body showing each canonical section in order. Adjust the content to your product, keep the headings and sequence.

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

## Colors
- Primary (#2665fd): CTAs and active states
- Surface (#0b1326): Page backgrounds
- On-surface (#dae2fd): Text on dark backgrounds

## Typography
- Headlines: Inter, semibold
- Body: Inter, regular, 14-16px
- Labels: Inter, medium, 12px, uppercase

## Layout
- 8px base spacing unit, scale: 4 / 8 / 16 / 24 / 32 / 48
- Max content width 720px with 24px gutters on mobile

## Elevation & Depth
- Surfaces rely on background contrast instead of shadow
- Overlays use an 8 percent white tint on dark surfaces

## Shapes
- Rounded 8px for controls, 16px for cards
- Avoid mixing sharp and rounded corners in one view

## Components
- Buttons: 8px rounded, primary filled with brand blue
- Inputs: 1px border, subtle surface-variant background
- Cards: no elevation, rely on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, for the most important action
- Don't mix rounded and sharp corners in one view
- Do maintain at least a 4:1 contrast ratio for all text

Design tokens and schema

DESIGN.md embeds design tokens as YAML front matter at the beginning of the file. The front matter block begins with a line containing exactly --- and ends with the same delimiter.

version: <string>
name: <string>
description: <string>
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

Common scale names include xs, sm, md, lg, xl, and full, but any descriptive key is valid. Spacing tokens live in the YAML under spacing:and are described in the markdown body's Layout section.

Token types

Color: Hex color in sRGB format. Example: "#1A1C1E".
Dimension: Number plus unit, such as px, em, or rem. Examples:48px,-0.02em.
Token Reference: Wrapped in curly braces and pointing to a value in the YAML tree. Example:{colors.primary}.
Typography: A composite object containing font properties such as family, size, weight, line height, and letter spacing. See Typography properties.

Typography properties

fontFamily: The font family name.
fontSize: The font size as a dimension.
fontWeight: Numeric weight such as 400 or 700.
lineHeight: A dimension or a unitless multiplier. Unitless values are recommended.
letterSpacing: Letter spacing adjustment as a dimension.
fontFeature: Configures font-feature-settings.
fontVariation: Configures font-variation-settings.

Token references

A token reference is wrapped in curly braces and contains an object path to another value in the YAML tree. For most token groups, the reference should point to a primitive value instead of a group. Within the components section, references to composite values such as typography levels are allowed.

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

Components

The components section captures style guidance for component atoms such as buttons, chips, lists, inputs, checkboxes, radio buttons, and tooltips. Design systems can define additional components that matter to their product domain.

Variants for hover, active, or pressed states are defined as separate component entries with related key names, such as button-primary-hover.

backgroundColor: Color
textColor: Color
typography: Typography
rounded: Dimension
padding: Dimension
size: Dimension
height: Dimension
width: Dimension

Recommended token names

These names are guidance, not requirements. They provide useful defaults for consistency across systems.

Colors: primary, secondary, tertiary, neutral, surface, on-surface, error

Typography: headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm

Rounded: none, sm, md, lg, xl, full