Create your design.md — Google-aligned, AI-ready
An 8-step workflow that builds a complete, linter-compliant design.md without Google Stitch. Import from Tailwind, DTCG, or CSS, or author from scratch. Works with Claude, Cursor, and Copilot.
Readiness
8design stages
10sections
0lint errors
What is design.md?
design.md is an open specification published by Google that captures a complete visual identity in a single Markdown file — structured so AI coding agents read it as persistent context and generate consistently on-brand UI code.
Every design.md has two parts: a YAML front matter block containing machine-readable design tokens (colors, typography, spacing), and Markdown sections containing human-readable rationale and guardrails — eight canonical sections plus optional extension sections for Iconography and Accessibility.
---
colors:
surface: "#ffffff"
on-surface: "#0d0d0d"
primary: "#2d1b69"
on-primary: "#ffffff"
typography:
headline-display:
fontFamily: Inter
fontSize: 40
fontWeight: 700
lineHeight: 44
body-md:
fontFamily: Inter
fontSize: 16
fontWeight: 400
lineHeight: 26
spacing:
xs: 4px
sm: 8px
md: 16px
lg: 24px
xl: 40px
---
# Acme Dashboard
## Overview
Brand: Acme Corp · Product: SaaS Dashboard
Audience: B2B product teams · Tone: Professional
## Colors
Primary #2d1b69 — hero, primary actions
Surface #ffffff · On-surface #0d0d0d
## Do's and Don'ts
- DO: use primary for single CTA per view
- DON'T: use error red for non-error statesAligned with Google's design.md spec — by the linter, not by claim
PerfectPalette emits YAML front matter, the canonical 8-section order, and Google token names — on-surface, surface, headline-display — so your spec passes @google/design.md's official validator on every export.
- Zero lint errors: YAML front matter with structured token groups for colors, typography, spacing, and radius
- PP color roles map to spec token names at export time — your workspace language stays unchanged
- PP extension sections (Iconography, Accessibility) placed after spec sections as legal extensions
Token mapping
8 layered steps, one complete design.md
Each step builds on the previous — your intent drives typography, typography informs components, and guardrails validate everything. Nothing is skipped, nothing is guessed.
- Intent, Typography, Spacing, Components, Iconography, and Guardrails
- AI-assisted cleanup polishes rough notes into structured sections
- Curated libraries for brand attributes, design principles, and anti-patterns
Intent
Product overview, tone, principles
Palette
Colors, roles, health score
Typography
Families, scale, roles
Spacing
Base unit, steps, density
Components
Preset, buttons, cards
Iconography
Library, style, size scale
Guardrails
Accessibility, do/don't rules
Export
Build, preview, download
Create design.md from your existing tokens — without Google Stitch
Google Stitch generates design.md from screenshots. PerfectPalette starts from your actual palette and design decisions. Drop in a Tailwind config, DTCG JSON, a CSS file with @theme, or a ZIP — or paste any URL and we'll fetch or synthesize one from the live CSS.
- Tailwind v3 configs parsed via acorn AST — color, font, and spacing extracted automatically
- Tailwind v4 @theme CSS blocks, DTCG JSON, CSS custom properties, and ZIP archives all accepted
- AI extraction fallback: Sonnet fetches live site CSS and synthesizes a spec-compliant design.md
DTCG JSON
tokens.json
Tailwind v3
tailwind.config.js
CSS vars
theme.css
Archive
tokens.zip
or paste any URL with a published design.md
palette · intent · spec — ready in the workspace
Three-score readiness dashboard
See exactly how complete your spec is before exporting. Three independent scores — Palette Health, Design System coherence, and design.md readiness — with actionable remediation for every gap.
- Transparent scoring with hard gates and remediation advice
- Status progresses from incomplete → viable → strong → ready to export
- Versioned snapshots so you can track how the spec evolves over time
Readiness Dashboard
Canonical markdown for AI coding tools
The exported design.md follows a fixed section order so AI tools and teammates always know where to look. Drop it into your repo as CLAUDE.md context, paste it into Cursor, or hand it off to any coding agent.
- Structured for Claude, Cursor, Copilot, and any LLM-based tool
- Complete coverage: palette, typography, spacing, surfaces, components, icons, guardrails
- Deterministic output — identical inputs always produce identical markdown
One MCP call, always-fresh markdown
Claude, Cursor, and Copilot call v1.generate_design_md to pull a spec-compliant design.md on demand — and every public specimen URL regenerates the file deterministically at request time, so the AI never sees stale tokens.
- v1.generate_design_md accepts a validated palette plus optional title and design intent
- Missing sections default to sensible presets — Inter, balanced density, Lucide icons, WCAG-AA
- Regenerate-on-read: every published system serves spec-compliant output on every fetch
design.md
Common questions about design.md
- What is design.md?
- design.md is an open specification published by Google for describing a visual identity to AI coding agents. It combines YAML front matter (machine-readable design tokens for colors, typography, and spacing) with Markdown prose (rationale and guardrails). AI tools like Claude, Cursor, and Copilot read design.md as persistent context so they generate consistently on-brand UI code.
- What goes in a design.md file?
- A spec-compliant design.md has eight canonical sections in this order: Overview (brand, audience, and product context), Colors (color roles like on-surface and surface), Typography (font families and semantic roles like headline-display and body-md), Layout (spacing, density, and grid rules), Elevation & Depth (surface layers and depth scale), Shapes (border radius scale), Components (button, card, and input style rules), and Do's and Don'ts (accessibility rules and guardrail patterns). The YAML front matter encodes the machine-readable tokens; the Markdown sections carry the human-readable rationale. Iconography and Accessibility can be added as extension sections after the canonical eight.
- How do I create a design.md without Google Stitch?
- PerfectPalette is a dedicated design.md authoring tool that doesn't require Google Stitch, a Google account, or access to screenshots. Start from your existing Tailwind config, DTCG JSON, or CSS custom properties — PerfectPalette imports them and seeds a full design spec. Or start from scratch with the 8-step guided workflow: define intent, build a palette, configure typography, set spacing, choose component profiles, select an icon library, write guardrails, and export a linter-compliant design.md. The whole process runs in your browser at perfectpalette.io.
- Does PerfectPalette's design.md pass Google's official linter?
- Yes — exports include YAML front matter, the canonical section order (Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts), and Google's token names (on-surface, surface, headline-display, body-md). The generated output is designed to be spec-compliant with @google/design.md and is tested for linter compatibility.
- Which AI tools can read a design.md file?
- Any AI coding tool that accepts file context can read design.md: Claude (drop it into your project as CLAUDE.md), Cursor (add it to .cursorrules or project context), GitHub Copilot (reference it as workspace context), and any LLM-based tool via the v1.generate_design_md MCP tool. The fixed section order means every tool knows exactly where to find Colors, Typography, Components, and Do's and Don'ts information.
Give your AI the design context it needs
design.md authoring is a Pro feature. Start free and upgrade when you're ready.