Website Design with an AI Agent: Claude Code and Refero DESIGN.md

Practical materials on working with projects and models: Ailoot documentation.

Why Do Claude Code Websites Look Like Tailwind Templates?#

In the January example described, a small side project was being created—a cold-sales dialer. In an empty repository, Claude Code was asked to build the home page. The result was generic: a slate-950 dark background, a purple-500 accent, a bold sans-serif heading, and three cards below it with identical shadows. The same layout as ChatGPT’s first release, Lovable’s first release, and v0’s first release. After five prompt edits adding “modern,” “premium,” and “not like everyone else”—nothing changed. The page still looked like it came from a set of Tailwind UI Templates.

That is, Claude does not “not know” how to make something beautiful. It knows what most people do and reproduces that majority. To get a non-averaged result, the agent needs specific constraints: which colors to use, which fonts, which spacing, and which components to treat as canonical.

This is where a design system comes in as context. Not “make it beautiful,” but “make it in this specific style; here are its parameters.”

Refero Styles bridges that gap with a ready-made artifact—a DESIGN.md file containing parameters from real products.

What Is Refero Styles?#

The styles.refero.design home page says it plainly: “discover 2,000+ AI-agent-readable design systems from leading product websites.” The catalog features brands that set the visual standard: Apple, Linear, Stripe, Notion, Vercel, ElevenLabs, Mercury, PostHog, xAI, Modal, Duolingo. They are not extracted manually—the Refero team runs a script that analyzes a site’s actual CSS and markup and packages the result into structured markdown. The styles.refero.design library itself is free.

The key word is “structured.” The file contains no screenshots and no description like “in a minimalist style.” It is markdown with specific hex colors, exact font sizes in pt, spacing units, and rules for components. The AI agent reads this file and works with specifics rather than attempts to describe taste in words.

The Refero team lists the supported tools on its ai-agents page as “Cursor, Claude Code, Codex, v0, and Lovable.” In other words, DESIGN.md works as a universal artifact—one file that suits all the major AI development agents.

What Is in a DESIGN.md?#

The Refero team describes the file structure on its design-md-template page as follows:

So the file structure is usually like this:

The creators also emphasize a principle that solves 80% of AI design problems:

That is, the hex code #5E6AD2 is stronger than “like Linear.” The exact value font-size: 13px / line-height: 18px is stronger than “compact text.” Specifics beat interpretation.

DESIGN.md in the repo is not an image for the team. It is a building block of your project’s Second Brain: structured knowledge that AI reads with every request.

How to Make a Website in the Style of Linear in 4 Steps#

These four steps make up the described sequence for starting a new website. Not “four steps in general,” but a specific sequence with one action for each step.

1. Install Claude Code

   Native one-command installer: curl -fsSL https://claude.ai/install.sh | bash (the recommended method in the official documentation). On macOS, brew install --cask claude-code works; on Windows, winget install Anthropic.ClaudeCode. If it is already installed, check the version: claude --version (2.1.178+ is needed—this version introduced Tool(param:value) permissions and blocking dangerous git commands in auto mode). Sign in to your account: claude launches the wizard. Claude Code is included in a Pro subscription ($17/month with annual billing or $20/month month-to-month).

2. Open Refero Styles and Choose a Brand

   Go to https://styles.refero.design and open the catalog. The main selection criterion is how closely it matches your product, not whether you “like the look.” Building a SaaS dashboard? Look at Linear, Vercel, and Notion. Building a fintech product? Look at Stripe, Mercury, and Column. Building a product for members? Look at Duolingo. Open a brand card and click “Copy DESIGN.md.”

3. Put DESIGN.md in the Project as Context

   Create a docs/DESIGN.md file in the project root and paste in the copied content. Then open CLAUDE.md and add one line: @docs/DESIGN.md. This is an import directive—Claude Code loads the contents into context when a session starts. For more about imports in CLAUDE.md, see the guide to one instruction file for Claude Code, Codex, and Cursor.

4. Prompt for a Specific Page

   Not “make it beautiful.” Be specific: “Using the DESIGN.md in context, build a home page for a SaaS task management product. Structure: hero with a heading and subheading, two CTA buttons (primary and secondary), a block below with 3 features and icons, then a testimonials block. Use exactly the colors and typography from DESIGN.md; don’t make up your own.”

After the fourth step, Claude builds the page. In the described experience, a home page takes an average of 8–12 minutes—and it really does look close to the selected brand’s style. Not a pixel-perfect copy, but a recognizable aesthetic: the same fonts, the same palette, the same spacing rhythm, and the same micro-decisions in the buttons.

The Refero creators describe the same three-step principle a little more briefly on their ai-agents/design-resources page:

This four-step sequence follows the same logic, with the added explicit steps of installing Claude Code and importing the file into CLAUDE.md.

Which Style Should You Choose for Your Product?#

The Refero creators give this advice right in the first step of their guide: choose a reference based not only on the brand name, but also on density, tone, and audience.

What does this mean in practice? Apple-derived colors, typography, hierarchy, and restrained motion can suit a SaaS dashboard, while the generous spacing of a particular product-marketing page may not. Inspect the specific reference rather than choosing by brand name. For an accounting dashboard, set compact row heights, spacing, and information density explicitly, preserving readable numbers and controls; do not copy a spacious presentation layout unchanged.

A simple product-type selection guide:

If you are still in doubt, choose Linear. It has the most versatile foundation: a neutral palette, readable typography (Inter / Söhne), and restrained spacing. A website based on Linear will look professional for 9 out of 10 product types.

Why Make DESIGN.md Part of the Project’s Permanent Context?#

In the described practice, DESIGN.md is stored next to CLAUDE.md in every project managed with AI agents. This file is not considered “temporary for one task.” It is a permanent canon that all future sessions rely on. In a month, you can ask Claude to add a new page to the project—it will open the same DESIGN.md and build in the same style. In six months, you can hand the project to another team member—they can also run Claude and get a consistent result, because DESIGN.md is in the repo.

In design, the principle works like this: a decision is made once—the palette, typography, and spacing rhythm. After that, every AI agent takes it as given.

That is, design lives as code (markdown is code), not as a Figma file that AI cannot read. When design is a file in the repo, Claude Code reads it, Codex reads it, and any future tool can read it. When design is in Figma, it lives in a separate plane and has to be manually translated for every session.

In the side projects described, this structure was used:

project/
├── CLAUDE.md            (imports @docs/DESIGN.md)
├── docs/
│   ├── DESIGN.md        (visual canon, copied from Refero)
│   ├── ARCHITECTURE.md  (project structure)
│   └── BRAND.md         (tone of voice, vocabulary)
└── ...

These three files are one way to organize the project’s permanent context. DESIGN.md handles visuals, ARCHITECTURE.md handles structure, and BRAND.md handles voice. Any AI agent with access to the repo gets all three as context.

What Are Refero MCP and refero_skill?#

Refero Styles is the base layer (DESIGN.md as a file). The next wave consists of integrations that make access to the library “native” for AI agents.

Refero MCP (official). This is a server API at https://api.refero.design/mcp that Claude Code connects to using a bearer token. The agent then has access to 150,000+ screens and 6,000+ user flows from real products. You can install it with a skill:

npx skills add https://github.com/referodesign/refero_skill --skill refero-design

After installation, Claude launches “design research” at the start of every session as a required first step: it looks at which visual choices suit the task and, if needed, proposes three directions tied to the selected reference. As of June 23, 2026, the refero_skill repository has 67 commits and 135 stars. A new product under active development.

The described practice uses a simple approach: open the site manually, copy DESIGN.md, and put it in a file. MCP is useful when working with design systems becomes routine—for example, when you manage several client projects and switch between visual canons every day. For more on connecting MCP servers to Claude Code, see the guide to NotebookLM and MCP.

What 4 Mistakes Break the Workflow?#

These four mistakes come up in the described experience of working with design context. Each seems harmless, but each returns the result to the standard Tailwind template.

Mistake 1. The prompt “make it modern.” This is the most common mistake pattern. People open Claude Code and write, “make me a SaaS website, modern style, premium look.” They get a dark background plus a purple accent. In the training data, the word “modern” correlates with all the 2022–2024 landing pages built from the same template. Without the exact parameters from DESIGN.md, “modern” means “average.”

Mistake 2. Pasting DESIGN.md into chat as a message. Sometimes people copy DESIGN.md into the Claude Code chat window and say, “here’s the style, use it.” This works once—until the end of the session. Open a new session (or switch to another task, /clear), and the context is lost. If you want the style to persist, the file must be in the repo and imported in CLAUDE.md. For more on why CLAUDE.md is the point of permanent context, see the guide to Claude memory.

Mistake 3. Choosing a style because you “like it.” A spacious Apple marketing reference may be a poor layout to copy unchanged into a real-estate dashboard that needs 30 listings on screen. That does not rule out Apple-derived typography, palette, or hierarchy: adapt spacing and row density to the task, then check the actual information visible at the target screen size. Choose the particular reference by density, tone, and audience, not just its brand name.

Mistake 4. Not mentioning DESIGN.md in the prompt itself. DESIGN.md may be in the repo, imported through CLAUDE.md, and visible to the agent. But if the prompt says “build a website,” Claude may take the standard route without explicitly referring to the file. For every design prompt, this line is useful: “Use exactly the colors, fonts, and spacing from docs/DESIGN.md. Don’t make up your own values—take them from the file.” This ensures the agent uses DESIGN.md instead of bypassing it.

Exact tokens are hex codes, font sizes in pt, and spacing units in DESIGN.md. Natural language means “modern,” “premium,” “clean,” or “like Apple.” Exact tokens work; free-form words do not.

What Should You Do Next?#

You now have the basic workflow: Claude Code + DESIGN.md from Refero + 4 steps = a non-template website. This covers 70% of needs. The remaining 30% are cases when you need greater precision, more speed, or verification.

Three directions to pursue after mastering the basics:

1. Frontend Design Skill. This is an official skill for Claude Code that adds visual feedback. The agent takes a screenshot of the assembled page with Puppeteer, looks at it with its “eyes” (a vision model), compares it with DESIGN.md, and suggests corrections itself. This is an automated “prompt → code → screenshot → critique → prompt” loop. Useful when a page is complex and you cannot get it right in one iteration.

2. Refero MCP in production mode. When you manage 3–5 projects in parallel, manually adding DESIGN.md for each becomes tedious. Refero MCP can find 3 suitable styles based on a project description and offer a choice. This speeds up starting a new project from 30 minutes to 3.

3. Combination with Context Engineering. DESIGN.md is one of the context artifacts. Alongside it, you will usually find ARCHITECTURE.md (project structure), BRAND.md (tone of voice), and business/audience.md (target audience). They are all imported in CLAUDE.md. When Claude builds a page, it relies on visuals, the audience, and the product structure. Essentially, this is context engineering—systematic work on what you give the agent before a request.

Practical materials: Ailoot documentation.

Practical materials: Ailoot documentation.

More materials and tools: Ailoot.