Design.md Cheat Sheet

DESIGN.md — The Comprehensive Cheat Sheet

Design.md — Cheat Sheet

TL;DR

DESIGN.md is an open Apache-2.0 file-format specification from Google Labs (open-sourced April 21, 2026) that gives AI coding agents a persistent, structured understanding of a design system — it pairs YAML front-matter design tokens (machine-readable) with Markdown prose (human-readable rationale) in a single file dropped into your repo root, the same way README.md documents code and AGENTS.md documents agent behavior.

**The official Google spec defines 8 canonical sections:**

• Overview
• Colors
• Typography
• Layout
• Elevation & Depth
• Shapes
• Components
• Do’s and Don’ts

The **community VoltAgent/awesome-design-md extension adds a 9th section** (Visual Theme & Atmosphere, Color Palette & Roles, Typography Rules, Component Stylings, Layout Principles, Depth & Elevation, Do’s & Don’ts, Responsive Behavior, Agent Prompt Guide).

Adoption was explosive: the official [google-labs-code/design.md](https://github.com/google-labs-code/design.md) repo hit 5.2k stars in 72 hours and ~14.3k by mid-May 2026 (per issue #85, May 18, 2026); VoltAgent's community collection hit 35,082 stars and 4,415 forks within 10 days of its March 31 launch — per OSS Insight, "faster than any awesome list in GitHub history" — and reached 84.3k stars / 10.1k forks by May 25, 2026. The format is still in version: alpha and the components schema is acknowledged by Google to be "actively evolving."

Key Findings

• DESIGN.md replaces re-prompting with a versioned contract. Marco Kotrotsos’s diagnosis is the canonical framing: “Five pages of the same app, generated by the same agent, can end up with five different design systems. The buttons drift. The grays shift… This is a context failure, not a model failure.” DESIGN.md solves the context failure by acting as a persistent, repo-resident contract.
• Two-layer architecture is the core idea. YAML front matter (delimited by ---) holds normative typed tokens; Markdown body holds the why. Per the spec: "Tokens give agents exact values. Prose tells them why those values exist and how to apply them." This is the pattern worth stealing even if the spec changes.
• It complements, not replaces, Figma and AGENTS.md. DESIGN.md sits in the same plain-text contract layer as AGENTS.md (released by OpenAI in August 2025 and now governed within the Linux Foundation's AI Agents Initiative — co-founded by OpenAI, Anthropic, and Block, with Google, Microsoft, and AWS as Platinum members; adopted by Cursor, Devin, Factory and 60,000+ projects per the Linux Foundation's December 9, 2025 announcement) and SKILL.md (Anthropic Claude Skills) — three orthogonal files for behavior, tasks, and visual appearance. Figma remains better for visual collaboration; DESIGN.md handles the spec-to-agent handoff.
• The CLI is real and useful. npx @google/design.md ships lint, diff, export (to Tailwind v3 JSON, Tailwind v4 CSS, or W3C DTCG tokens.json), and spec commands. The linter runs 7 named rules; broken token references are errors, WCAG AA contrast failures (<4.5:1) are warnings.
• The prose layer is what separates strong files from weak ones. Lisa Demchenko’s investigation found “the tokens were perfect. The reasoning layer was fabricated” — models can infer hex values but not intent. The most-impactful section, per multiple practitioners, is Do’s and Don’ts: explicit negative constraints carry more weight than additional tokens.

Details

1. What DESIGN.md Is and Why It Exists

DESIGN.md is “a format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system” (official GitHub one-liner). It originated inside Google Stitch, Google Labs’ AI UI design tool — launched at Google I/O 2025 on May 20, 2025 (per TechCrunch and the Google Developers Blog), built on Gemini 2.5 Flash for Standard mode and Gemini 2.5 Pro for Experimental mode, and free via Google Labs after Google’s Galileo AI acquisition. DESIGN.md was introduced in the Stitch 2.0 update (March 19, 2026) alongside multi-screen generation, infinite canvas, and voice input, then open-sourced under Apache 2.0 on April 21, 2026 so it could “be used across any single tool or platform” (blog.google announcement).

The problem it solves, per Google Labs’ David East in the announcement video: DESIGN.md is “a persistent context layer — something an agent reads once at session start rather than something a developer has to re-explain with every prompt.”

The format is read by any agent that scans the repo filesystem: Claude Code, Cursor, GitHub Copilot, Google Stitch, Gemini CLI, Antigravity, Kiro, Windsurf, Cline, v0, Lovable, plus future agents that follow the convention.

2. File Anatomy

---
version: alpha            # optional
name: Heritage
description: …            # optional
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"
---

## Overview
Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
premium matte finish — a high-end broadsheet or contemporary gallery.

## Colors
- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
…

Token types:

Design.md — Token Types

Component properties whitelist: backgroundColor, textColor, typography, rounded, padding, size, height, width. Variants are sibling keys (button-primary-hover), not nested (button-primary.hover is wrong).

3. The Canonical 8 Sections (Google Spec)

Sections use ## headings, can be omitted, but those present must appear in this order (the section-order linter rule flags deviation):

Design.md — The Canonical 8 Sections

4. The 9-Section Extension (VoltAgent / Community)

The widely-used VoltAgent/awesome-design-md template adds two sections and renames several to be more LLM-prompt-friendly:

Design.md — The 9-Section Extension (VoltAgent / Community)

The Agent Prompt Guide is the genuine innovation — it treats the AI as a teammate with explicit meta-instructions (e.g., “When generating UI: always reference tokens from sections 2–6; ensure WCAG AA contrast minimums; prioritize subtle animations for real-time features”).

5. The CLI — @google/design.md

npm install @google/design.md          # or npx, no install needed
# Windows users: use the "designmd" alias inside package.json scripts

Design.md — The CLI

The 7 linter rules:

Design.md — The 7 linter rules

The linter is also a library:

import { lint } from '@google/design.md/linter'.

6. How to Write an Effective DESIGN.md

Synthesizing guidance from Nick Babich (UX Planet), Lisa Demchenko (UX Collective), Marco Kotrotsos (Medium), the TDP team, and the official spec:

Babich’s philosophy (UX Planet): “Unlike a traditional specification that often has very specific details that designers should follow when crafting a new design, DESIGN.md is less prescriptive in its nature. It creates a solution foundation for AI tools (colors, typography, corner radius) while providing enough freedom to alter the format for domain-specific needs.” He adds: “DESIGN.md is a living artifact, not a static config file. It should evolve as your design evolves.”

Demchenko’s “value, intent, boundary” formula (UX Collective).

Instead of:

primary: #1B4DFF

write:

primary: #1B4DFF — CTAs and active states only. Never used as a background,
never decorative. One per screen. If you're reaching for two, reconsider the layout.

Demchenko’s mandatory interview (4 questions before writing anything):

1. What does the product do?
2. Who uses it?
3. What must the UI always do?
4. What can it never do?

Her central insight: “The tokens were perfect. The reasoning layer was fabricated.” A model will fill any silence with plausible-sounding inference; DESIGN.md’s job is to remove that silence. She also notes underperformers “start with a colour palette. No context before the first hex code” — the brief must come first.

TDP’s anti-pattern advice: Write Do’s and Don’ts last and make them specific by walking through real AI generations and writing a “don’t” for each bad output. “I noticed this pattern across Stitch, Claude Code, and v0 — the don’ts pulled more weight than the do’s.” Example don’ts that work:

• “Don’t use full-uppercase headers.”
• “Don’t stack more than two CTAs.”
• “Don’t use drop shadows on cards — we use borders.”
• “Don’t mix rounded and sharp corners in the same view.”
• “Don’t use more than two font weights on a single screen.”

Match reality, not aspiration. TDP: “Open the product you ship today. Screenshot five core screens. Pull the actual hex values, font sizes, and radii from the code. Write the file to match reality, not the redesign you wish you’d shipped.”

Build it with engineering, not for them. A DESIGN.md is “a shared contract” — sit with an engineer for half an afternoon to catch tokens that don’t exist in the theme and components that got renamed.

7. Wiring DESIGN.md Into Each Agent

• Claude Code: Drop DESIGN.md in repo root; in CLAUDE.md, add: "Always refer to DESIGN.md when generating UI components. Use only colors, fonts, and spacing defined in DESIGN.md. Never introduce values outside the documented scale. Validate accessibility against the Do's and Don'ts section."
• Cursor: Add the file to .cursor/rules so it's injected on every UI generation.
• Kiro: Place it in .kiro/steering/.
• Windsurf: Configure global_rules.md to point at your DESIGN.md.
• Google Stitch: Native — export DESIGN.md directly from any Stitch project, or import one to constrain generation.
• GitHub Copilot Workspace / Antigravity / Gemini CLI: read repo files automatically; just reference DESIGN.md in the opening prompt.

8. Tooling and Ecosystem

Companion files & layered context model (per dev.to analysis):

• AGENTS.md — coding/behavior conventions. Released by OpenAI in August 2025; now governed within the Linux Foundation's AI Agents Initiative (co-founded by OpenAI, Anthropic, and Block on December 9, 2025; Google, Microsoft, and AWS joined as Platinum members; Cursor, Devin, and Factory are among 60,000+ adopters).
• SKILL.md — Anthropic Claude Skills (per-task capability).
• DESIGN.md — visual identity contract.

Where to get one without writing it:

• VoltAgent/awesome-design-md (MIT) — community collection of DESIGN.md files reverse-engineered from real brand sites (Apple, Notion, Stripe, Vercel, Linear, Airbnb, Anthropic Claude, Spotify, Figma, Cursor, Coinbase, Uber, BMW, Ferrari, NVIDIA, Tesla, Nike, etc.). Created March 31, 2026 — three weeks before Google’s official open-source release. Each entry ships with DESIGN.md, preview.html, and preview-dark.html. 84.3k stars / 10.1k forks by May 25, 2026 (per GitHub issues page).
• designmd.ai — community platform with 100+ free downloadable design systems, browsable by tags (dark, saas, minimal, fintech, etc.).
• designmd.app — library of 454+ design systems plus per-tool setup guides.
• getdesign.md — curated independent analyses; built on Google’s DESIGN.md spec.
• design.dev/ai/design-md-generator — visual editor with live preview, WCAG AA linting, and Tailwind/DTCG/CSS export, mirroring the official 7-rule linter (plus its own 8th token-summary info rule).
• design-extractor.com — paste any URL, get a structured DESIGN.md derived from CSSOM frequency analysis.
• Google Stitch export — generate a DESIGN.md from any Stitch project for free.
• Stitch Skills (design-md) — npx skills add google-labs-code/stitch-skills --skill design-md --global — auto-extracts DESIGN.md from a Stitch project.

Interoperability: Token model is inspired by the W3C Design Tokens Format Module (DTCG), so DESIGN.md tokens convert cleanly to tokens.json, Figma Variables, and Tailwind theme configs via the export command.

9. Adoption and Industry-Standard Trajectory

Design.md — Adoption and Industry-Standard Trajectory

The honest verdict on standard-vs-trend: Practitioners and the muz.li columnist (Thalion, “DESIGN.md: new standard or temporary trend?”) treat DESIGN.md as a credible standardization signal because (a) tokens follow the W3C DTCG structure — Google isn’t reinventing the wheel; (b) the file is plain Markdown — zero tooling friction; © export paths exist to every neighboring ecosystem (Tailwind v3, Tailwind v4, DTCG). The risks: alpha schema, no enforcement (the agent can still ignore the file), no governance body yet (Google Labs holds the pen), and adoption hinges on Figma/v0/Cursor/Lovable formally supporting it rather than just reading it as plain text.

10. Use Cases and Benefits

• Cross-tool portability. Same DESIGN.md works in Claude Code, Cursor, v0, Lovable, Stitch, and Copilot — write it once.
• Brand consistency at scale. Five screens generated with DESIGN.md hold their style; five without it drift.
• Built-in accessibility audit. WCAG AA contrast checked automatically; the lint output reads e.g. “textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA.”
• Version control as first-class design citizen. Diffs, PRs, history — design changes get reviewed like code.
• CI integration. Run lint in CI to catch token drift; diff returns exit 1 on regressions.
• DTCG escape hatch. If Google deprecates the spec, export --format dtcg produces a W3C-standard token file.

11. Known Limitations (Acknowledged by Google and Practitioners)

• No enforcement at generation time. The lint CLI catches problems after the agent has already generated drift. For scale, you still need component libraries that enforce tokens at the code level.
• No animation or interaction-state tokens in the current schema.
• Alpha-status instability — field names can change; pin your CLI version.
• Components schema is “actively evolving” (Google’s own language).
• It is not a Figma replacement. Realistic workflow is hybrid: Stitch + DESIGN.md for ideation and code handoff, Figma for visual polishing and team comments.
• Adoption is uneven. Stitch consumes it natively; other agents read it as project context but don’t enforce it.

12. Best-Practice Token References

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

Token paths resolve by dotted address: {colors.primary} works; {primary} does not. Hex colors must be quoted strings (YAML otherwise treats # as a comment). Components reference primitives; the components section is the only place composite typography references are allowed.

Recommendations

Stage 1 — Adopt this week (cost: one afternoon):

1. Read the spec once: npx @google/design.md spec.
2. Clone a near-fit brand from VoltAgent/awesome-design-md or generate one in Stitch from your live site.
3. Drop the file in your repo root as exactly DESIGN.md.
4. Run npx @google/design.md lint DESIGN.md and fix every broken-ref error and contrast-ratio warning.
5. Add a reference line in CLAUDE.md/AGENTS.md/.cursor/rules: "Before writing UI code, read DESIGN.md. Use the token values and semantic descriptions for all design decisions. Do not use arbitrary color values."

Stage 2 — Harden after 1–2 weeks of agent use: 6. Run Demchenko’s diagnostic loop: generate three screens, log every deviation, add a Don't rule for each. Repeat until output stabilizes. 7. Replace bare hex values in the prose with value + intent + boundary statements ("Primary is rationed: one per screen, only the most important action"). 8. Add npx @google/design.md lint to CI and npx @google/design.md diff to PRs against main.

Stage 3 — Scale across teams (cost: one quarter): 9. Export dtcg and css-tailwind in CI so the same source of truth flows into Storybook, Style Dictionary, and Tailwind. 10. Sit with engineering for half an afternoon to align names in DESIGN.md with names in the actual component library. 11. If you maintain multiple brands or sub-brands, create one DESIGN.md per brand and version them as Git submodules — VoltAgent's repo demonstrates the pattern.

Benchmarks that change the recommendation:

• If your team ships <1 UI screen/week with agents, the payoff is marginal — wait two quarters for the spec to leave alpha.
• If Figma, v0, or Cursor announce native DESIGN.md support (today they only read it as plain text), accelerate adoption — that flips the format from “convention” to “standard.”
• If your project is regulated (healthcare, finance, government), adopt now — the WCAG AA linter is a defensible accessibility audit trail.
• If Google publishes a 1.0 release out of alpha, treat that as the signal to pin to a stable schema and remove version caveats from your team docs.

Caveats

• Alpha status is real. The official repo states bluntly: “The DESIGN.md format is at version alpha. The spec, token schema, and CLI are under active development. Expect changes to the format as it matures." Field names and rule names have already shifted (token-summary is on some forks listed as an 8th rule, on others as info-only; the spec ships with 7 rules at the time of writing).
• Two different section sets coexist. Google’s official 8 vs. VoltAgent’s 9 (Responsive Behavior + Agent Prompt Guide). Both are valid in the wild but the linter only validates Google’s order; using the VoltAgent extension will produce section-order warnings if you don't follow the canonical sequence for the 8 it knows about.
• VoltAgent’s collection count varies by source. Marco Kotrotsos cited “423 brand systems”; other May 2026 audits put the actual file count closer to 55–70. The discrepancy likely reflects variants and preview files vs. unique brand systems. Treat the headline number as a marketing approximation.
• The blog.google announcement video walkthrough is presented by David East of Google Labs, but Google has not announced a long-term governance model. As of late May 2026 the main maintenance still sits with Google Labs; no W3C-style independent committee exists.
• DESIGN.md does not test every generated UI against WCAG — it only validates the specific bg/text combinations you’ve encoded. Dynamic content and runtime color mixing fall outside the linter’s scope.
• Practitioner commentary varies. Industry voices including TDP, Banani, vibe coding directories, and Substack writers (Demchenko, Kotrotsos) treat DESIGN.md as already-useful in alpha; some skill maintainers (anthropics/skills issue #1008) explicitly note their team is still deciding whether to adopt it. Treat the format as high-promise, not yet certified-standard.
• Some Medium articles in the user’s source list (e.g., “The 9 Sections Every DESIGN.md Needs” on generativeai.pub, and the original UX Planet “AI and Design System” piece) were not fully retrievable due to robots.txt and paywall restrictions — quoted positions in this report are drawn from accessible snippets, syndicated reprints, and the spec itself rather than the full Medium articles.

More

• GetDesign.md Analyzed patterns, tokens, and rules as inspiration for your coding agent. Built with real depth for high-quality UI generation, not surface-level.
• VibeDesign: Chrome extension to get any site url Design.md