How to use design.md (spec-first)

Write a design.md from scratch when you have a vision but no reference URL to extract from.

Extraction tools work when you have a site to learn from. But sometimes the aesthetic is in your head, a mood, a set of words, a feeling you can't yet point to. The spec-first approach lets you describe what you want in plain language and have Claude write the DESIGN.md for you, then use that file to generate UI directly.

L3L4

Before you startYou'll want a working sense of [what a DESIGN.md file contains](/lessons/portfolio-l2-03) before writing one from scratch. Extraction first, spec later.

Steps

Describe the aesthetic in plain language before opening Claude

Write 3–5 sentences about how you want your project to feel. Name references if you have them, but also describe the feeling: 'editorial, like a film still, lots of breathing room' or 'energetic and graphic, high contrast, like a concert poster.' The more specific the description, the more precise the spec.

Ask Claude to write your DESIGN.md

Paste the prompt below with your description filled in. Claude will produce a complete DESIGN.md with color tokens, type scale, spacing values, and component patterns, structured to paste directly into Lovable, Bolt, or a Claude Code session.

I want to build [PROJECT_TYPE] with this aesthetic: [YOUR_AESTHETIC_DESCRIPTION] Write me a complete DESIGN.md file I can paste directly into Lovable or Bolt as my first prompt. Use the google-labs-code/design.md format: a Colors section with CSS custom properties, a Typography section with font names and size scale, a Spacing section with a base unit and scale, and a Components section describing card and button patterns. Use real CSS values, not placeholders. Favor open-source or Google Fonts choices for typography.

[PROJECT_TYPE]What you're building e.g. portfolio site for a video editor

[YOUR_AESTHETIC_DESCRIPTION]How you want it to feel (3–5 sentences) e.g. Editorial and cinematic. Lots of breathing room between sections. Dark background, near-black, slightly warm. One accent color used sparingly: a muted amber or burnt sienna. Type-forward layout with very large headlines and small body text.

Validate the spec before building

Read the generated DESIGN.md out loud, or ask Claude to narrate it back as a visual description. If it doesn't match your intent, tell Claude what to adjust: 'make the spacing tighter' or 'the accent should be cooler, more blue-tinted.' Iterating on a spec takes seconds; iterating on built UI takes much longer.

Paste the spec into your builder as the first message

Copy the full DESIGN.md and paste it as the first message in a new Lovable, Bolt, or Claude Code session. Follow immediately with your build request. You are no longer describing style in natural language. You are handing the builder exact CSS values.

How do you know it worked?

Your DESIGN.md has real CSS values, hex codes, rem values, font names, not placeholder text
The file has all four sections: Colors, Typography, Spacing, Components
You can paste it as a first prompt in Lovable or Bolt and the output looks close to your description
You can revise one section and re-run without rewriting the whole file

If something looks off

Vague descriptions produce vague specs

'Clean and modern' is not a description. Every designer thinks their work is clean and modern. Name a reference, a material, a time period, a feeling. 'Like a Japanese film poster from the 1980s' gives Claude something to calibrate against.

Placeholder values in the output

If Claude writes '#YOUR_COLOR_HERE' or '[font name]', ask it to make a specific choice. The file is only useful when it contains real values you could paste directly into CSS.

Spec-first does not mean reference-free

You can still name references in your prompt, 'inspired by Stripe but warmer, with editorial typography.' You are writing the spec yourself rather than extracting it, but references still help Claude calibrate the output.