How to use design.md

A machine-readable visual design system format that coding agents use to generate pixel-perfect UI, ships with a lint/diff/export CLI.

When you want Claude to build something that matches a site you love, you need exact values, not screenshots, not descriptions. design.md is a structured format combining YAML design tokens (colors, typography, spacing, components) with markdown design rationale. It ships a CLI with lint (validates tokens and WCAG contrast), diff (catches design regressions), export (converts to Tailwind or W3C Design Tokens), and spec commands, giving you both a machine-readable brief for your coding agent and a validation toolchain.

L2L3L4

Before you startYou'll want a working sense of [what a DESIGN.md file is](/lessons/portfolio-l2-03) before working through this guide.

Steps

Find the site you want to learn from

Pick any public website whose design you want to match. Copy its URL. A portfolio site, a SaaS product, a brand you admire. Any publicly visible site works.

Ask Claude to extract the design

Paste this into a new Claude conversation. Claude will use the design.md pipeline to analyze the site and pull out the design values. Give it a moment. This can take 30-60 seconds for complex sites.

I want to extract the design system from [YOUR_REFERENCE_URL]. Use the design.md pipeline from google-labs-code to analyze it and give me a complete DESIGN.md file with the colors, fonts, spacing values, and any component patterns you find. Format it exactly as a DESIGN.md file so I can save it and use it in my next project.

[YOUR_REFERENCE_URL]Reference site URL e.g. https://linear.app

Know what you're looking at

A well-formed DESIGN.md has four sections: Colors (hex values and semantic names), Typography (font families, sizes, and weights), Spacing (a base unit and a scale), and Components (how cards, buttons, and grids are built). Here's what a minimal one looks like. Yours will have more detail:

## Colors - Primary: #1A73E8 - Background: #FFFFFF - Surface: #F8F9FA - Text Primary: #202124 - Text Secondary: #5F6368 ## Typography - Font Family: Inter, sans-serif - Heading 1: 32px, 700 weight - Body: 16px, 400 weight - Caption: 12px, 400 weight ## Spacing - Base unit: 8px - Values in use: 4, 8, 16, 24, 32, 48px ## Components - Button border radius: 8px - Card border radius: 12px - Card shadow: 0 1px 3px rgba(0,0,0,0.12)

Save the output as DESIGN.md

When Claude finishes, it will give you a block of text. Ask Claude to save it, or copy it yourself and paste it into a new file in your project folder. The file name matters. Call it exactly DESIGN.md. AI builders like Lovable and Bolt look for that specific name.

Save that output as a file called DESIGN.md in my project folder.

Use it in your next build

Once DESIGN.md is in your project, you can reference it any time you ask Claude to build something. Claude reads the file and uses those exact values when generating code or layouts.

I have a DESIGN.md file in my project that has the design system I want to use. When you build anything for this project, use those exact colors, fonts, and spacing values from DESIGN.md.

How do you know it worked?

Claude gave you a block of text that starts with color values: things like #3a1f0d or rgba(58, 31, 13, 1).
You can see font names in the output, like Inter, Helvetica Neue, or a Google Font name.
The output is at least 20 lines long and includes more than one design category (colors, fonts, spacing, or components).

If something looks off

Claude gave me an error about the URL

Some sites block automated access. Try a different page on the same site, like the homepage instead of a subpage, or try a different reference site entirely. If a site consistently blocks the tool, a screenshot works as a fallback. Paste the screenshot into Claude and ask it to analyze the design layers it can see.

My output is missing fonts or colors

This is normal for sites that load styles dynamically. The tool captures what it can see on the initial page load. Use what you got. Partial design tokens are still useful. You can fill gaps by asking Claude: 'Based on what you extracted, what font and color values would complete this design system?'

The output looks like code and I have no idea what to do with it

Paste the whole thing into a new Claude conversation and say: 'I have a DESIGN.md file. Use these values when you build my next project.' That's all you need. Claude handles the rest.

The site I want is behind a login

design.md can only analyze publicly visible pages. For password-protected sites, take a screenshot of the design you want, paste it into Claude, and ask Claude to analyze the design layers it can see in the image. Screenshot extraction often catches spacing and typography relationships that automated tools miss.

Claude returned descriptions instead of exact values

Specificity is what makes a DESIGN.md useful. '#1A73E8' works. 'A trustworthy shade of blue' does not. The model cannot build from it. If your output has adjectives instead of hex codes or pixel measurements, push back: 'Give me the exact CSS values, not descriptions.'

The file is months old and I'm still using it

A stale DESIGN.md sends Claude the wrong brief on every build that follows. When your design direction shifts (new palette, different type scale), update the file first. One outdated token quietly misaligns everything built after it.

Skills & Commands Reference

design.md CLI commands for validating and converting your design token files.

Command / Skill	What it does	When to use it
`design.md lint`	Validate your DESIGN.md for structural correctness and WCAG contrast compliance	After generating or editing a DESIGN.md, catches broken tokens and accessibility failures before building
`design.md diff`advanced	Compare two DESIGN.md versions to detect regressions in colors, spacing, or typography	Before merging any design system update, surfaces unintended changes
`design.md export`advanced	Convert DESIGN.md tokens to Tailwind config or W3C Design Tokens format	Wiring your design system into a Tailwind project or a cross-tool token pipeline
`design.md spec`advanced	Output the format specification for inclusion in agent system prompts	When instructing a coding agent to produce valid DESIGN.md output