# Choose the right AI design reference

> Choose between screenshots, HTML and DESIGN.md when rebuilding a website with AI. Learn what each reference reveals and how to combine them.

Canonical page: https://sitepeel.dev/guides/screenshot-html-design-md-for-ai/

Use a screenshot for appearance, HTML for structure and DESIGN.md for recurring design decisions. Combine them when fidelity matters, and describe behavior separately.

## A screenshot shows one rendered state

A screenshot makes relationships visible: the proportions of a hero, the density of a table or the space around a heading. It is a useful visual target, especially when the agent cannot open the reference page. Include the viewport dimensions and enough surrounding context to show how the section fits into the layout.

It cannot reveal every rule that produced those pixels. The image alone does not tell you whether a column has a fixed width, which font file loaded, or what happens when a menu opens. A desktop screenshot also leaves mobile behavior unresolved. Supply another view or a written requirement instead of expecting the missing state to be recovered exactly.

## HTML adds structure, with important context to review

An HTML and CSS reference can make the section hierarchy, content order and styling more explicit. If you have access to the original source project, use the relevant components directly. When you have a rendered page export, label it as a snapshot so the agent does not mistake it for the original application architecture.

Remove unrelated sections before using a large export as context. Explain which piece is useful and which parts should be rebuilt. Check asset URLs and dependencies. The reference may point to remote images, include page-specific styles or capture a single viewport. More bytes do not automatically provide a clearer implementation brief.

## DESIGN.md explains what should stay consistent

A design reference is useful when the new page should share a visual language without repeating the same composition. Record text hierarchy, color roles, spacing relationships and recurring component choices. Add reasons where they affect implementation, such as why a reading column stays narrow or why a destructive action receives a quieter default presentation.

Sitepeel can help collect a page export, a screenshot and Design MD from a site you are studying. Review those outputs and select the relevant material. A generated reference still needs your product’s content, intended behavior and decisions about which parts of the inspiration should change.

- Reproduce a specific section: provide a screenshot and a focused HTML reference.
- Create another page in an existing product: provide shared components and DESIGN.md.
- Explore a new direction: provide references with a written explanation of each.
- Implement interaction: provide its trigger, states and expected outcome.

## Send a small reference package with a clear task

Name the files and explain their roles. Avoid an unexplained folder containing several exports and dozens of images. Tell the agent which file is the visual target, which contains reusable rules and which is only a structural starting point. Supply the real copy early because text length changes layout.

The example below asks for one component and explicitly identifies the information that a screenshot does not contain. Adapt the widths and behavior to your product. Keeping the first task small makes it easier to distinguish a bad interpretation from an incomplete input.

Example: reference-handoff.md

```
# Reference package

reference-desktop.png: appearance at a 1440px viewport
reference-mobile.png: intended content order at 390px
section.html: rendered structure, not original app source
DESIGN.md: approved design values and component rules

Task: rebuild the featured section in this project.
Reuse our existing components and use the supplied copy.
The primary button opens our existing contact form.
Do not infer application behavior from the screenshot.

Render both widths and compare hierarchy, wrapping and spacing.
List missing inputs instead of inventing their contents.
```

## Compare the rendered result under the same conditions

Use the same viewport, zoom, content and loaded font when comparing the output. If the reference includes an open menu, compare that state too. A screenshot comparison is hard to interpret when one page contains shorter copy or has not finished loading its images.

Fix the largest difference first, then check the real interaction. Record the approved result in your components and design reference so later pages can reuse it. Screenshot-to-code is a useful starting workflow, but the finished page still needs a browser review and clear behavior.

## Further reading

- [Reddit: choosing a website reference workflow for AI](https://www.reddit.com/r/ClaudeDesign/comments/1w2derz/best_way_to_use_a_website_as_a_design_reference/)
- [Reddit: problems capturing a site during a rebuild](https://www.reddit.com/r/ClaudeCode/comments/1shqx6w/cloning_websites_best_practices/)
- [Playwright: page and element screenshots](https://playwright.dev/docs/screenshots)

## Related pages

- [Website prompt generator](https://sitepeel.dev/website-prompt-generator/index.md): Turn an existing website into a structured design prompt. Capture layout, typography and visual details for an AI website project with Sitepeel.
- [Use Design MD with AI](https://sitepeel.dev/guides/use-design-md-with-ai/index.md): Give an AI coding assistant a clear design reference. Learn how to hand off Design MD, write a focused task and review the resulting interface.
- [Fix a generic AI website](https://sitepeel.dev/guides/fix-generic-ai-website-design/index.md): Make an AI-generated website feel specific to your product. Fix the content, hierarchy, visual references and review process with a practical design brief.