DESIGN.md: Markdown Rules for Branded AI UIs

Better Stack2026-05-07go watch the original →

the gist

Google's DESIGN.md is a repo-resident markdown file with tokens (hex colors, fonts, spacing) and intent guidelines that AI tools like Cursor, v0, and Stitch use to output consistent, non-generic UIs from identical prompts.

The Breakthrough

Google's DESIGN.md defines a markdown format that combines structured design tokens with explanatory guidelines, enabling AI agents to produce clean, consistent, on-brand interfaces without repetitive prompting.

What Actually Worked

AI tools read DESIGN.md from the repo for hard rules like exact hex colors, font families, border radius values, and spacing scales.
Markdown sections describe intent behind rules, such as 'this blue is the primary accent and it should feel clear and trustworthy,' covering color palette, typography, components, layouts, and accessibility.
Same prompt ('Build a modern dashboard') in v0 without DESIGN.md yields generic Tailwind-style cards and buttons; adding Stripe DESIGN.md produces matching colors, cleaner spacing, and cohesive buttons.
DESIGN.md works across Cursor, Claude Code, v0, and Stitch; start with templates from community repo for brands like Stripe, Linear, Notion, Vercel.
File lives version-controlled next to code, human-readable yet agent-native, replacing per-prompt instructions like 'make it clean, modern, better spacing.'

Context

AI coding tools generate functional apps quickly, but UIs remain generic, inconsistent, and off-brand due to lack of design context. DESIGN.md solves this by embedding a full design system in markdown, outperforming Figma (human-only, external), JSON tokens (no intent), and agent rules (not design-focused). Developers adopt it for prototypes and AI-heavy workflows to reduce rework on buttons, spacing, and identity. Pros include zero setup, cross-tool compatibility, and accessibility notes; cons limit to input quality.

Notable Quotes

'Without DesignMD the AI is guessing. What should the site look like? With DesignMD the AI has rules based on other proven platforms that already look really good.'
'Your goal is not to make the AI creative. Your goal is to stop making it guess because once the rules are clear the UI is going to get more consistent and your app starts to feel less like an AI demo and more like a real product.'

Content References

Community shares DESIGN.md files for Stripe, Linear, Notion, Vercel. Google released DESIGN.md on April 21st; repo hit 70,000+ GitHub stars in weeks.