Documentation
How to use DesignMD
Everything in one place — what DesignMD does, how each file works, and the exact tips that make your AI-generated UIs look great.
what is designmd?
the big pictureTurn any website into AI-ready design documentation
DesignMD reads a live website and writes out its full design system in structured files your AI coding tool can actually understand.
Input: any URL
Paste a website URL — yours, a competitor's, or a site you admire. Any public page works.
Process: AI extraction
The extractor renders the page and reads the computed CSS — colors, fonts, spacing, shadows, and component patterns.
Output: 10 files
Download a ZIP with design.md, JSON tokens, a Tailwind config, Figma tokens, and pre-written AI prompts.
Why does this matter?
When you tell an AI "make this look like Stripe", it guesses. When you give it Stripe's actual design.md, it knows — the exact blue (#2F5BEA), the font stack, the 8px border-radius, the hairline grid. The difference in output quality is enormous.
step-by-step guide
6 stepsHow to use DesignMD from start to finish
From entering a URL to having AI build pixel-perfect components — here is the complete flow.
Paste any website URL
Go to the homepage and enter any public website URL in the input box. It can be a full URL like https://stripe.com or just the domain stripe.com — both work fine.
Click Generate
Hit the Generate button. The extractor reads the rendered page — colors, fonts, spacing, components, and visual rhythm — and organises everything into a structured design system.
Preview your design.md
A live preview appears right on the page. Read through the markdown — you'll see the color palette with roles, the typography scale, and the geometry rules all laid out clearly.
Download the ZIP
Click Download ZIP and you get all ten files at once: design.md, colors.json, typography.json, spacing.json, components.md, prompts.md, figma-tokens.json, tailwind.config.ts, and more.
Drop into your AI tool
Open Claude Code, Cursor, Windsurf, or any AI coding assistant. Attach design.md (and as many of the other files as you like) to your session. Your AI now has full design context.
Build with real design DNA
Ask your AI to build components, pages, or whole features. Because it has the actual token values and design rules, it matches the source brand — not a generic approximation.
saas architecture
Firecrawl + OpenRouter Multi-AgentThe Ultra Low-Cost Design.md Pipeline
Deconstructed 5-agent architecture combining Firecrawl for LLM-ready DOM extraction and ultra-low-cost OpenRouter inference.
Multi-Agent SaaS Pipeline Overview
Firecrawl Scrape
Converts page DOM to clean Markdown, raw HTML structure, and PNG viewport screenshot.
OpenRouter Routing
Streams payloads to high-speed, cost-optimized LLM backends with automated failovers.
5-Agent Parallel Processing
Specialized sub-agents analyze tokens, components, layout, Tailwind theme, and prompt synthesis.
ZIP Export Bundle
Merges agent artifacts into design.md, tokens.json, tailwind.config.ts, prompt.md & CSS.
Cheapest OpenRouter Inference Models
Specialized Sub-Agent Distribution
Extracts primary, neutral, accent, surface hex codes & semantic roles.
Parses buttons, cards, navigation, forms, icons, and hero sections.
Analyzes modular grid systems, spacing scales, border-radii, and typography.
Generates drop-in TypeScript tailwind extension definitions.
Creates optimized system prompts for Claude Code, Cursor & Windsurf.
// 1. Scraping DOM with Firecrawl API
import FirecrawlApp from "@mendable/firecrawl-js";
const app = new FirecrawlApp({ apiKey: process.env.FIRECRAWL_API_KEY });
const scrape = await app.scrapeUrl("https://stripe.com", {
formats: ["markdown", "html", "screenshot"],
});
// 2. Sending context payload to OpenRouter
const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "deepseek/deepseek-chat-v3", // Fallback: "qwen/qwen-2.5-coder-32b-instruct"
messages: [
{ role: "system", content: "You are a Senior Product Designer. Output valid DESIGN.md markdown." },
{ role: "user", content: scrape.data.markdown }
]
})
});output files explained
8 files per exportWhat's inside your design.md ZIP
Every file is designed for a specific job. Here's what each one does and when to use it.
The master overview. Colors, fonts, spacing rules, and component notes — all in one readable file.
→Paste it at the top of any Claude Code / Cursor / Windsurf session.
Every color token with its hex value, role, and usage note.
→Import into Figma, Storybook, or any token pipeline.
Font families, sizes, weights, line-heights, and letter-spacing for every text style.
→Feed it to your AI agent to match the exact type scale.
The spacing scale — padding, margin, and gap values that make up the rhythm of the layout.
→Use as a reference when asking AI to space components correctly.
Button, card, input, badge — each documented with their exact visual rules.
→Reference in prompts: "Follow components.md for card styling".
Drop-in token file for Figma's Token Studio or Variables panel.
→Import into Figma once, then all your frames auto-update.
A ready-to-merge Tailwind config with all extracted colors, fonts, and spacing.
→Copy-paste into your project — zero manual mapping required.
Pre-written AI prompts already loaded with this site's design context.
→Copy a prompt into Claude / GPT-4o / Gemini for instant results.
tips & tricks
pro movesGet the most out of DesignMD
These are the habits that separate teams who get good AI output from teams who get great AI output.
Give the URL to your AI agent — not just the colors
The real power is context. Instead of telling your AI 'use blue', give it the full design.md file. It will understand primary vs. accent, know the exact blue (#2F5BEA vs. #E6ECFF), and apply them in the right places automatically.
Put design.md in your project root
Claude Code, Cursor, and Windsurf all read files in your repo. Drop design.md at the root (or .cursor/rules/) and every AI session in that project will have full design context — no copy-pasting required.
Run multiple domains for inspiration
Extract design.md from Stripe, Linear, and Vercel. Then tell your AI: 'Use Stripe's color palette with Linear's spacing rhythm.' This cross-pollination creates unique, polished UIs faster than designing from scratch.
Start a new chat with just one line
Open prompts.md and copy the first prompt. It already includes the site name, color roles, font choices, and spacing scale. Your AI has everything it needs in one message — no back-and-forth to clarify design intent.
Use figma-tokens.json before you code
Import figma-tokens.json into Figma Token Studio first. Design your screens with real tokens, then hand those same token names to your AI coder. The result: Figma and code share the same language — no more 'it looked different in the mockup'.
Analyse your competitor's site
Enter a competitor's URL instead of your own. You get their full design system deconstructed — color palette, type scale, spacing rhythm. Great for competitive research or for matching a client's reference without guesswork.
Ready-to-use AI prompts
Copy these into your AI tool with your design.md attached.
Build a component
Using the design system in design.md, build a pricing card component. Match the exact color tokens, border-radius, and spacing scale. Output Tailwind JSX.
Refactor existing code
Refactor the attached component to match design.md. Replace hardcoded values with the correct token names. Preserve all existing logic.
Create a landing section
Build a hero section that feels native to the brand in design.md. Use the heading font for the title, the body font for copy, and the primary accent for CTAs. Add a subtle animation.
Critique your output
Compare the attached screenshot to design.md. List every deviation: wrong colors, wrong font weights, wrong spacing. Suggest the exact fix for each issue.
integrations
works everywhereEvery AI tool and design pipeline it works with
DesignMD files are plain text — they work in any tool that accepts context files, attachments, or token imports.
Claude Code
Attach design.md to project context
Cursor
Drop files into .cursor/rules/
Windsurf
Add to Cascade memory
Devin
Attach as session file
GitHub Copilot
Use as workspace instructions
Kiro
Add to agent specs
ChatGPT
Paste file contents directly
Gemini Advanced
Attach via Google Drive or paste
Figma Token Studio
Import figma-tokens.json
Style Dictionary
Use tokens.json as source
Storybook
Wire colors.json to theme
Tailwind CSS
Copy tailwind.config.ts
your-project/
├── .cursor/
│ └── rules/
│ ├── design.md ← always-on design context
│ └── components.md ← component rules
├── src/
└── tailwind.config.ts ← replace with generated one
understanding design.md
anatomyHow to read the design.md file
The file is structured YAML-style markdown. Here's what each section means.
colors:
Lists the color palette with named roles — not just hex values. The role tells your AI exactly where a color goes: primary CTA, tint fills, text, borders. This context is what makes AI output accurate.
primary-soft: "#E6ECFF" # tints, hovers, badges
ink: "#0B0B0F" # headlines on light surfaces
typography:
Defines named text styles — display hero, body, eyebrow — with every property spelled out. Your AI knows which style to apply to a headline vs. a caption vs. a button label.
fontFamily: Satoshi
fontSize: 40px
fontWeight: 700
}
geometry:
Border-radius, border-width, and the spacing scale. The spacing scale is a sequence of values (4 · 8 · 16 · 24…) — your AI should only pick values from this sequence, which keeps layouts consistent.
border: 1px solid #E4E4E7
spacing-scale: 4·8·12·16·24·32·64
components:
Pre-defined component specs using the token names from above. AI can look up "button-primary" and know exactly which background color, text color, radius, and padding to apply.
background: #E6ECFF
color: #2F5BEA
radius: 8px
}
common mistakes
avoid theseWhat not to do — and the fix
Most people get 80% of the benefit. These are the things that unlock the other 20%.
Mistake
Paste only the colors section into your AI prompt
Fix · Impact: High
Attach the full design.md file as a project context file — your AI needs the role labels and the component specs too, not just raw hex values.
Mistake
Use the output once and throw the files away
Fix · Impact: High
Check the design.md file into your git repo (or a shared Notion). Every person on your team — and every AI session — should be reading from the same source of truth.
Mistake
Re-extract the same site every week
Fix · Impact: Medium
Production design systems don't change that often. Re-extract when you notice a rebrand or major UI update — otherwise the cached file is fine.
Mistake
Give your AI a vague reference like 'make it modern'
Fix · Impact: High
With design.md attached, be specific: 'Use the display-hero type style, the primary-soft background, and an 8px radius. Follow the spacing scale.'
Mistake
Import figma-tokens.json and then manually override values in Figma
Fix · Impact: Medium
Let the token file be the single source of truth. Change the token file first, re-import, and let Figma update. Otherwise your Figma and your code drift apart.
quick reference
cheat sheetDesignMD cheat sheet
The most important things on one screen.
- ·1. Go to the homepage
- ·2. Paste a URL → Generate
- ·3. Download ZIP
- ·4. Attach design.md to AI
- ·5. Start building
design.mdEvery AI sessionprompts.mdCopy-paste into chattailwind.config.tsDrop into repofigma-tokens.jsonImport to Figma
- →Extract competitor sites for research
- →Mix palettes from different sites
- →Keep design.md in .cursor/rules/
- →Re-extract after major rebrands
- →Use prompts.md as agent instructions
faq
6 questionsFrequently asked questions
Quick answers to the most common questions about DesignMD.
Ready?
Give your AI coding tool real design context
One URL in, ten AI-ready files out. Then hand them to Claude Code, Cursor, or your whole team.