Create a DESIGN.md File from a Website Reference

Contents

• [1. Capture the design decisions first](#1-capture-the-design-decisions-first)
• [2. Organize the file around reusable tokens](#2-organize-the-file-around-reusable-tokens)
• [3. Turn observations into an implementation checklist](#3-turn-observations-into-an-implementation-checklist)
• [Use this in your AI agent](#use-this-in-your-ai-agent)

You can create a useful DESIGN.md file from a website reference by documenting the visible design decisions, then separating observed details from choices you still need to verify. Start with the page structure, typography, colors, spacing, borders, shadows, and repeated components rather than trying to copy every visual detail.

1. Capture the design decisions first

Begin with a short reference section: the page URL, the page or screen you reviewed, the viewport used, and the parts of the page that informed the notes. Then record the main visual rules in the order a developer will use them: canvas and layout, type, color, spacing, surfaces, controls, and responsive behavior. This makes the file useful during implementation instead of turning it into a loose collection of observations.

Use plain, testable language. For example, write “body text uses Inter at regular weight with muted gray labels” instead of “the page feels clean.” Record values only when they are visible or measured from the reference. If a detail is uncertain, mark it as a check rather than presenting an assumption as part of the design.

A practical opening might look like this:

fudge-pins { "layout": "compact-card-grid", "pins": [ { "pinId": 6434, "title": "The system for product development", "domain": "linear.app", "note": "The captured Linear page used to ground the exported theme." } ] } ```

## Direction - Dense product interface with restrained contrast - Rounded surfaces and compact controls - Hierarchy comes from type size, weight, and muted color ```

2. Organize the file around reusable tokens

The strongest DESIGN.md files turn repeated choices into a small token table. Include names that a team can reuse, such as --color-background, --color-foreground-muted, --space-4, --radius-md, and --shadow-card. Add the observed value beside each token, then explain where it appears. A token without a role is harder to apply consistently.

Typography deserves its own section. Record the family, available weights, approximate sizes, line heights, letter spacing, and the jobs each style performs. In the Linear examples below, Inter appears at regular weight for body copy, labels, navigation, and controls, while a heavier weight supports headings and emphasized interface text. Treat that as an observed reference detail, not proof that every Linear surface uses exactly the same rule.

Then document components by pattern. For a button, note height, horizontal padding, radius, text weight, fill, border, hover treatment, and disabled treatment if those states are visible. For cards, note surface color, border, radius, internal spacing, and shadow. Include a short “do not infer” list when necessary, such as unverified mobile behavior, hidden states, or values that were not available from the capture.

3. Turn observations into an implementation checklist

Before using the file, compare each note with the actual reference. Check whether the page has one type family or several, whether muted text still meets the required contrast, whether spacing repeats on a consistent scale, and whether rounded corners change between controls and larger surfaces. Check the first screen separately from lower sections because a page may use different density, imagery, or navigation treatment as visitors move through it.

A useful final section maps the notes to work:

• Build global color and type tokens.
• Add the page container and responsive layout rules.
• Implement buttons, links, inputs, cards, and navigation states.
• Match spacing and surface treatment on one representative section.
• Compare the implementation against the reference at the same viewport.
• Mark uncertain details for review rather than silently standardizing them.

Open the examples below and compare the captured Linear page before borrowing a pattern. The typography example gives you a concrete starting point for the font family and weight roles, while the page card identifies the reference itself. A design export can save time by placing supported observed details into a DESIGN.md draft, but it does not make that file an official internal design system. Keep the source, scope, confidence, and review notes in the document so future readers know what came from the reference and what your team decided.

Use this in your AI agent

> From the saved website reference, create a DESIGN.md draft for implementation. Document the page structure, viewport, typography families and weights, color roles, spacing scale, borders, radii, shadows, gradients, and repeated components. Separate directly observed details from uncertain values, include a token table with practical names and roles, and finish with an implementation checklist. Do not invent responsive states or claim this is the source site's official design system. Use the captured reference and the examples below as evidence, and cite the source URL inside the file.

Install Fudge for your AI agent

Use sections that answer the questions a developer will have while building the page:

1. Reference and scope: source URL, reviewed page, viewport, capture date if known, and what was not reviewed.
2. Design direction: a short summary of density, contrast, surface treatment, and hierarchy.
3. Layout: container width, columns, alignment, section spacing, and responsive behavior that has actually been checked.
4. Typography: font families, weights, sizes, line heights, letter spacing, and each style's role.
5. Color tokens: background, foreground, muted text, borders, accents, status colors, and contrast notes.
6. Spacing and shape: spacing steps, control heights, radii, border widths, and shadows.
7. Components: buttons, links, inputs, cards, navigation, alerts, and visible states.
8. Assets and motion: image treatment, crops, gradients, video, transitions, or overlays when observed.
9. Open questions: values or states that still need verification.
10. Implementation checklist: the order of work and the comparison pass against the reference.

Keep the file specific enough to guide implementation, but do not fill gaps with guesses. A clear “not checked” note is more useful than an invented mobile rule or hidden component state.

Copy this prompt into your AI agent when you are ready: “Create a DESIGN.md outline from my saved website reference. Include scope, layout, typography, colors, spacing, components, assets, open questions, and an implementation checklist. Separate observed details from decisions that still need verification.” Use Fudge with your AI agent

Use a short comparison pass instead of reviewing the whole file at once. First render the same page at the same viewport as the reference. Compare the container width, top navigation, first heading, primary action, and the spacing between the first major sections. These elements reveal whether the overall hierarchy is close.

Next, check repeated details: font family and weight, heading scale, muted text color, button height, corner radius, border contrast, card padding, and shadow strength. Test at least one normal state and one visible alternate state, such as a hover, selected, or disabled control. If the reference includes a mobile capture, repeat the check there rather than assuming desktop rules scale down correctly.

Record differences in three groups: intentional changes, values that need measurement, and likely implementation mistakes. Update the design notes only when the evidence changes. If a detail cannot be confirmed from the reference, leave it marked as uncertain and make the implementation decision explicit. This keeps DESIGN.md useful as a working guide without confusing a visual reference with an official design system.

Copy this prompt into your AI agent: “Compare my implementation with the saved website reference at the same viewport. Check layout, typography, color, spacing, controls, surfaces, and visible states. List intentional differences, measurements to verify, and likely implementation mistakes without inventing missing evidence.” Run the comparison with Fudge

Related questions

• Create a Design Report from a Website Reference
• Create CSS Variables from a Website Reference
• Create color and font tokens from a website reference
• Convert Website Design Details into a Tailwind v4 Theme