Google Stitch just introduced DESIGN.md as a machine-readable, portable design system manifesto. Token-level rules in the repo give agents something concrete to follow instead of vague adjectives.
Google Stitch's DESIGN.md is a markdown file of design tokens sitting in your repo root. I point Claude Code and Cursor at it so they stop inventing a new shade of blue on every page.
I rotate through side projects faster than I should, which means I keep re-teaching agents the same UI rules. Inter for body text. This hex for primary buttons. 8px radii on cards, not 12, not 6. Tell an agent to "make it look clean" and you get the same generic Tailwind dashboard every time.
I've been testing this with Cursor Composer-2 and Claude Opus 4.6 on nathanfennel.com and a few smaller repos. The annoying part isn't the coding. It's repeating the brand decisions on every fresh thread.
Stitch's fix is DESIGN.md. A markdown file at the repo root with your colors, type scale, spacing, and component notes. README for how things should look, not how to run the dev server.
JSON and YAML token files work fine in a build pipeline. I don't open them in a design review. Markdown I'll actually edit, and agents already read it without a plugin or parser config. That part matters more than it sounds. One file, one source of truth, no translation layer.
Hex values, font families, spacing scale, border radii, shadow rules. The stuff an agent can apply mechanically when it generates a button or a card.
It won't replace a full design system doc with rationale and usage examples. It gives the agent enough to stop guessing. Primary button color? #2563eb. Card padding? 16px. When I ask for a new settings panel, the output at least starts in the right neighborhood.
The format is plain markdown, so the file isn't locked to Stitch. Same DESIGN.md works in Claude Code, Cursor, Gemini CLI, whatever you're running this week. Your design intent lives in git, not in one vendor's canvas.
That's the part I think actually matters from the Stitch update. Not another prototyping toy. A handoff format agents can read without Figma export gymnastics. Figma is still where I'd do pixel-perfect production work. For "keep the agent from drifting," a repo-root markdown file beats a chat message I typed once in March.
VoltAgent shipped awesome-design-md with pre-built files scraped from Stripe, Vercel, Linear, Notion, Spotify. Drop one in your root and tell the agent to follow it. Cheesy? A little. Useful when you're bootstrapping and don't have a brand yet.
Google also published stitch-skills on GitHub. Tools to synthesize a .stitch/DESIGN.md from a URL and turn Stitch screens into React components. I haven't wired that into a production flow yet. The DESIGN.md export alone was enough to change how I start UI work.
You don't need Stitch installed to use the pattern. Paste this into Claude Code, Cursor, Gemini CLI, or Codex and let it interview you:
You are setting up DESIGN.md at the repository root so this project has a single source of truth for visual design.
1) Check whether DESIGN.md already exists in the repo root. If it is missing or only a stub, create or meaningfully expand it into a concrete design spec.
2) Before writing the file, if you do not yet know enough to avoid inventing a brand, ask me a small number of focused questions (aim for roughly 3–5 at most). Good topics: primary or accent brand colors, primary typeface, light vs dark default, and whether the UI should feel dense (product) or airy (marketing). If I defer to your judgment on something, pick sensible defaults and label them clearly as defaults in the file.
3) Write DESIGN.md in markdown with real values: color palette (hex), typography scale, spacing scale, radii, shadows, and any component-level rules that will keep UI consistent. Include a short "How agents should use this file" section at the top.
4) From this point forward, whenever you generate UI components, style existing elements, or write CSS/Tailwind classes, you must strictly follow the tokens and rules in DESIGN.md. Do not invent new colors or spacing values outside what is documented unless I explicitly ask you to update the design spec.
Answer the questions with whatever you already know. You don't need to draft the file by hand first. Once it exists, add a line to your CLAUDE.md or Cursor rules pointing at it. Constraints in the repo beat constraints in chat history, because chat history disappears when you start a new session.
If your agent keeps shipping pages that almost match but not quite, this is the first thing I'd try before swapping models.