Guide

Make Claude Code and Cursor build UI that matches a website

Ask a coding agent for “a clean settings page” and you get a generic one. Give it a DESIGN.md taken from a site you like, and it builds with that site's real colors, type scale, radii and component rules instead of guessing.

This guide shows the whole loop in Claude Code and Cursor, using Linear's file from the gallery as the example.

Written for developers building with an AI coding agent. Updated .

What you'll get

  • A DESIGN.md for a site you like, saved in your repo where your agent can read it.
  • A short pointer in CLAUDE.md for Claude Code and a project rule for Cursor, so every UI task starts from the file.
  • Prompts that name the tokens, so the agent uses exact values instead of close guesses.
  • A quick review routine to catch the places where the agent drifted.

Why a DESIGN.md beats a screenshot

A screenshot gives your agent pixels to guess from. It will get the mood roughly right and the values wrong: a blue that is close, a radius that is off by a few pixels, a font it picked because it looked similar. Every new screen guesses again, so the app slowly drifts.

A DESIGN.md gives it the exact values. The file follows Google's DESIGN.md specification: YAML front matter at the top holds the tokens (hex colors, font families and sizes, radii, components), and the markdown below explains where each one belongs. New to the format? Read what a DESIGN.md is.

Steps

  1. Pick a site whose interface feels like what you are building

    Product screens with a similar density work better than a landing page with a big hero. If you are building a dashboard, pick a product that has one. Check the DESIGN.md gallery first: the file may already be there.

  2. Get its DESIGN.md

    Copy it from the gallery page, or paste the URL on the Design Extractor home page and run a Pro extraction. Pro samples the site's key pages, and a run takes at least a minute.

  3. Save it as DESIGN.md in your repository root

    Put it next to README.md and AGENTS.md and commit it, so every branch and every teammate's agent reads the same file.

  4. Point your agent to it

    Add a short pointer to CLAUDE.md for Claude Code, or a project rule for Cursor. The blocks are below.

  5. Ask for UI in the file's terms

    Name tokens and components in your prompt (primary, body-md, a button recipe) and ask the agent to list any value it could not find instead of inventing one.

  6. Review the result against the file

    Check colors, fonts, radii and states against DESIGN.md before you accept the change.

Worked example: Linear

The Linear DESIGN.md in the gallery was extracted from linear.app with a Pro run that captured 5 pages. It holds 17 color tokens, 16 type styles and 12 radii. This is what your agent works from.

Colors

Typography

hero-displayDesign is intelligence made visibleInter Variable72px / 510 / 1
display-lgDesign is intelligence made visibleInter Variable64px / 510 / 1
display-mdDesign is intelligence made visibleInter Variable48px / 510 / 1
heading-lgDesign is intelligence made visibleInter Variable32px / 590 / 1.15
title-mdDesign is intelligence made visibleInter Variable20px / 590 / 1.35
body-lgDesign is intelligence made visibleInter Variable17px / 400 / 1.6

Shapes

xs · 2px
sm · 4px
sm-2 · 4.4625px
md · 5px
md-2 · 6px
lg · 8px
lg-2 · 9px
xl · 12px

Linear's first 12 colors, 6 type styles and 8 radii, rendered from its DESIGN.md. Click a swatch to copy the hex value.

The top of the file, abridged: 8 of 17 colors, 2 of 16 type styles and 4 of 12 radii. These are the exact values the agent copies.
---
name: Linear
colors:
  primary: "#5E6AD2"
  canvas: "#08090A"
  surface: "#121414"
  surface-raised: "#1C1C1F"
  ink: "#F7F8F8"
  ink-secondary: "#D0D6E0"
  muted: "#8A8F98"
  subtle: "#62666D"
typography:
  hero-display:
    fontFamily: Inter Variable
    fontSize: 72px
    fontWeight: 510
    lineHeight: 1
    letterSpacing: -1.584px
  body-lg:
    fontFamily: Inter Variable
    fontSize: 17px
    fontWeight: 400
    lineHeight: 1.6
    letterSpacing: normal
rounded:
  xs: 2px
  sm: 4px
  sm-2: 4.4625px
  md: 5px
---

Extracted from Linear's public website, not official brand guidelines. Read the full Linear DESIGN.md

How the file describes the look

The prose under the tokens tells the agent where each value belongs. It opens like this:

Linear's marketing surface reads like the product itself: a near-black Void canvas (canvas, #08090A) with charcoal panels stacked a half-step lighter, fenced by 1px hairlines rather than shadows. The mood is engineering-grade and restrained. Realistic product UI mockups, a customer logo strip and Berkeley Mono micro-labels ("FIG 0.1") stand in for illustration. Nothing shouts; the page earns attention through precision.

Rules the file gives your agent

The Do's and Don'ts section turns the look into rules. The first few:

Do

  • Reserve Linear Indigo (primary, #5E6AD2) for focus and interactive accents. Every measured focus state is a 1px solid #5E69D1 outline with a 2px offset.
  • Shape every button as a pill with rounded.full. button-ghost, button-ghost-2 and button-ghost-3 all measure 9999px.
  • Keep control heights on the observed ladder: button-ghost and button-ghost-2 at 32px, button-ghost-4 at 29px, button-ghost-3 at 24px, and sidebar-nav-item and the icon buttons at 28px.

Don't

  • Don't use weights other than 400, 510 and 590, and never substitute a static 600 or 700 for heading-lg or title-md.
  • Don't add a third typeface. Inter Variable carries everything, and Berkeley Mono is limited to micro figure labels.
  • Don't use accent-blue, danger or success for marketing chrome; they belong inside product mockups.

Components

The file has 30 component recipes in HTML and CSS. 13 of them passed the check against the live page; for the others the file says why they did not pass or could not be checked. The whole file is about 276,000 characters, most of it recipes. That is why you point your agent to it instead of pasting it into prompts.

Point your agent to the file

Most agents do not open DESIGN.md on their own. A few lines in the instructions they already load fix that. In Claude Code, add this to CLAUDE.md in your repository root:

## Design
Follow DESIGN.md in the repository root for every UI change.
Use its color, typography, rounded and component tokens instead of inventing values.
Before you build a button, card or input, read its recipe in the Components section.

In Cursor, add a project rule. Save this as .cursor/rules/design.mdc; alwaysApply loads it for every request in the project:

---
description: Follow DESIGN.md for every UI change
alwaysApply: true
---
Follow DESIGN.md in the repository root for every UI change.
Use its color, typography, rounded and component tokens instead of inventing values.
Before you build a button, card or input, read its recipe in the Components section.

Use a pointer rather than pasting the file into the instructions. A Pro DESIGN.md carries a recipe for every component it picked from the site, so it is long, and your agent only needs it for UI work.

Prompts that use the tokens

Name the file and its tokens, and give the agent a way out instead of a reason to guess. These prompts were written for this guide with Linear's real token names; swap in your own task.

Claude Code

Build a pricing page with three plan cards. Follow DESIGN.md:
- use primary (#5E6AD2) only where the file says it belongs
- set headings in hero-display and body copy in body-lg
- reuse the button-ghost recipe for the plan buttons, with its hover and focus states
- start the plan cards from the card recipe
List any value you could not find in DESIGN.md instead of inventing one.

Cursor

@DESIGN.md Restyle the settings form in src/app/settings to match this file.
Take colors, type and radii from the tokens and inputs and buttons from the component recipes.
Keep the existing layout and logic, and list any value you could not find in the file.

In Cursor, @DESIGN.md attaches the file to the chat, which helps on top of the rule when the task is mostly about looks.

What should the result look like? Roughly like this card, which this page draws straight from the tokens. It shows what the values do, not what an agent produced.

Plan the next release

Every task, date and decision in one place, so the team ships on time.

Start buildingTalk to sales
Illustration drawn by this page from Linear's tokens: canvas #08090A, ink #F7F8F8, primary #5E6AD2 and button-ghost.rounded 9999px. It is not output from a coding agent, and the font only shows if your device has it.

Review what the agent built

  • Colors. Search the diff for hex values. Each one should be in DESIGN.md. A new one usually means the agent guessed.
  • Fonts. Many brands use commercial fonts you cannot ship. The file's Typography section usually names an open-source stand-in; make sure the agent loaded that one, not a random fallback.
  • Radii and spacing. Buttons and cards should use the file's rounded tokens, not a default like 8px everywhere.
  • States. Hover and focus styles are part of each component recipe. Tab through the page and check the focus ring.
  • Flagged recipes. If the file marks a recipe as flagged, its geometry is an approximation. Compare that component with the real site.

If you edit DESIGN.md by hand, check it with the free DESIGN.md Validator before your agent reads it again.

FAQ

Match a website in Claude Code and Cursor: questions

Short answers to what people ask before they try this.

No. Save it once as DESIGN.md in the root of your repository and point to it from CLAUDE.md for Claude Code or from a project rule for Cursor. The agent reads it when a task touches the interface. A Pro DESIGN.md with component recipes is long, so pointing to it keeps your prompts short.

No, and that is not the goal. The agent gets the site's tokens (colors, type, radii), its component recipes and its rules. Your layout, content and features stay your own. Recipes that did not pass the check against the live site are marked as flagged in the file, so treat those as close approximations.

Yes. Any agent that can read files in your repository can use a DESIGN.md. Point to it from the instructions that agent already reads, such as AGENTS.md or .github/copilot-instructions.md, or name the file in your prompt.

Yes. Every gallery page has the full DESIGN.md to copy. Gallery files are extracted from each brand's public website, not official brand guidelines. For a site that is not in the gallery, paste its URL on the home page and run an extraction.

Get a DESIGN.md for the site you like

Paste any public URL. A Pro extraction samples the site's key pages and returns a DESIGN.md your agent can read.

Get a DESIGN.md from any website

Related guides

See all DESIGN.md guides