CLAUDE.md for Website Design Recreation

A CLAUDE.md for a website design recreation project tells Claude Code which reference materials are authorized, what the responsive behavior should be, where the assets live, and how to confirm the output matches the source. Without those constraints, an assistant will make decisions about layout, typography, and breakpoints based on its own judgment — which may produce something functional but different from what was intended.

Tools like fenbs are useful for tracking the design decisions that emerge during the project: which revision was approved, which element was intentionally changed from the original, which constraints were recorded by the client. Your CLAUDE.md stays focused on the technical setup; fenbs holds the decisions and revision history that explain why the output looks the way it does.

What belongs in a CLAUDE.md for design recreation

Design recreation projects are different from greenfield builds because the reference exists and the goal is fidelity. The most important thing to communicate to Claude Code is what it is allowed to use as reference, and what counts as a successful match. A precise brief prevents both over-interpretation (changing things the original had right) and under-interpretation (missing details that look similar at a glance).

• Authorized reference files: screenshots, Figma links, design tokens, or a live URL to measure against.
• Asset locations: where fonts, images, icons, and other design assets live in the project.
• Responsive breakpoints and the expected behavior at each screen width.
• Typography and color rules: font families, scale, color values, and how to apply them.
• What is intentionally different from the reference and why.
• How to run the project locally to review the output visually.

The template

Copy this into a CLAUDE.md at your project root. Fill in the bracketed sections with your specific references and requirements.

# [Project name] — website design recreation

## Reference materials
The authorized design references for this project are:
- Screenshots: `design/screens/` — use these as the primary visual reference.
- Figma file: [link or "not available; use screenshots only"]
- Live reference site: [URL, or "none — work from screenshots only"]

Do not use other sites as visual references. Do not copy code from any external source.
If you find the screenshots are ambiguous, ask rather than assuming.

## Assets
- Fonts: `src/fonts/` — [list font families and their files]
  Load fonts locally; do not use a CDN unless specified below.
- Images and icons: `src/assets/` — use only what is in this folder.
- Color tokens: `src/styles/tokens.css` (or list values here if there is no token file):
  - Primary: #[hex]
  - Background: #[hex]
  - Text: #[hex]
  - [add others]

## Typography
- Heading font: [family name], weights [list]
- Body font: [family name], weight [regular/medium]
- Base size: [value]. Scale: [list sizes if relevant]
- Line height: [value]. Letter spacing: [if specified]

## Responsive behavior
- Mobile-first. Base styles apply at all widths.
- Breakpoints:
  - md: [value] — [describe layout change]
  - lg: [value] — [describe layout change]
- Navigation: [describe mobile vs desktop behavior]
- Images: [fluid / fixed / cover / contain]

## Running the project
```
[commands to install and start the dev server]
```
Review the output in a browser at the widths listed above.
Compare against the screenshots in `design/screens/` before submitting.

## Known intentional differences from the reference
[List changes that are deliberate: "The original uses a Google-hosted font; we serve it locally."
"The hero image in the reference is a placeholder; we use the actual approved image."]

## What Claude Code must not do
- Change a color, font, or layout value not covered in this file without asking.
- Use an image or asset not in `src/assets/`.
- Add a CSS framework or library not already in the project.

Authorizing references clearly

The most important section is the reference materials list. Claude Code should know exactly what it is allowed to measure against, and what counts as ground truth when the screenshot and a reasonable interpretation disagree. If the Figma file is not available and the screenshots are the only reference, say so. If the live site can be used to check specific measurements, say that too.

Listing what Claude Code must not use as reference is equally important. Without that constraint, an assistant may look at similar designs online and import conventions from them. The goal of recreation is fidelity to the original, not similarity to common web design patterns.

Responsive behavior needs its own section

Responsive behavior is often the area where recreations diverge most from the original. Screenshots are usually taken at one screen width; the behavior at other widths must be inferred or specified. If the original design has documented breakpoints, include them. If not, describe the expected behavior at each major width and mark any areas where the specification is incomplete.

A rule like "On mobile, the navigation collapses to a hamburger menu that expands to show the full menu list" is precise enough for Claude Code to implement. "Make it responsive" is not — it leaves too much open to interpretation.

Typography is another area where a rule prevents unnecessary interpretation. If your CLAUDE.md names the font family, the size scale, and the line-height value, Claude Code can apply them consistently. If it only says "match the reference," it will estimate values from the screenshot — and estimates compound. A heading that is two pixels taller than the reference will create spacing inconsistencies that cascade through the layout.

Tracking design decisions as the project evolves

Design recreation projects produce decisions continuously: the client approves a font substitution, an element is moved for accessibility reasons, a color is adjusted to meet contrast requirements. Those decisions need a home that is more visible than a comment in a CSS file.

A project's Decisions and rules in fenbs keeps a record of each change from the reference, who approved it, and why. The next session — or the next person — can look at the record and understand which deviations were intentional before making further changes.

How to do this with fenbs

1. Create a free account. Start a project for the site recreation and add the key tasks.
2. Add the reference constraints — authorized design source, breakpoints, font and color decisions — as context notes in the project.
3. As the client approves changes from the original design, record each one as a Decision in fenbs with the approver and the reason.
4. Connect Claude Code to fenbs from Integrations. Ask it to read the project context so it knows the current approved state before making visual changes.
5. Copy the CLAUDE.md template above into your project root and fill in your specific references, asset paths, breakpoints, and typography values. Update it whenever the client approves a change from the original reference.

For broader Claude Code tips on design and front-end work, see the Claude design guide. For building sites from scratch with Claude Code, see can Claude Code build a website. If the output drifts from the reference over multiple sessions, CLAUDE.md not working has troubleshooting steps.