Workflow

How to create a DESIGN.md from a website

Turn an existing product surface into a reusable AI-readable design brief.

May 1, 20267 min read

Audit first

Creating a DESIGN.md from an existing website starts with a systematic visual audit before writing a single line of the file. The goal of the audit is to extract the implicit design rules that are already being applied consistently across the product, even if they were never explicitly documented. Start by capturing full-page screenshots of the four to six most representative pages: the homepage or landing, the main authenticated surface such as a dashboard or feed, a settings or account management page, a detail or profile page, and a typical form or onboarding flow. Open the browser inspector alongside each page and record: the primary font family, base font size, heading sizes, body line height, link color, primary action color, background colors, border colors, shadow usage, border radius values, and spacing between the most repeated elements. This raw data is the foundation from which the spec will be built.

Extracting typography and color

Typography and color are the two systems that most reliably reveal a product's visual identity. For typography, use the browser inspector's computed styles panel to find the font properties for body text, h1 through h4, navigation labels, table headers, and captions. Record font family, font weight, font size, line height, and letter spacing for each text role. Look for patterns: are all headings the same family? Is there a consistent weight for interactive labels versus display headings? Note any inconsistencies — a page where a heading is 22px instead of the usual 24px — because those reveal places where the design system was applied unevenly and are candidates for normalization in DESIGN.md. For color, extract the hex or HSL values for the primary action color, the neutral background, the card background, the text on each background, and any semantic colors for success, danger, and warning states. Use computed styles, not visual estimation — exact values are what make the spec useful to an AI agent.

Documenting spacing and layout

Spacing and layout are harder to extract than typography and color because they are often not named values. The approach is to measure consistent patterns rather than trying to infer a system from inconsistent data. Take a card component and measure: the padding inside the card, the gap between the card title and body, the gap between the card and the next element below it. Take a form and measure: the gap between label and input, the gap between input and validation message, the gap between form sections. Take a page layout and measure: the maximum content width, the left and right page padding at desktop width, the gap between the navigation area and the content area. Repeat this for three to five components and pages. Look for values that appear repeatedly — 16px, 24px, 32px, 48px are common anchor points. When a consistent scale emerges, document it in DESIGN.md as the spacing system, not as a list of measurements from individual pages.

Structure the file

Translate the audit findings into DESIGN.md sections in a consistent order: product feel, colors, typography, spacing, components, layouts, and anti-patterns. The product feel section comes from your overall impression of the site — not the marketing copy, but the actual UI: is it dense or airy, formal or casual, data-heavy or narrative, brand-expressive or tool-focused? Write two to four sentences that capture this character. Then write the token sections using the extracted values. For components, describe the most common patterns using the measured values: "Cards use 16px internal padding, 8px border radius, a 1px neutral-200 border, and no shadow." For layouts, describe how the page is structured at desktop width and how it adapts at mobile. For anti-patterns, document every visual decision from the audit that felt inconsistent, generic, or unintentional — these are patterns to explicitly prohibit in future AI-generated work.

Anti-patterns from observation

The anti-patterns section of a DESIGN.md built from a real website is often the most valuable part because it comes from actual product experience rather than from a theoretical spec. During the audit, note every place where a generic AI agent would likely make the wrong choice: surfaces where a gradient would be added but the product never uses gradients, screens where the default density would be too loose or too tight, page types where an agent might apply a marketing layout instead of an operational one. Also note any visual inconsistencies found during the audit — places where the existing product already deviates from its own apparent design system. These are candidates for the anti-patterns section too, marked as "do not repeat this pattern even though it appears in legacy pages." Anti-patterns written from observation are more effective than speculative ones because they target mistakes that have actually happened rather than mistakes that might theoretically occur.

Validate with an agent

After writing the file, the validation step is essential and often skipped. Give the DESIGN.md to Cursor or Claude Code and ask it to generate a page from scratch using only the file as guidance — no screenshots, no references to existing pages, no additional instructions beyond the task. Compare the generated page against a real page from the product. Where they match, the relevant rules are effective. Where they diverge, identify whether the gap is a missing rule, an unclear rule, or an ambiguous rule that the agent interpreted differently than intended. For missing rules, add them. For unclear rules, rewrite them with more specific values. For ambiguous rules, choose the correct interpretation and make it explicit. Run the validation two to three times after major updates to the file. When generated output consistently matches the real product across multiple page types, the DESIGN.md is ready to serve as the primary visual reference for AI-assisted development work.

Use DESIGN.md with a real product reference

Browse curated DESIGN.md examples from product teams, design systems, developer tools, SaaS dashboards, and AI-native apps. Use them as references before your agent builds the next screen.

Browse directory Submit DESIGN.md

Related guides

Workflow7 min read