How to build a website with Claude Code that looks designed

Claude Code can take an empty folder to a working, responsive website in one session. It scaffolds the project, writes the components, starts the dev server and checks its own work in a browser. What it cannot do is decide what the site should look like, so every decision you leave open gets the most common answer it knows.

Anthropic's Applied AI team gave that pull a name, distributional convergence, when it described Claude's unguided frontend output: Inter, purple gradients on white, very little motion (Anthropic). The cure is a specification written as values, and this guide is how to set one up and hand it to Claude Code.

The short version:

1. Set the project up so the design rules load in every session.
2. Write the brief as hex values, type sizes, curves, durations and a section order.
3. Supply the media, because Claude Code writes code and does not film.
4. Build in passes, and make Claude check each pass in a browser.

If you want a clickable prototype without a codebase, Anthropic's other route is Claude Design, covered in Claude Design prompts. This guide is for a site you own as code.

What Claude Code actually does on a website#

Claude Code is Anthropic's agentic coding tool. It reads a codebase, edits files and runs commands, and it works in the terminal, in VS Code and JetBrains, in the Claude desktop app and on the web. It is included in Claude's paid plans from Pro upward (pricing).

On a website build it runs the whole loop rather than handing you snippets:

• Scaffold: it runs the project generator you name and installs the packages.
• Write: components, styles, scroll and pointer logic, responsive rules.
• Run: it starts the dev server and reads the errors itself.
• Look: it reads screenshots you paste with Ctrl+V. In the desktop app it opens the site in its Browser pane, takes screenshots, clicks through and fixes what it finds (desktop docs). In the terminal, claude --chrome connects it to your Chrome (Chrome docs).

The last point matters more than it looks. A model that can see the page catches a headline that wraps into five lines at 375px, or a hero video that never starts on a phone. A model that cannot see the page ships both.

What it lacks is your taste. Ask for "a modern landing page for a coffee roaster" and each open decision gets the median: a centered hero, a sans serif at a safe size, a gradient behind it, three feature cards, a fade-up on every section. That is the look described in why AI websites look the same, and the brief is where it comes from. For a café, the coffee shop website prompt answers those decisions with values instead, down to a 21px body size for reading in daylight. The same tool, handed a full art direction, builds pages like these, each from a Thanor prompt that sets the palette, type, spacing, curves, section order and media as values:

Set up the project before the first prompt#

A few minutes of setup decide whether your design rules survive past the first session.

1. Start in an empty folder and name the stack#

Run claude in a new directory and say exactly what to scaffold. "A Vite project with React and TypeScript, Tailwind for layout, GSAP with ScrollTrigger for scroll, no other UI library" closes five decisions in one line. Leave the stack open and Claude picks whatever is most common for the request, which can be far more framework than a one-page site needs.

2. Put the design rules in CLAUDE.md#

Claude Code reads CLAUDE.md at the start of every session (memory docs). Run /init for a starting file, keep it under the 200 lines the docs recommend, and import the long specification with an @ path so it loads alongside:

## Design rules
- Read @design/SPEC.md before any UI change. Its values win over your defaults.
- Colors, sizes and durations come only from src/styles/tokens.css.
- One display face, one text face, both named in SPEC.md.
- Reveals: cubic-bezier(0.22, 1, 0.36, 1) at 640ms. UI response: 240ms.
- Every animation has a static end state under prefers-reduced-motion.

3. Install the frontend-design plugin#

Anthropic publishes a frontend-design skill in its official plugin marketplace. Install it with /plugin install frontend-design@claude-plugins-official and Claude loads it for UI work: it plans a palette and type system before coding and watches for the common defaults. The direction still has to come from you, and the skill's own text says the brief's words always win.

4. Give it a way to see the page#

In the desktop app the Browser pane is built in, and with autoVerify on, Claude screenshots and checks its own changes. In the terminal, start with claude --chrome, or add the Playwright server with claude mcp add playwright -- npx @playwright/mcp@latest. The bundled /verify skill builds and runs the app to confirm a change works (skills docs).

Write the brief as a specification#

A brief that ships a designed site answers the questions Claude Code would otherwise answer for you. There are about a dozen of them, and each one has a value.

Every row is a decision the model makes anyway. Writing the value is how the decision becomes yours, and it costs one line per row. The words premium, bold and cinematic close none of them, which is why a longer, more adjective-heavy prompt changes so little (the counted version). For a 3D hero like Kickflip's, the 3D website guide adds the camera, light and material values.

Media is the part Claude Code cannot make#

Claude Code writes code. It does not shoot a hero film, light a product or cut an object out of its background, so when a brief asks for a cinematic hero with no media attached, it builds one from what code can draw: gradients, blurred blobs, an SVG shape, a canvas noise field. That is one of the quickest ways for a Claude Code site to read as generated, even when the layout is good.

There are three ways to give it real media:

• Your own files: footage, product photography, a 3D model as a .glb. Put them in public/media/ and name each one in the brief, with where it goes.
• Media hosted with the design: every Thanor art direction comes with hosted media, whether films, cut-outs or stills, that the built page uses, so the prompt carries URLs instead of a wish for "a dramatic video".
• A background clip: the animated backgrounds page has looping video backgrounds for hero sections. Copy a clip's URL into Claude Code or download the file.

Then say how the media behaves, because "add a video" leaves five more decisions open:

<video autoplay muted loop playsinline preload="metadata"
  poster="/media/hero-poster.jpg" width="1920" height="1080">
  <source src="/media/hero.mp4" type="video/mp4">
</video>

muted and playsinline are what allow a video to autoplay on a phone, and the explicit width and height stop the layout from jumping while it loads. A film that the scroll scrubs is a different build: the brief has to say that currentTime follows scroll progress, and the file needs frequent keyframes so seeking stays smooth. The scroll animation prompt has the distances, and animated website backgrounds covers loops that do not slow the page.

Build in passes, and check every pass#

One prompt for the whole site produces one large average. Four passes, each with a check, keep every decision visible.

Pass 1: plan the structure#

Press Shift+Tab until the status bar shows plan mode, or start with claude --permission-mode plan. Claude reads and proposes but edits nothing until you approve (common workflows). Ask for the token file, the section list and the component tree, and correct the plan before a line is written.

Pass 2: the hero alone#

Build only the hero, with its media and its single motion sequence, then stop. The hero carries most of the first impression, and it is cheaper to fix on its own.

Pass 3: the remaining sections#

Build them in the written order, each against the tokens. Then ask Claude to list every value it used that is not in tokens.css. The right answer is none.

Pass 4: the check#

Open the site in the browser. Screenshot every section at 375, 768 and 1440 px
wide. Check that nothing scrolls horizontally, the display headline never wraps
past three lines, the hero video plays on mobile, focus rings are visible, and
with prefers-reduced-motion every animation shows its end state. Fix what fails
and show me the screenshots.

Anthropic's best practices make the same point in general terms: give Claude a check it can run, and ask for the evidence, meaning the command output or the screenshot. Claude Code prompts for UI that ships has a prompt for each of these passes.

Put the art direction inside Claude Code#

Writing a full specification for every project is the slow part. The Thanor MCP server moves that step into Claude Code itself: the library of art directions becomes a tool Claude can search and read, with no copying and pasting.

claude mcp add --transport http thanor https://thanor.ai/api/mcp

Run /mcp in a session, pick the server and approve on the Thanor page that opens. Claude Code signs in with OAuth, so there is no token to paste, and --scope user makes it available in every project. It exposes three read-only tools:

• search_designs finds directions by name or category, and returns names and categories only.
• get_design returns one design's details, including whether it is free.
• get_prompt returns the full art direction to build from, and spends one copy from your plan's daily allowance.

A session then reads like a brief: "search Thanor for a portfolio hero with cursor interaction, get the prompt for Vesperion, and build it as the home page of this Vite project". The MCP is included in every paid plan and listed in the Claude connectors directory. Setup for Claude, ChatGPT and Cursor is in the MCP docs, and the rest of the useful toolset is in the best MCP servers for web design.

Mistakes that make a Claude Code site look generated#

Most of these come from the same root: a decision left open in the brief, or a rule that lived in one conversation instead of a file.

• Adjectives in place of values. Clean, bold and premium close no decision, so Claude falls back to the median for each one.
• Letting it choose the typefaces. Type carries most of a page's personality. Name the display face, the text face and both sizes.
• A fade-up on every section. The frontend-design skill itself calls this the generic default. One orchestrated sequence reads as designed; twelve identical ones read as a template.
• One radius everywhere. 8px on the button, the card and the image is the framework talking, one of the defaults listed in the frontend model comparison. Give controls, cards and media their own values.
• A gradient where the media should be. If the hero is meant to be cinematic, it needs a film or a cut-out, with a URL in the brief.
• Checking only at desktop width. Ask for screenshots at 375px every pass. Display type breaks there first.
• Changing direction without updating CLAUDE.md. The next session reads the old rules and drifts back.

If you build in Cursor instead, every point above still applies; Claude Code vs Cursor for frontend work covers what differs between the two.

What to do next#

Open Vesperion and copy its prompt; it is free with an account. Run the four setup steps in an empty folder, paste the prompt into Claude Code as the brief, and build it in passes. Then open a fresh session, ask for "a portfolio hero with a creature whose eyes follow the cursor" in one sentence, and compare the two results. That comparison shows where the design comes from faster than any argument.

When one direction is not enough, the library has the rest, each with its prompt and its media, and the paid plans on pricing include the Thanor MCP so Claude Code can fetch any of them directly.