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

# The DESIGN.md Specification

**Source:** `stitch.withgoogle.com/docs/design-md/specification`
**Version:** alpha

---

## File structure

A DESIGN.md file has two layers:

- **YAML front matter** — machine-readable design tokens. The precise values agents use to enforce consistency.
- **Markdown body** — human-readable design rationale, organized into `##` sections. Prose may use descriptive color names (e.g., "Midnight Forest Green") that correspond to systematic token names (e.g., `primary`). Tokens are the normative values; prose provides context for how to apply them.

The spec is a **foundation, not a prescription**. Unknown sections and custom tokens are accepted, not rejected. Design systems are free to extend the format for domain-specific needs.

```
---
version: alpha
name: Daylight Prestige

colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"

typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em

rounded:
  sm: 4px
  md: 8px

spacing:
  sm: 8px
  md: 16px

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px
---

# Design System

## Overview

A calm, professional interface for a healthcare scheduling platform.

## Colors

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.

## Components

- **Buttons**: Rounded (8px), primary uses brand blue fill
```

---

## Design tokens (YAML front matter)

The YAML front matter must begin and end with a line containing exactly `---`. The token system is inspired by the [W3C Design Token Format](https://www.designtokens.org/). Tokens are easily converted to and from `tokens.json`, Figma variables, and Tailwind theme configs.

### Schema

```yaml
version: <string>          # optional, current version: "alpha"
name: <string>
description: <string>      # optional

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

`<scale-level>` is a named level in a sizing/spacing scale. Common names: `xs`, `sm`, `md`, `lg`, `xl`, `full`. Any descriptive string key is valid.

---

## Token types

| Type | Format | Example |
|---|---|---|
| **Color** | `#` + hex code (sRGB) | `"#1A1C1E"` |
| **Dimension** | number + unit (`px`, `em`, `rem`) | `48px`, `-0.02em` |
| **Token Reference** | `{path.to.token}` | `{colors.primary}` |
| **Typography** | composite object | See properties below |

### Typography properties

| Property | Type | Description |
|---|---|---|
| `fontFamily` | string | The font family name |
| `fontSize` | Dimension | The font size |
| `fontWeight` | number | Numeric weight (e.g., `400`, `700`) |
| `lineHeight` | Dimension \| number | A dimension (`24px`) or unitless multiplier (`1.6`). Unitless recommended |
| `letterSpacing` | Dimension | Letter spacing adjustment |
| `fontFeature` | string | Configures `font-feature-settings` |
| `fontVariation` | string | 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 must point to a primitive value (e.g., `{colors.primary-60}`), not a group. Within the `components` section, references to composite values (e.g., `{typography.label-md}`) are permitted.

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

---

## Sections (markdown body)

Sections can be omitted if not relevant. Those present should appear in the sequence listed below. All sections use `##` headings. An optional `#` heading may appear for document titling but is not parsed as a section.

### Section order

| # | Section | Aliases |
|---|---|---|
| 1 | Overview | Brand & Style |
| 2 | Colors | |
| 3 | Typography | |
| 4 | Layout | Layout & Spacing |
| 5 | Elevation & Depth | Elevation |
| 6 | Shapes | |
| 7 | Components | |
| 8 | Do's and Don'ts | |

---

### 1. Overview

Also known as "Brand & Style." A holistic description of the product's look and feel — brand personality, target audience, and emotional response the UI should evoke. Serves as foundational context when a specific rule or token is not defined.

```markdown
## Overview

A calm, professional interface for a healthcare scheduling platform.
Accessibility-first design with high contrast and generous touch targets.
```

---

### 2. Colors

Defines the color palettes. At least the `primary` palette should be defined. Additional palettes may be named freely; common convention is `primary`, `secondary`, `tertiary`, `neutral`.

```markdown
## Colors

The palette is rooted in high-contrast neutrals and a single accent color.

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** The sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation.
```

**Design tokens:**
```yaml
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
```

---

### 3. Typography

Defines typography levels. Most design systems have 9–15 levels, each with a semantic role (headline, body, label) and size variant (small, medium, large).

```markdown
## Typography

- **Headlines:** Public Sans Semi-Bold for an institutional voice.
- **Body:** Public Sans Regular at 16px for long-form readability.
- **Labels:** Space Grotesk for technical data and metadata.
```

**Design tokens:**
```yaml
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.1em
```

---

### 4. Layout

Also known as "Layout & Spacing." Describes grid models, spacing scales, and containment principles.

```markdown
## Layout

The layout follows a Fluid Grid model for mobile and a Fixed-Max-Width Grid
for desktop (max 1200px). A strict 8px spacing scale is used.
```

**Design tokens:**
```yaml
spacing:
  base: 16px
  xs: 4px
  sm: 8px
  md: 16px
  lg: 32px
  xl: 64px
  gutter: 24px
  margin: 32px
```

---

### 5. Elevation & Depth

Also known as "Elevation." Describes how visual hierarchy is conveyed. For shadow-based designs, defines shadow properties. For flat designs, explains alternative methods (borders, tonal layers, color contrast).

```markdown
## Elevation & Depth

Depth is achieved through tonal layers rather than heavy shadows.
Background uses a soft off-white; primary content sits on pure white cards.
```

---

### 6. Shapes

Describes corner radii, edge treatments, and overall shape language.

```markdown
## Shapes

All interactive elements use a minimal 4px corner radius.
Modern enough to feel current, rigid enough to feel engineered.
```

**Design tokens:**
```yaml
rounded:
  sm: 4px
  md: 8px
  lg: 12px
  full: 9999px
```

---

### 7. Components

Style guidance for component atoms. The spec defines common types (Buttons, Chips, Lists, Inputs, Checkboxes, Radio buttons, Tooltips) but design systems are encouraged to define additional components.

```markdown
## Components

- **Buttons**: Rounded (8px), primary uses brand blue fill, secondary uses outline
- **Inputs**: 1px border, surface-variant background, 12px padding
- **Cards**: No elevation, 1px outline border, 12px corner radius
```

**Design tokens:** Component variants are defined as separate entries with a related key name (e.g., `button-primary-hover`).

```yaml
components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"
```

**Component property tokens:**

| Property | Type |
|---|---|
| `backgroundColor` | Color |
| `textColor` | Color |
| `typography` | Typography |
| `rounded` | Dimension |
| `padding` | Dimension |
| `size` | Dimension |
| `height` | Dimension |
| `width` | Dimension |

---

### 8. Do's and Don'ts

Practical guidelines and common pitfalls. Act as guardrails during generation.

```markdown
## Do's and Don'ts

- Do use the primary color only for the single most important action per screen
- Don't mix rounded and sharp corners in the same view
- Do maintain WCAG AA contrast ratios (4.5:1 for normal text)
- Don't use more than two font weights on a single screen
```

---

## Consumer behavior for unknown content

| Scenario | Behavior | Example |
|---|---|---|
| Unknown section heading | Preserve; do not error | `## Iconography` |
| Unknown color token name | Accept if value is valid | `surface-container-high: '#ede7dd'` |
| Unknown typography token name | Accept as valid typography | `telemetry-data` |
| Unknown spacing value | Accept; store as string if not a valid dimension | `grid-columns: '5'` |
| Unknown component property | Accept with warning | `borderColor` |
| Duplicate section heading | **Error; reject the file** | Two `## Colors` headings |

---

## Recommended token names

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