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. Tokens are easily converted to and from tokens.json, Figma variables, and Tailwind theme configs.

Schema

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.

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.

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

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

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

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

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.

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

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

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

## Shapes

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

Design tokens:

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.

## 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).

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.

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