Google Stitch DESIGN.md Specification: A Plain-Text Design System for AI Agents

The Google Stitch DESIGN.md specification defines a Markdown-based format that enables AI agents to read design tokens and generate consistent UI components without requiring Figma exports, JSON schemas, or specialized tooling.

Google Stitch introduced DESIGN.md as a deterministic, human-readable design system document that lives at the root of a project. According to the VoltAgent/awesome-design-md repository, this specification allows development teams to maintain visual consistency by storing colors, typography, spacing, and component definitions in a single file that LLMs can parse natively.

Core Architecture of the DESIGN.md Format

File Layout and Metadata

Every DESIGN.md file begins with a YAML front-matter block followed by named sections that define the visual language. As implemented in design-md/apple/DESIGN.md, the metadata establishes version and context:

---
version: alpha
name: Apple-design-analysis
...

Because the format is pure Markdown, it requires no compilation steps or proprietary software. The specification is published officially at stitch.withgoogle.com/docs/design-md/specification/, ensuring compatibility across different AI agent implementations.

Token System and References

The specification employs a token reference syntax using curly braces and dot notation. Values like {colors.primary}, {rounded.pill}, or {typography.body} create reusable design tokens that propagate throughout the document. In the Apple example from the repository, component definitions map these references to concrete styling: backgroundColor: "{colors.primary}" resolves to the actual hex value during agent processing.

The Nine-Section Schema

The Google Stitch DESIGN.md specification mandates nine numbered sections that capture comprehensive design intent:

1. Visual theme — Core aesthetic direction
2. Palette — Color definitions and semantic mappings
3. Typography — Font families, sizes, weights, and hierarchies
4. Component stylings — Reusable UI element specifications
5. Layout — Grid systems and spacing scales
6. Depth — Shadows, elevation, and z-index patterns
7. Guardrails — Constraints and design rules
8. Responsive behavior — Breakpoints and adaptation rules
9. Agent prompt guide — Ready-to-use prompts for AI reproduction

Section nine specifically provides "quick color reference, ready-to-use prompts" that allow agents to reproduce specific visual characteristics without additional parsing logic, as noted in the repository README.

Implementing the Specification in Practice

Loading Design Tokens from DESIGN.md

Developers extract token definitions by parsing the YAML front-matter. Here is a Node.js implementation for reading design-md/apple/DESIGN.md:

import fs from 'fs';
import yaml from 'js-yaml';

// Read the DESIGN.md file (strip front‑matter)
const raw = fs.readFileSync('design-md/apple/DESIGN.md', 'utf8');
const [, frontMatter, ...body] = raw.split(/^---$/m);
const tokens = yaml.load(frontMatter);

// Example: Resolve a token reference
function resolve(path) {
  return path.split('.').reduce((obj, key) => obj && obj[key], tokens);
}
console.log('Primary brand color:', resolve('colors.primary')); // → "#0066cc"

Generating UI Components Programmatically

Once tokens are loaded, applications construct component specifications by resolving token paths to concrete values:

function generateComponent(name) {
  const comp = tokens.components[name];
  return {
    background: resolve(comp.backgroundColor),
    color: resolve(comp.textColor),
    borderRadius: resolve(comp.rounded),
    font: resolve(comp.typography),
    padding: comp.padding,
  };
}
console.log(generateComponent('button-primary'));
/*
{
  background: "#0066cc",
  color: "#ffffff",
  borderRadius: "9999px",
  font: {fontFamily: "...", fontSize: "17px", ...},
  padding: "11px 22px"
}
*/

Prompting LLMs with Design Context

The specification enables direct prompting of AI agents using token placeholders. When querying an LLM to build UI, developers reference the DESIGN.md specification and token paths explicitly:

Using the DESIGN.md specification, create a React button component that matches the `button-primary` token:
- Background: {colors.primary}
- Text color: {colors.on-primary}
- Rounded: {rounded.pill}
- Typography: {typography.body}
- Padding: 11px 22px

The agent replaces token placeholders with resolved values from the file to output production-ready JSX or CSS.

Real-World Examples in the Repository

The VoltAgent/awesome-design-md repository contains complete implementations demonstrating the specification across different brands:

• design-md/apple/DESIGN.md — Full implementation following the Apple site design system, featuring iOS-style typography and blue-primary color schemes
• design-md/spotify/DESIGN.md — Music streaming platform design tokens emphasizing dark themes and rounded components
• design-md/webflow/DESIGN.md — Visual-builder platform implementation showing how the spec adapts to no-code environments

These files illustrate how the nine-section schema applies to diverse visual languages, providing reference implementations for agents that must read and render UI from plain-text design documents. The repository also includes CONTRIBUTING.md, which outlines guidelines for adding new DESIGN.md files that conform to the Stitch specification.

Summary

• The Google Stitch DESIGN.md specification defines a plain-text Markdown format for design systems that AI agents can parse natively without additional tooling.
• Files use YAML front-matter for metadata and token references (e.g., {colors.primary}) for reusable values across nine structured sections.
• The format eliminates dependencies on Figma exports or JSON schemas, residing as a single DESIGN.md file at the project root.
• Reference implementations in design-md/apple/DESIGN.md, design-md/spotify/DESIGN.md, and design-md/webflow/DESIGN.md demonstrate production-ready usage patterns.

Frequently Asked Questions

What is the Google Stitch DESIGN.md specification?

The Google Stitch DESIGN.md specification is a standardized Markdown format published by Google Stitch that documents design systems in plain text. It enables AI coding assistants and design bots to read visual tokens, typography scales, and component definitions directly from a repository, eliminating the need for specialized design tool exports or complex configuration files.

How do AI agents parse DESIGN.md files?

AI agents parse DESIGN.md by extracting the YAML front-matter block to retrieve metadata and token definitions, then resolving token references like {colors.primary} using dot-notation path reduction against the parsed object. Because the format is pure Markdown with predictable section headings, LLMs can process the content natively using standard parsing libraries without custom schemas.

What are the nine sections in a DESIGN.md file?

According to the specification, the nine sections are: (1) Visual theme, (2) Palette, (3) Typography, (4) Component stylings, (5) Layout, (6) Depth, (7) Guardrails, (8) Responsive behavior, and (9) Agent prompt guide. Section nine provides specific prompts that help AI systems reproduce exact colors, shadows, and typographic treatments without requiring additional interpretation of the design tokens.

Where can I find examples of DESIGN.md implementations?

Complete examples are available in the VoltAgent/awesome-design-md repository, specifically in design-md/apple/DESIGN.md, design-md/spotify/DESIGN.md, and design-md/webflow/DESIGN.md. These files demonstrate how different brands implement the nine-section schema with specific tokens and component definitions, serving as authoritative reference material for developers building Stitch-compatible agents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}