Convert a Website into a DESIGN.md File for AI Coding Agents

Contents

• [Choose what the file should contain](#choose-what-the-file-should-contain)
• [Use a repeatable conversion method](#use-a-repeatable-conversion-method)
• [Example structure and practical checks](#example-structure-and-practical-checks)
• [Use this in your AI agent](#use-this-in-your-ai-agent)

A website-to-DESIGN.md converter turns an observed page into a written design brief that an AI coding agent can use while building a project. The most useful file captures the page's visual rules, not just a screenshot: fonts, weights, colors, spacing, layout patterns, borders, shadows, and guidance for applying them.

Choose what the file should contain

Start with the parts an agent needs to make consistent implementation decisions. Record the page structure first: the main sections, navigation, hero treatment, content widths, card arrangements, buttons, and responsive patterns that are visible. Then describe the visual system behind those parts, including type families, font sizes, weights, line heights, color roles, spacing rhythm, radii, borders, shadows, and gradients.

A useful DESIGN.md file separates observations from recommendations. For example, write "The body uses Inter at regular weight with muted gray text" as an observation, then add "Use the regular face for body copy and reserve the heavier weight for headings" as an implementation rule. This gives an AI agent enough direction without pretending that an observed page is the official internal design system.

Use a repeatable conversion method

1. Capture or provide the public page you want to study.
2. Check the page structure and identify its repeated components.
3. Inspect typography, including family, available files, variants, sizes, weights, and line heights.
4. Record color roles and contrast: background, foreground, muted text, accent, borders, success or warning colors, and prominent gradients.
5. Add layout details such as content width, alignment, gaps, padding, card radius, shadow strength, and mobile changes.
6. Turn the findings into DESIGN.md sections for principles, tokens, components, page structure, and build guidance.

Keep the final file concrete. Instead of saying "make it modern," say "use a compact sans-serif hierarchy, keep secondary text muted, use size and weight to create contrast, and repeat the same corner radius on cards and controls." Include a short verification checklist so the agent can compare its result against the reference: heading scale, page width, navigation spacing, button treatment, text contrast, card rhythm, and responsive behavior.

Example structure and practical checks

A dependable DESIGN.md outline is:

• Reference and scope: page URL or capture, viewport, and which state was reviewed.
• Visual direction: a short summary of the page's observable character.
• Typography: families, weights, sizes, line heights, casing, and usage by element.
• Color and contrast: named roles with values where available and notes about priority.
• Layout: container width, columns, alignment, spacing, padding, and breakpoints to verify.
• Components: navigation, headings, buttons, cards, forms, tables, and repeated states.
• Build rules: decisions the coding agent should follow and decisions it should avoid inventing.
• Review checklist: concrete comparisons for the finished implementation.

Open the examples below and compare the first screen before borrowing a pattern. The captured Linear reference is paired with typography notes showing Inter at regular weight for body copy, labels, navigation, and controls, with a heavier weight for headings and emphasized interface text. That is a useful example of translating a visible pattern into an agent-ready rule rather than merely naming a font.

Before handing the file to an AI coding agent, check that every important statement can be traced to something visible in the page or clearly marked as a recommendation. Verify that font files and variants are actually available to the project, that color values are not confused with semantic roles, and that responsive behavior is labeled as observed or still needing review. A DESIGN.md file should speed up implementation while leaving room for the agent to ask when the reference does not reveal an answer.

Use this in your AI agent

> Inspect the captured website reference and create a DESIGN.md file for this project. Document the observed page structure, typography families and weights, color roles and contrast, spacing, borders, radii, shadows, gradients, component patterns, and responsive behavior. Separate observed details from recommendations, avoid inventing hidden design-system rules, and finish with a practical checklist for comparing the implementation against the reference. Use the Linear typography example below as a pattern for describing font usage, not as a universal default. Install Fudge for your AI agent.

Use sections that answer the decisions an agent must make while it builds the page:

1. Reference and scope: identify the page or capture, viewport, visible state, and any parts that were not reviewed.
2. Design direction: summarize the observable visual character in a few precise sentences.
3. Typography: list font families, files, variants, weights, sizes, line heights, casing, and where each style appears.
4. Colors: define roles such as page background, surface, text, muted text, accent, border, and status colors. Include contrast notes when they were checked.
5. Layout: describe the content width, columns, alignment, spacing rhythm, padding, section heights, and responsive changes.
6. Components: document repeated patterns for navigation, buttons, cards, inputs, badges, tables, and states.
7. Implementation rules: tell the agent what to reuse, what to keep consistent, and what not to invent.
8. Review checklist: provide visual checks for type scale, spacing, alignment, contrast, component states, and mobile layout.

For each item, separate what is visible from what is recommended. That distinction prevents the file from sounding more authoritative than the evidence supports. A short note such as "observed at the supplied viewport" is useful when a behavior may change at other sizes.

> Ask Fudge to turn this captured reference into the outline above, with observations and recommendations clearly separated: Use Fudge with your AI agent.

Make each instruction actionable and easy to verify. Replace broad language such as "use a clean layout" with rules like "keep the content in a centered container, use the same surface treatment for repeated cards, and reserve the stronger text weight for headings and key controls." Agents work better when the file states priorities and gives examples.

Add a decision order. For instance: preserve page structure first, then match typography hierarchy, then match color roles, then tune spacing and decoration. This helps the agent avoid spending time on shadows while the content width or heading scale is still wrong.

Include values when they are known, but label estimates and observations clearly. Record font files and supported variants so the agent does not request a family that the project cannot load. Describe responsive behavior separately from desktop observations, and mark any breakpoint that still needs testing.

Finish with a visual review checklist and a list of open questions. The checklist might ask whether navigation height, heading weight, body text contrast, card spacing, button radius, and mobile stacking match the reference. Open questions can cover states the capture did not show, such as hover, error, loading, or empty states. This keeps the agent focused while making uncertainty visible.

> Have Fudge review the finished implementation against the captured page and return a prioritized checklist of mismatches: Use Fudge with your AI agent.

Related questions

• Website to Design Report Converter for AI Coding Agents
• Website to CSS Variables Converter for AI Coding Agents
• Convert Website Design Details to CSS Custom Properties
• Convert a Website into a Reusable Design Reference File for AI Coding Agents