A DESIGN.md generator that builds the file from your CSS or Tailwind tokens, has your AI write the words, and checks it the way Google's own linter does.
Start from your CSS variables, a Tailwind config or a list of colors, then fill in the rest. The file, its checks and a preview update as you type.
Start from your tokens
Colors
Text styles
Corners and spacing
Corners
Spacing
Components
Give each state its own component with a related name, like button-primary-hover. That's how the format describes states.
The words
More sections
The format has 8 sections, and you can add more: the spec says tools keep a section they don't know. Extra ones go after Do's and Don'ts.
Preview
Paste a DESIGN.md, or load navid.me's, to see its checks and preview.
Checks
Your checks show up here as you build.
Your DESIGN.md
0 KB--- version: alpha name: "" ---
Save it as DESIGN.md in your project's root, next to your CLAUDE.md or AGENTS.md. It's built in your browser, and nothing you type is sent anywhere.
This free DESIGN.md generator builds a DESIGN.md from your CSS variables, a Tailwind config or a list of colors. Name your tokens, add your components, write a line or 2 for each section, and download a file your AI can read.
It also checks any DESIGN.md the way Google's own linter does, with the same rules, plus a few more. And it draws your colors, type and components as you go, so you see what the agent will see.
Here's what DESIGN.md is, what goes in it, how to get Claude Code, Cursor and Codex to use it, and what 5 real ones do, from navid.me to Clerk, Mintlify and Vercel.
What is a DESIGN.md file?
DESIGN.md is a plain-text file that tells an AI agent what your product looks like. The exact colors, type, corners and spacing sit in a YAML block at the top, and the reasons follow in markdown.
It began in Google's design tool Stitch. Google open-sourced the draft spec on April 21, 2026 (Google's post), and it lives at github.com/google-labs-code/design.md.
Without one, an agent guesses. You get a new blue on every screen and a new corner on every card. With one, it builds with your values, because the spec makes the tokens the rules and the words the reasons.
What goes in a DESIGN.md, section by section
The spec sets 8 sections, in this order. Leave out any you have nothing to say about, but never move one.
| Section | Also called | What it says | A real example |
|---|---|---|---|
| Overview | Brand & Style | The look and feel, who it's for, and the mood | Clerk: "give developers something they can drop in and ship, then get out of the way" |
| Colors | The palette, and what each color is for | Corey Haines: Brand Gray #4d4d4d for headings, icons and primary text | |
| Typography | The fonts, and when to use each text style | Clerk: Suisse Intl for copy and headings, Geist only for tabular numbers | |
| Layout | Layout & Spacing | The grid, the widths and the spacing | navid.me: a 1,152px max width and 20px gaps |
| Elevation & Depth | Elevation | Shadows, and what sits on top of what | Clerk: layered shadows, never a single flat one |
| Shapes | Corners, borders and shapes | Clerk: 6px for buttons, 16px for bento cards, fully round for pills | |
| Components | How buttons, cards and inputs look | Mintlify: a switch with hover, disabled and focus states, all from tokens | |
| Do's and Don'ts | Rules to follow and mistakes to avoid | Clerk: keep purple for calls to action, never for body text |
Each section is a ## heading, spelled exactly as the spec spells it. ## 04. Colors or ## Color isn't the Colors section to an agent reading by the spec.
The tokens block
The tokens go at the very top, between 2 lines of 3 dashes. There are 5 groups: colors, typography, rounded (corners), spacing and components.
The block is optional: a file of words alone is valid. But the tokens are what give an agent exact values instead of descriptions, and a check can only test what's in them.
A small DESIGN.md, from navid.me's own tokens---
version: alpha
name: navid.me
colors:
primary: "#0B81F7"
status-done: "#2C7049"
status-done-bg: "#E4F0E8"
typography:
display:
fontFamily: Inter
fontSize: 42px
fontWeight: 700
body:
fontFamily: Inter
fontSize: 18px
fontWeight: 400
lineHeight: 29px
rounded:
full: 9999px
spacing:
gap: 20px
components:
status-chip-done:
backgroundColor: "{colors.status-done-bg}"
textColor: "{colors.status-done}"
rounded: "{rounded.full}"
height: 24px
padding: 0 10px
---
## Overview
The complete design language for navid.me: logos, photos, bios, colors, gradients, type, spacing, surfaces, icons and motion.
A few rules trip people up:
- A size needs its unit:
44px,1.5remor-0.02em, never a bare44 - A token can point at another with
{colors.status-done}, so a component uses your palette instead of new values - Name your main color
primary, or the agent picks your key colors itself - A color can hold a light and a dark value, like
ink: { light: "#1a1a2e", dark: "#e8e8ec" }. Google's checker reads that as 2 colors,ink.lightandink.dark - A component takes 8 properties: backgroundColor, textColor, typography, rounded, padding, size, height and width
What the best DESIGN.md files add
The spec's minimum gives an agent the right values. The files that get the best UI out of an agent add 5 things on top:
- What each token is for. A value says what, a note says when:
primary(#0B81F7) is for links, buttons and focus rings. The generator writes each note next to its token - States as components. The spec describes a hover or pressed state as its own component with a related name, like
button-primary-hover - Sections beyond the 8. The spec says a tool reading DESIGN.md keeps a section it doesn't know, and gives
## Iconographyas its example. Add Responsive Behavior, Logo, Imagery, Motion or Voice - A guide for the agent. An Iteration Guide tells it how to work with the file: 1 component at a time, tokens by name, a check after every change
- Known gaps. Say what the file doesn't cover yet, so the agent asks instead of guessing
The generator suggests each of these as you build, and your AI can write the words from your tokens.
How to make your DESIGN.md
The generator reads CSS variables, Tailwind v3 configs and v4 @theme blocks, design tokens JSON and plain lists of colors. A variable set again under a dark theme comes back as a second color ending in -dark, since the format has no themes.
You can also download your tokens as a Tailwind v4 theme.css or a design tokens JSON file.
How to check a DESIGN.md
Open the Check a file tab and paste any DESIGN.md. You get every problem with where it is, and a preview of its tokens.
| Check | Why it matters |
|---|---|
| A reference to a token that isn't there | The agent gets nothing where a color should be |
| Text on its background under 4.5:1 | It fails WCAG AA, the bar for readable text |
| No primary color | The agent picks your key colors itself |
| A size without px, em or rem | It isn't a valid size, so an agent can't use it |
| A component property the format doesn't have | An agent reading by the spec skips it |
| Sections out of order, or 1 twice | The spec fixes the order, and says to reject a file with a section twice |
| A heading like 04. Colors instead of Colors | An agent reading by the spec won't take it for that section |
| A color no component uses | Often a leftover, or a component you haven't written down |
| No YAML block | Valid, but the agent gets descriptions instead of exact values |
The rules Google's linter has use Google's names and conditions. I test them against Google's linter on the same files, and they agree on every finding but 1.
Google judges contrast on a see-through color as if it were solid, so white glass at 6% counts as white. The generator doesn't judge a see-through pair, since its contrast depends on what's under it.
Contrast follows WCAG 2.2: 4.5:1 for normal text and 3:1 for large text (W3C). The ratio is never rounded, so 4.499:1 fails.
How to get Claude Code, Cursor and Codex to use it
None of them load a DESIGN.md on their own. Each has its own way in:
| Tool | How |
|---|---|
| Claude Code | Add @DESIGN.md on its own line in your CLAUDE.md, and Claude Code imports it at launch (docs) |
| Cursor | Mention @DESIGN.md in a rule in .cursor/rules, or in AGENTS.md, which Cursor reads (docs) |
| Codex | Add a line to AGENTS.md telling it to follow DESIGN.md for any UI work. Codex has no import, and reads up to 32 KiB of AGENTS.md by default (docs) |
| Stitch | Import it into a project, or export one from it. DESIGN.md began there |
Then ask for UI the way you always do. The agent builds with your tokens instead of guessing.
DESIGN.md in your AI OS
An AI OS is the layer underneath your AI tools. It connects AI to your context, your data and your tools, so every agent you use starts out knowing your business instead of starting from zero. It's platform agnostic, and it runs wherever suits you: your computer, an always-on server or the cloud.
DESIGN.md is part of your context, next to who you are, your company and your voice. In the AI OS I build and teach, it sits in the context folder, and the rules file tells every agent to read that folder at the start of every session.
The same rules file serves Claude Code, Codex, Cursor and Gemini CLI. So you set it up once, and every agent builds in your brand:
- Save the file as design.md in your AI OS's context folder, or as DESIGN.md in a project's root, and point the project's rules file at it
- Ask for UI the way you always do. The agent reads your tokens before it builds
- When a color or a font changes, change your tokens, make the file again and replace the old one
- Point every new project at the same file, so a landing page, an app and a slide deck share 1 look
Other tools can read it too. My post image generator takes its colors: paste your DESIGN.md under My brand, and your post images match your site.
Learn to build your own AI OS at AI OS Lab.
Real DESIGN.md files from real companies
You don't have to guess what a good one looks like. These sites publish theirs at /design.md on their own domains:
| File | What to learn from it |
|---|---|
| navid.me/design.md | Built from the brand page on every request, with YAML tokens and 16 sections |
| clerk.com/design.md | Written "for humans and AI agents", with a voice section: avoid "powerful", "robust" and "seamless" |
| mintlify.com/design.md | A light and a dark value for most colors, and 1 rule up top: "Reference tokens, never raw literals" |
| vercel.com/design.md | Written as instructions for an agent, with a list of generated-design habits to reject, from cards nested in cards to em dashes |
| corey.co/design.md | Corey Haines' brand, with a live version at corey.co/brand and principles like "Color is a reward, not a default" |
Only navid.me and Mintlify carry YAML tokens. The others are words an agent reads, which the spec allows. Paste any of them into the Check a file tab to see how it reads.
The best ideas travel. Corey Haines gives the logo clear space equal to the height of the "C" and a 24px minimum. Clerk swaps outer shadows for inset borders in dark mode. Mintlify keeps UI transitions between 150 and 250ms and turns every animation off for people who ask for reduced motion.
navid.me/design.md, walked through
navid.me publishes its own at navid.me/design.md. It's built from my brand page on every request, so it can't fall out of step with the site.
It's about 100 KB: 52 colors in dark and light pairs, 9 text styles, 5 corner sizes, 8 spacing tokens and 8 components. After the tokens come 16 sections that follow the brand page, from Foundations to Design tokens, then the Do's and Don'ts.
When I built this tool, its checks found 9 errors in my own file: font sizes written with no unit. They also flagged 7 component properties the format doesn't have, and no primary color. All fixed now.
Press Load navid.me's DESIGN.md in either tab. Build turns it into rows you can edit and keeps every section where it stands, and Check a file shows what the checks say about it.
How to keep it in step with your site
A DESIGN.md goes stale the day you change a color by hand in 1 place and not the other. The fix is 1 source.
- Keep your tokens in 1 file, like your CSS variables, and make the DESIGN.md from it
- When a token changes, paste the file into the generator again, or rebuild it the way navid.me does
- Check it after every change, here or with Google's CLI:
npx @google/design.md lint DESIGN.md - Compare 2 versions with
npx @google/design.md diff DESIGN.md DESIGN-v2.md
DESIGN.md Generator FAQs
Questions about DESIGN.md? Here's what to know.
A DESIGN.md file is a plain-text description of a design system for AI agents: exact colors, type, corners and spacing in a YAML block, then the reasons in markdown. The format is open, from Google Labs (spec).
Clerk, Mintlify and Vercel publish a DESIGN.md at /design.md on their own sites, and so do navid.me and Corey Haines' corey.co. Clerk's says it's written for humans and AI agents.
A brand guide is written for people, while a DESIGN.md is written for an AI agent, with exact values it can use in code. You can make one from the other, the way navid.me/design.md is built from navid.me's brand page.
Put DESIGN.md in the root of your project, next to your CLAUDE.md or AGENTS.md, then point your agent at it.
No, Claude Code doesn't read DESIGN.md on its own. Add `@DESIGN.md` to your CLAUDE.md and Claude Code imports it at launch (Anthropic's docs).
No, neither reads DESIGN.md on its own. In Cursor, mention `@DESIGN.md` in a rule or in AGENTS.md; in Codex, add a line to AGENTS.md telling it to follow DESIGN.md for UI work.
In an AI OS, DESIGN.md is part of your context, next to who you are, your company and your voice, so every agent reads it at the start of every session. Learn how to build one at AI OS Lab.
Yes, you can add your own sections to DESIGN.md: the spec says a tool keeps a section it doesn't know, like `## Iconography`, instead of rejecting the file. Keep the 8 standard sections spelled exactly as the spec spells them.
Describe each state in DESIGN.md as its own component with a related name, like `button-primary-hover` or `button-primary-pressed`, the way the spec shows.
Yes, paste your site's CSS variables or Tailwind config into the generator and it fills in the colors, type, corners and spacing. It doesn't read a site from its address, so copy the variables from your CSS file.
Yes, AI can write the words in your DESIGN.md: build the tokens here, then press Claude, ChatGPT or another app under the file, and it opens with your file and the ask filled in. Keep the tokens yours, so the AI never makes up your colors.
Yes, DESIGN.md works with Tailwind: import a Tailwind config to start, and download your tokens as a Tailwind v4 theme.css.
Normal text needs at least 4.5:1 against its background, and large text 3:1, to meet WCAG AA (W3C). The ratio isn't rounded, so 4.499:1 fails.
No, nothing you type is uploaded: the generator runs in your browser, and your draft is saved in this browser only. When you press an AI app, your file goes to that app in your own account.
No, the YAML block is optional: a DESIGN.md of words alone is valid. The tokens in it are what give an agent exact values, so add them when you can.
The llms.txt generator gives AI a map of your site, and the schema markup generator tells search engines and AI what each page is. See all my free tools.
Navid Moazzez
AI business strategist & AI OS builder
Navid Moazzez helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life.
Navid.me is reader-supported. When you buy through links on this site, I may earn an affiliate commission. Learn more.
More free tools
Bluesky
Apple Books
Amazon
Free AI newsletterThe most actionable AI newsletter for founders
Every week, get proven AI strategies, curated tools, and step-by-step systems to grow your audience, create better content, and build a profitable creator business.
No fluff, no filler, no BS. Just five minutes each week that might level up your online business and life.
P.S. Sign up now to get free access to my ultimate AI tools guide for creators.
