Google Stitch ships design.md — a markdown file it calls a "design agent." It has four color roles, three type scales, and component descriptions in plain English. That's documentation, not a design system. Here's the difference.
# design.md
## Color Palette & Roles
Primary: Ocean-deep Cerulean (#0077B6)
— Used for interactive elements,
calls to action, and links.
Background: Cloud White (#F8F9FA)
— Provides a clean, neutral canvas.
## Typography Rules
Heading: Inter 700, 32px/1.1
Body: Inter 400, 16px/1.6
## Component Stylings
Buttons use primary color with
4px border-radius and 12px 20px
padding. Hover state lightens
by 10%.On March 18, 2026, Google updated Stitch — its AI-native design canvas — with a feature called design.md: a markdown file that captures the visual language of a UI project in a portable, agent-readable format. The idea is simple and genuinely useful. Give an AI agent a design.md file and it has enough context to generate code that looks intentionally designed, not generically styled.
Google didn't invent this concept, but they named it in a way that stuck. The insight behind design.md is correct: AI coding agents need structured design context to produce consistent output. A plain text file that says "use #4F46E5 for primary actions and Inter 400 at 16px for body copy" is meaningfully better than no guidance at all.
A design.md file is organized into five sections, each covering a different dimension of the visual system:
Where design.md falls short isn't in its intent — it's in its depth and enforceability. Natural language describing a hover state is useful context. It's not a contract. The gap between describing a design system and encoding one is exactly what the rest of this page explores.
design.md describes your design system in natural language. Design tokens encode it in structured, machine-readable data. Neither is wrong — they serve different purposes. But one is copy-paste documentation; the other is enforceable infrastructure.
# design.md — Acme Corp
## Visual Theme & Atmosphere
A professional, modern aesthetic with
clean lines and confident colors.
Warm undertones, approachable but
authoritative. Suitable for B2B SaaS.
## Color Palette & Roles
Primary: Deep Indigo (#4F46E5)
— Core brand color. Use for primary
actions, navigation highlights,
and focus states.
Secondary: Warm Slate (#64748B)
— Supporting color for secondary
text and inactive UI elements.
Surface: Soft White (#FAFAF9)
— Page and card backgrounds.
## Typography Rules
Display: Plus Jakarta Sans 800
— Reserved for hero headlines.
Body: Plus Jakarta Sans 400, 16px
— Line height 1.6. Max width 68ch.
Code: JetBrains Mono 400
— Used inline and in code blocks.
## Component Stylings
Primary Button: Filled indigo (#4F46E5)
with white text, 10px border-radius,
12px 24px padding. Hover: lighten 8%.
Cards: White background, 1px border
(#E5E5E0), 16px border-radius,
subtle box-shadow.
## Layout Principles
8px base grid. Max content width
1120px. 24px side padding on mobile,
48px on desktop.{
"$schema": "https://design-tokens.org/schema.json",
"color": {
"primary": {
"50": { "$value": "#EEF2FF", "$type": "color" },
"100": { "$value": "#E0E7FF", "$type": "color" },
"200": { "$value": "#C7D2FE", "$type": "color" },
"300": { "$value": "#A5B4FC", "$type": "color" },
"400": { "$value": "#818CF8", "$type": "color" },
"500": { "$value": "#6366F1", "$type": "color" },
"600": { "$value": "#4F46E5", "$type": "color" },
"700": { "$value": "#4338CA", "$type": "color" },
"800": { "$value": "#3730A3", "$type": "color" },
"900": { "$value": "#312E81", "$type": "color" }
},
"semantic": {
"action-default": { "$value": "{color.primary.600}", "$type": "color" },
"action-hover": { "$value": "{color.primary.500}", "$type": "color" },
"action-pressed": { "$value": "{color.primary.700}", "$type": "color" },
"surface-default": { "$value": "#FAFAF9", "$type": "color" },
"surface-elevated": { "$value": "#FFFFFF", "$type": "color" },
"border-default": { "$value": "#E5E5E0", "$type": "color" },
"text-primary": { "$value": "#1C1917", "$type": "color" },
"text-secondary": { "$value": "#57534E", "$type": "color" }
}
},
"typography": {
"scale": {
"display": { "$value": { "fontFamily": "Plus Jakarta Sans", "fontWeight": 800, "fontSize": "56px", "lineHeight": 1.1 }, "$type": "typography" },
"h1": { "$value": { "fontFamily": "Plus Jakarta Sans", "fontWeight": 700, "fontSize": "40px", "lineHeight": 1.15 }, "$type": "typography" },
"body": { "$value": { "fontFamily": "Plus Jakarta Sans", "fontWeight": 400, "fontSize": "16px", "lineHeight": 1.6 }, "$type": "typography" },
"code": { "$value": { "fontFamily": "JetBrains Mono", "fontWeight": 400, "fontSize": "13px", "lineHeight": 1.7 }, "$type": "typography" }
}
},
"spacing": {
"1": { "$value": "4px", "$type": "dimension" },
"2": { "$value": "8px", "$type": "dimension" },
"3": { "$value": "12px", "$type": "dimension" },
"4": { "$value": "16px", "$type": "dimension" },
"6": { "$value": "24px", "$type": "dimension" },
"8": { "$value": "32px", "$type": "dimension" },
"12": { "$value": "48px", "$type": "dimension" }
},
"borderRadius": {
"sm": { "$value": "6px", "$type": "dimension" },
"md": { "$value": "10px", "$type": "dimension" },
"lg": { "$value": "16px", "$type": "dimension" },
"full":{ "$value": "9999px", "$type": "dimension" }
},
"shadow": {
"sm": { "$value": "0 1px 3px rgba(0,0,0,0.06)", "$type": "shadow" },
"md": { "$value": "0 4px 12px rgba(0,0,0,0.07)", "$type": "shadow" },
"lg": { "$value": "0 12px 32px rgba(0,0,0,0.09)", "$type": "shadow" }
}
}| Feature | design.md (Google Stitch) | Design Tokens (W3C format) |
|---|---|---|
| Format | Natural language markdown | Structured JSON with $type, $value |
| Machine-readable | No — requires parsing | Yes — direct programmatic access |
| Color scales | Named roles only (Primary, Background…) | Full 50–900 palette + semantic aliases |
| Enforceable | Copy-paste only | Import into Figma, Style Dictionary, CI |
| AI agent access | Read as text — prone to interpretation | Query by key — deterministic lookup |
| Token aliasing | Not supported | Yes — {color.primary.600} references |
| Portability | Great for humans, fragile for tools | Works across any W3C-compliant toolchain |
design.md is documentation. Design tokens are better — but they're still static files you check into a repo, copy between projects, and manually keep in sync. The real future is runtime expression infrastructure that your agents can query, validate against, and resolve on demand.
action-primary at runtime, deterministically.LESS turns your design tokens into live infrastructure. Not a markdown file to paste. Not a JSON blob to commit. A runtime API your agents query, validate against, and resolve — deterministically, every time.
The gap between "describing" a design system and "enforcing" one is exactly where Google Stitch stops and where LESS begins.
See how LESS works →design.md is a structured markdown file produced by Google Stitch that captures a UI's visual language across five sections: Visual Theme & Atmosphere, Color Palette & Roles, Typography Rules, Component Stylings, and Layout Principles.
Each section describes design decisions in natural language, often pairing descriptive names with exact hex values or pixel measurements in parentheses — for example, "Ocean-deep Cerulean (#0077B6) — used for interactive elements." It is generated either from a text prompt describing the desired aesthetic or by extracting rules from an existing screenshot or URL.
The format is designed to be portable: something you can paste into a coding agent's context window to give it consistent design guidance. That's a real improvement over no guidance at all — but it stops well short of a formal design system.
No — they're fundamentally different things, even though they cover similar territory. design.md is natural-language documentation: it describes design decisions in prose that humans and LLMs can read and interpret. A design token file is structured data: a JSON file where every value carries an explicit $type and $value, enabling tools to parse, validate, and transform it programmatically.
A design.md entry saying "Primary: Deep Indigo (#4F46E5) — used for interactive elements" is a description. A token entry like "action-default": { "$value": "#4F46E5", "$type": "color" } is a contract. The distinction matters most when tools — not humans — are the consumers. A build tool, a CI linter, or a Figma plugin cannot reliably consume natural language. They can consume structured tokens directly.
Yes — but only as read-only context, not as a queryable interface. AI agents can ingest design.md as plain text and use it to inform generated UI code: it gives the model useful guidance about intended colors, type sizes, and component patterns. For simple, single-session tasks this often works well enough.
What design.md cannot provide is a reliable lookup interface. If an agent needs to know "what is the exact disabled state color for a secondary button?" there is no structured key to query — only prose to parse. This creates interpretation variance: the same question asked in two different contexts may yield subtly different answers, especially as context windows grow long.
Design tokens solve this by making every decision a named, typed key agents can resolve deterministically — color.neutral.300 always returns the same value, regardless of how the question is phrased.
The W3C Design Token Community Group (DTCG) is developing a standardized specification for design tokens — a shared format that tools like Figma, Style Dictionary, and Theo can all read and write without custom transformation layers. It is not yet a formal W3C standard, but has broad industry adoption and is the de-facto format for interoperable token systems.
In DTCG format, every token is a JSON object with two required fields: $value (the raw value) and $type (the semantic category — color, dimension, typography, duration, shadow, etc.). Tokens can reference other tokens using a {dot.path} alias syntax, enabling semantic layers — for example, action-default can alias to {color.primary.600}, so changing the primary palette automatically updates all semantic action tokens.
Adopting DTCG format means a token file you define today can be consumed by any compliant tool in your toolchain — now and as the ecosystem grows.
Design tokens are static files — they encode decisions at a point in time and must be manually updated, versioned, and distributed across every repo that uses them. The enforcement model is convention: teams agree to use the tokens, but nothing stops a developer from hardcoding a value. LESS (from Designless) is runtime expression infrastructure: a live API that agents query to resolve design values on demand, without parsing a file or depending on a particular repo's token state.
Rather than asking "does this repo have the latest tokens.json checked in?", an agent queries the LESS API and receives a deterministic, always-current response. LESS also supports bidirectional validation — it can verify that generated code actually conforms to the brand contract, not merely suggest values. That closes the loop between design intent and shipped code in a way static token files cannot.
Pick your brand colors, choose a type style, and see both outputs side-by-side — the Google Stitch-style design.md and the W3C-format token JSON.
No signup. No export limits. Just tokens.