design-md

name	design-md
description	Write, read, and apply DESIGN.md files — Google Stitch's open AI-readable design-system format (YAML design tokens + Markdown rationale). Use when asked to "create a design.md", "extract a design system from [brand/PDF/site/screenshots]", "document this brand for AI tools", or when reverse-engineering a brand's visual identity into reusable tokens for an AI coding agent to apply consistently.

DESIGN.md — AI-readable design system files

DESIGN.md is an open format introduced by Google Stitch (the design.md spec — https://stitch.withgoogle.com/docs/design-md/). It's a single Markdown file, dropped in a project's root next to README.md, that an AI coding agent reads to generate or restyle UI consistently with a brand. It works because it pairs two layers in one file:

"Tokens give agents exact values. Prose tells them why those values exist and how to apply them." — design.md spec

• YAML front matter — machine-readable design tokens (colors, typography, spacing, shape, components) an agent can reference exactly.
• Markdown body — human-readable rationale, organized into a canonical section order, that tells the agent why those values exist and how to apply them in context.

This is the format used by Stitch, and it's Claude/Cursor-compatible: the workflow is "drop DESIGN.md in the repo root → tell the agent Use the @DESIGN.md file and style my app."

A community collection of 70+ real-world examples (Linear, Stripe, Apple, Figma, Cursor, Tesla, etc.) lives at https://github.com/voltagent/awesome-design-md — each entry pairs a DESIGN.md with preview.html/preview-dark.html visual catalogs. Use these as calibration references for tone, token granularity, and section depth.