What is DESIGN.md

In March 2026, Google Stitch introduced DESIGN.md as part of an update that included infinite canvas, a design agent with project memory, instant prototyping and voice interaction. Among all these features, DESIGN.md is the least visible — but the most reusable outside the Stitch ecosystem.

DESIGN.md is a Markdown file that serializes a design system — color palette, typography, spacing, component patterns and visual constraints — in a format optimized for LLM consumption. The file sits at the repository root and the AI agent reads it before generating any interface.

The most accurate analogy: DESIGN.md is to design what AGENTS.md is to code conventions. It's persistent context that the agent consults on every interaction.

Format

Format and structure

A DESIGN.md is composed of sections with Markdown headings. Each section has a specific function in the agent's context. Order matters: the LLM processes top to bottom.

1. Overview

Product description and visual direction in 2-3 sentences. Gives the LLM context calibration before processing technical specs.

## Overview
Analytics app for enterprise finance. Precise, reliable, minimal visual.

2. Colors

Hex + semantic name + usage rule. Without a semantic name, the LLM might use the error color as accent.

## Colors
- **brand-primary** (#1A73E8): main actions, links, interactive states
- **neutral-surface** (#F8F9FA): surface backgrounds and cards
- **status-error** (#D93025): error states and destructive actions only

3. Typography

Families, weights and scale with concrete values. The agent needs numbers — "large font" is not a useful instruction for an LLM.

## Typography
- Headlines: Inter, 600, 24-48px, tracking-tight
- Body: Inter, 400, 14-16px, leading-relaxed
- Mono: JetBrains Mono, 400, 13px (code blocks, numeric data)

4. Spacing

Base unit and named scale. Without a defined scale, each generated component uses arbitrary spacing.

## Spacing
Base: 4px
- xs: 4px | sm: 8px | md: 16px | lg: 24px | xl: 32px | 2xl: 48px

5. Components

Visual patterns with states. Without this section, the agent invents different states on each generation.

## Components
### Buttons
- Primary: filled brand-primary, text white, rounded-lg, py-2 px-4
- Hover: brightness +10%
- Disabled: opacity 50%, cursor not-allowed

6. Do's and Don'ts

Explicit constraints. LLMs respond well to negative instructions — saying what not to do is as important as saying what to do.

## Do's and Don'ts
- DO: use primary only for the most important action on screen
- DON'T: mix rounded and sharp corners in the same component
- DO: maintain minimum 4.5:1 contrast ratio for text
- DON'T: use shadows on more than 2 elevation levels

Format

Why Markdown and not JSON or YAML

Markdown is the format LLMs understand with the highest fidelity. Most of the training corpus uses this structure. The model needs no extra instruction to interpret it.

JSON design tokens define values, but not rules. There's no way to express "use primary only for the main action" in a tokens.json file. DESIGN.md combines values and semantics in the same file, without a build pipeline.

Criteria	DESIGN.md	Tokens (JSON)	Style Guide
LLM-readable	Native (trained on MD)	Requires parsing	Not readable
Human-readable	Yes, no tooling	Partial	Yes
Versionable (Git)	Yes	Yes	No (binary)
Context window	Light (~2-5K tokens)	Medium	N/A
Build pipeline	None	Required	N/A
Semantic rules	Yes (Do's/Don'ts)	No (values only)	Yes

How to get one

How to get a DESIGN.md

Four paths, from fastest to most controlled.

1. Copy from the designmd.app library

Choose by vertical or visual style, customize values for your project and use. The library has over 400 documented files.

2. Generate with the design-md skill

The skill analyzes the existing codebase — components, CSS variables, tokens — and extracts a structured DESIGN.md from the patterns found.

3. Export from Google Stitch

If the project already uses Stitch, the export is native. The generated file follows the same structure documented here.

4. Write manually

Follow the 6-section structure above. Full control over every design decision.

FAQ

Frequently asked questions

What is DESIGN.md?

A Markdown file that serializes a design system for consumption by AI agents. It defines colors, typography, spacing, component patterns and visual constraints in a format optimized for LLMs. Standard introduced by Google Stitch in March 2026.

Does DESIGN.md replace Figma?

No. Figma is a visual design tool for creating interfaces. DESIGN.md is the translation of those design decisions into a format that AI agents read and apply automatically. They are complementary.

Do I need design skills to use DESIGN.md?

Not to use a ready-made one. The designmd.app library has over 400 files ready to copy. The design-md skill generates one from your existing codebase.

Does it work with any AI agent?

Yes. Any agent that reads repository files can use DESIGN.md: Claude Code, Cursor, Kiro, Windsurf, Google Stitch and others.

What's the difference between DESIGN.md and JSON design tokens?

JSON design tokens define only values (colors, spacing). DESIGN.md defines values + semantic rules + constraints (Do's and Don'ts). Tokens need a build pipeline. DESIGN.md is plain Markdown.

Can I use it in an existing project?

Yes. Add the DESIGN.md file to the project root and reference it in your agent's configuration file. It doesn't alter existing code.

How do I update it when the design changes?

Edit the file. It's Markdown — any text editor works. Version with Git to keep change history.

Does it work with React, Vue, Svelte?

DESIGN.md is framework-agnostic. It defines visual rules, not implementation. The agent applies these rules regardless of framework.

Next steps

Explore the library with over 400 documented DESIGN.md files or generate one from your existing codebase.

View library design-md skill →