Generate a DESIGN.md File from a Live Website

Contents

• [Start with the right page and scope](#start-with-the-right-page-and-scope)
• [Check the details before exporting](#check-the-details-before-exporting)
• [Make the DESIGN.md file practical](#make-the-design-md-file-practical)
• [Use this in your AI agent](#use-this-in-your-ai-agent)

You can generate a useful DESIGN.md file from a live website by first capturing the page, checking its visible design details, and then exporting those observations into a structured project reference. The result should document what the site uses, not pretend to be the site's private design system.

Start with the right page and scope

Begin with the public page that best represents the design you want to reuse. A homepage is useful for overall layout, navigation, buttons, type scale, colors, and large sections. A product screen, pricing page, or documentation page may be better if your project needs a specific interface pattern. If the website changes between routes or states, capture the pages that matter instead of relying on one screen.

Write down the purpose of the file before inspecting anything. For example: "Create a DESIGN.md reference for rebuilding this marketing page in Tailwind" or "Document the visual rules used across these three product screens." This keeps the output focused. Separate global observations, such as font families and color roles, from page-specific details, such as a hero layout or a particular card arrangement.

Check the details before exporting

Review the page in groups so the document stays useful. Check the page structure and viewport first: header height, content width, section order, column behavior, alignment, and responsive clues. Then check typography: family, available weights, sizes, line heights, casing, tracking, and where each style appears. Finally check colors and component styling: background and text roles, borders, radii, shadows, gradients, buttons, cards, forms, and repeated spacing values.

Treat every value as an observation to verify. A font that appears to be Inter may be used in several weights, while a visual match can sometimes come from a nearby fallback. A pale border may be a color, an opacity treatment, or a contrast effect against its background. Record confidence or add a note where the page does not make the source clear. The examples below show a compact typography summary for a captured Linear page: Inter at 400 for body and controls, and Inter at 500 for headings and emphasized interface text. Use it as a comparison point, not as an assumption about every website.

Make the DESIGN.md file practical

A good file turns inspection into decisions another designer or developer can apply. Use sections such as Overview, Typography, Colors, Spacing, Layout, Components, Motion, Assets, and Open Questions. For each token or rule, include a name, value, role, and where it appears. For example, document a color as "muted text" rather than only listing a hex value, and describe a card by its padding, border, radius, shadow, and content relationship.

Include implementation-ready examples where they help: a Tailwind theme block, CSS custom properties, component recipes, or a small page-structure outline. Keep the source observation separate from your suggested implementation. "Observed: headings use a medium sans-serif weight" is different from "Use font-weight: 500 for all headings." This distinction prevents a generated reference from becoming an unverified internal design system.

Before saving the file, run a short quality check. Confirm that every listed font and color can be tied to an observed page element, that repeated values are grouped consistently, that responsive behavior is marked as confirmed or inferred, and that unknowns are called out. If you are working from several captures, compare them before combining the rules. A one-page export can describe a page accurately; a multi-page reference is stronger evidence for shared patterns.

Use this in your AI agent

> Inspect the captured website pages I provide and create a DESIGN.md reference for rebuilding them. Document observed page structure, viewport and layout behavior, typography families and variants, color roles, spacing, borders, radii, shadows, gradients, repeated components, imagery, motion, and responsive clues. Separate confirmed observations from inferences, include where each rule appears, and avoid inventing values that are not visible. Organize the result into Overview, Typography, Colors, Spacing, Layout, Components, Assets, and Open Questions. Add Tailwind v4 or CSS implementation suggestions only after the observed details, and clearly label those suggestions as recommendations. Compare all supplied pages before describing anything as shared. Install Fudge for your AI agent.

For one landing page, keep the file focused on choices someone can reuse. Start with a short Overview that names the page purpose, captured route, viewport, and any important state. Then document the page structure in order: navigation, hero, supporting sections, calls to action, footer, and any repeated content blocks.

The most useful sections are Typography, Colors, Layout, Components, and Open Questions. In Typography, list each observed family, weight, size, line height, casing, and usage. In Colors, use roles such as page background, primary text, muted text, border, accent, success, or warning when those roles are visible. In Layout, record content width, columns, gaps, alignment, section spacing, and responsive behavior.

For each component, describe its visual recipe rather than only its name: button height, padding, radius, border, fill, text treatment, and state differences. Add screenshots or links only if your project convention supports them. Finish with unknowns, such as unverified mobile behavior or a font whose source was not clear. That keeps the file honest and easy to update.

Copyable prompt: Document this one landing page in DESIGN.md using observed evidence only, then list open questions and use Fudge with your AI agent for the next capture.

Create the Tailwind tokens in a second pass. First preserve the observations in plain language: for example, "dark page background," "muted gray supporting text," "medium-weight sans-serif headings," or "rounded cards with a thin border." Then map those observations to token names that describe their role, such as surface, text-muted, border-subtle, accent, or radius-card.

Avoid naming tokens after the source website or a single screen unless that is intentional. Prefer a small set of repeated values over a long list of one-off measurements. If several spacing values cluster around a rhythm, propose a scale, but mark the scale as your implementation choice rather than a confirmed source rule. The same applies to responsive breakpoints and semantic color names.

A practical DESIGN.md entry can show both layers: observed value and proposed token. For example: "Observed: pale border around cards; proposed token: border-subtle, used with the card recipe." Include the page elements supporting the observation and note any places where the value changes. This gives developers a usable Tailwind theme while preserving the difference between what the page shows and what your project decides to standardize.

Copyable prompt: Convert these observed details into a small Tailwind token proposal, label every recommendation, and use Fudge with your AI agent to compare additional pages.

Related questions

• Generate a design report from a live website
• Generate CSS Variables From a Live Website
• Generate color and font tokens from a live website
• Export a Website Design System as a Tailwind v4 Theme