The CLAUDE.md File Every Design Project Needs (With Templates)

Reviewed by Yusuf, Lead Designer at 925Studios

A CLAUDE.md file is the single most impactful configuration you can add to any design project using Claude Code. It is a markdown file placed at the root of your repository that Claude reads automatically at the start of every session, giving it persistent knowledge of your design system, coding conventions, and project constraints. Without one, Claude guesses. With one, it builds exactly what your design system specifies. The difference in output quality is not subtle. Teams using structured CLAUDE.md files consistently report 60-80% fewer design corrections on first-pass code generation. At 925Studios, we treat CLAUDE.md setup as the first task on every new project, before a single component gets built.

TL;DR:

• CLAUDE.md gives Claude Code persistent context about your design system, eliminating repeated instructions

• For design projects, include typography scales, color tokens, spacing rules, component conventions, and accessibility requirements

• Keep it under 200 lines. Use sub-folder CLAUDE.md files for frontend-specific rules

• The file reduces AI-generated "design slop" by constraining Claude to your actual system, not generic defaults

• Templates for SaaS dashboards, landing pages, and design system projects are included below

Quick Answer: A CLAUDE.md file is a markdown configuration file at your project root that Claude Code reads automatically every session. For design projects, it should contain your typography scale, color tokens, spacing system, component naming conventions, and accessibility rules. Anthropic recommends keeping it under 200 lines. The file eliminates generic AI output by constraining Claude to your specific design system, resulting in dramatically better first-pass code quality.

What is a CLAUDE.md file and why do designers need one?

CLAUDE.md is a project-level configuration file that Claude Code loads into its context window at the start of every conversation. Think of it as a persistent brief that travels with your codebase. Unlike chat instructions that disappear when a session ends, CLAUDE.md stays in your repository and applies consistently across every interaction, every team member, and every coding session.

For developers, CLAUDE.md typically contains terminal commands, linting rules, and architectural patterns. For designers working with Claude Code, the file serves a different and arguably more important purpose: it encodes your design system into Claude's working memory.

Without a CLAUDE.md file, Claude Code defaults to generic design decisions. It picks system fonts, uses arbitrary spacing values, applies colors that look reasonable but do not match your brand, and generates components that feel like a template. This is the root cause of what people call "AI slop" in web design. The AI is not bad at design. It just has no idea what your design looks like.

A well-written CLAUDE.md file solves this problem by giving Claude three things: (1) the exact tokens and values from your design system, (2) the conventions your team follows for naming, structure, and component composition, and (3) the constraints that should never be violated, like accessibility requirements or brand guidelines.

According to Anthropic's best practices documentation, CLAUDE.md files should be concise, focused, and actionable. The recommended length is under 200 lines. Every line should earn its place by influencing Claude's output in a measurable way.

Why does CLAUDE.md setup matter more for design than for development?

Developers already have guardrails baked into their workflows. TypeScript catches type errors. ESLint enforces code style. Prettier formats everything consistently. But design decisions, the font size of a caption, the padding inside a card, the specific shade of grey for secondary text, live outside those automated systems. They exist in Figma files, design tokens, and the heads of designers. Claude Code cannot access any of those by default.

This gap explains why AI-generated frontend code often looks technically correct but visually wrong. The HTML is valid, the React components render, the Tailwind classes are syntactically fine. But the spacing is off, the typography hierarchy feels flat, and the color palette looks like every other AI-generated site on the internet.

CLAUDE.md closes that gap. When you specify that your body text is 16px/24px Inter, your primary color is #2563EB, and your card padding follows an 8px grid, Claude stops guessing and starts implementing. The shift from generic output to system-compliant output is immediate.

Nick Babich wrote on UX Planet that the three most impactful practices for improving Claude Code productivity are configuring a CLAUDE.md file with project conventions, structuring prompts with precise context, and using plan mode before complex tasks (UX Planet, 2026). The CLAUDE.md file is first on that list for a reason. It is the foundation that makes everything else work.

Need help encoding your design system for AI-assisted development? Book a free 30-minute call with our team.

What should a design-focused CLAUDE.md file include?

The structure below covers the seven sections that matter most for design projects. Not every project needs all seven, but most benefit from at least five. The key principle: include only rules that directly affect visual output.

1. Project overview and stack

Start with what the project is and what tools it uses. This gives Claude the technical context it needs to generate correct code. Keep it to 3-5 lines.

2. Typography system

Typography is where generic AI output is most obvious. Specify your type scale, font families, weights, and line heights explicitly. Claude will use these values instead of defaulting to system fonts or arbitrary sizes.

3. Color tokens

List your color system with semantic names. Do not just list hex values. Map them to their purpose so Claude understands when to use each color.

4. Spacing and layout

Define your spacing scale and layout conventions. This prevents Claude from using random padding and margin values that break your visual rhythm.

5. Component conventions

Tell Claude how your components are structured and named. This is especially important if you use a component library like Radix, shadcn/ui, or a custom system.

6. Accessibility requirements

Accessibility rules are constraints that should never be overridden. Making them explicit in CLAUDE.md prevents Claude from generating inaccessible markup.

7. Do not rules

Negative constraints are surprisingly effective. Telling Claude what not to do eliminates entire categories of generic output.

When we set up CLAUDE.md files for client projects at 925Studios, we follow this exact structure. The result is AI-generated code that matches the Figma designs closely enough that design review focuses on refinement, not rework.

How do you structure CLAUDE.md files across a project?

Anthropic supports multiple CLAUDE.md files at different directory levels. This is powerful for design projects because frontend-specific rules do not need to pollute the root configuration that backend developers also use.

The recommended structure uses progressive disclosure. The root CLAUDE.md contains project-wide rules: the tech stack, commit conventions, testing commands, and shared principles. A frontend-specific CLAUDE.md in the /src or /app directory adds design system details, component conventions, and UI-specific constraints. Claude merges these automatically when working in that directory.

This layered approach keeps each file focused and under the 200-line recommendation. Builder.io's guide on writing CLAUDE.md files emphasizes that the file should capture "project-specific instructions you'd otherwise repeat in every prompt" (Builder.io, 2026). If you would not repeat it in a prompt, it probably does not belong in the file.

One pattern that works well for design teams: keep a /docs/design-system.md file with the full design system documentation, and reference it from CLAUDE.md with a one-line pointer. Claude can read the referenced file when it needs details, without bloating the main configuration.

Want to see how this pattern plays out in practice? Explore our case studies.

What are the most common CLAUDE.md mistakes designers make?

After reviewing dozens of CLAUDE.md files across design projects, these are the patterns that consistently lead to poor output.

Writing a novel instead of a spec

The most common mistake is treating CLAUDE.md like documentation rather than a configuration file. Long explanations about why you chose Inter over Helvetica waste context window space. Claude needs the decision, not the reasoning. "Font: Inter" beats "We chose Inter because of its excellent readability at small sizes and comprehensive language support" every time.

Missing the "do not" rules

Positive instructions tell Claude what to do. Negative constraints prevent the generic output that makes AI code look like AI code. Without explicit "do not" rules, Claude will add drop shadows, use arbitrary border-radius values, introduce new colors outside your palette, and apply animations you did not ask for. HumanLayer's guide notes that explicit constraints are often more impactful than positive instructions because they eliminate entire categories of unwanted behavior.

Not including the actual values

Saying "follow the design system" without specifying what the design system contains gives Claude nothing actionable. If your primary color is #2563EB, write #2563EB. If your card border-radius is 12px, write 12px. Ambiguity in CLAUDE.md produces ambiguity in output.

Forgetting responsive rules

Design systems that only specify desktop values leave Claude guessing about mobile. Add breakpoints and responsive behavior to your CLAUDE.md. Specify what changes at each breakpoint: which elements stack, which hide, how typography scales down.

Never updating the file

A CLAUDE.md file is a living document. As your design system evolves, the file must evolve with it. Stale tokens and outdated conventions cause more confusion than having no file at all. Review your CLAUDE.md monthly, or update it whenever the design system changes.

Struggling with inconsistent AI output on your design projects? We fix this for SaaS teams weekly.

What do real CLAUDE.md templates for design projects look like?

Below are three templates covering the most common design project types. Each is under 200 lines and ready to customize with your specific values.

Template 1: SaaS Dashboard

This template works for data-heavy products with tables, charts, cards, and navigation patterns. Products like Linear, Amplitude, and Mixpanel follow similar conventions.

Template 2: Marketing Landing Page

This template targets conversion-focused pages where visual hierarchy and whitespace drive engagement. Products like Vercel, Linear, and Notion use similar approaches for their marketing sites.

Template 3: Design System Component Library

This template works for teams building or maintaining a design system as code. It enforces token usage and prevents drift between the design source and the implementation.

Yusuf breaks down this pattern in more detail on the 925Studios YouTube channel, including live examples of how different CLAUDE.md configurations change Claude's output quality.

How do you measure whether your CLAUDE.md file is working?

A CLAUDE.md file is working when your design review process shifts from "this is wrong" to "this needs refinement." The measurable indicators are straightforward.

First-pass accuracy is the clearest signal. Before CLAUDE.md, Claude Code generates components that roughly match your intent but use wrong fonts, colors, spacing, and structure. After a good CLAUDE.md, first-pass output should match your design system on typography, color, and spacing without manual correction. If you are still correcting basic token values after adding a CLAUDE.md, the file is not specific enough.

Iteration count matters too. Track how many rounds of "change this spacing" or "use the correct color" you go through per component. A good CLAUDE.md reduces this to zero for token-level decisions. Your iterations should focus on layout choices and interaction patterns, not basic visual properties.

Team consistency improves measurably. When multiple designers or developers use Claude Code on the same project, a shared CLAUDE.md ensures everyone gets the same baseline output. Without it, each person's conversational context produces different results, and the codebase drifts.

The Anthropic frontend-design skill, which has over 277,000 installs as of March 2026, works by injecting a design system philosophy into Claude's context. Your CLAUDE.md file does the same thing but with your specific system, your specific values, and your specific constraints. The combination of both produces the best results.

Not sure where your design workflow stands? Get a free UX audit from 925Studios.

Frequently Asked Questions

Where should I place the CLAUDE.md file in my project?

Place the main CLAUDE.md at the root of your repository. For design-specific rules, add a second CLAUDE.md inside your /src or /app directory. Claude merges all CLAUDE.md files it encounters in the directory hierarchy, with deeper files taking precedence over root-level ones.

How long should a CLAUDE.md file be for design projects?

Keep it under 200 lines. Anthropic recommends concise files that focus on actionable rules rather than explanations. If your file exceeds 200 lines, split design system details into a separate /docs/design-system.md and reference it from your CLAUDE.md with a single line.

Does CLAUDE.md work with Cursor, Copilot, or other AI coding tools?

CLAUDE.md is specific to Claude Code. Cursor uses .cursorrules, Copilot uses .github/copilot-instructions.md, and Gemini CLI uses GEMINI.md. The content is transferable between formats, but the file name and loading mechanism differ. Some teams maintain a shared design-system.md and create tool-specific wrapper files that reference it.

Can CLAUDE.md reference my Figma design tokens?

Yes. If you export design tokens from Figma using Tokens Studio or the Variables API, paste the token values directly into your CLAUDE.md. For projects using Figma MCP (released February 2026), Claude can also read design values directly from Figma files, but having tokens in CLAUDE.md provides faster access without an API call.

How often should I update my CLAUDE.md file?

Update it whenever your design system changes: new colors, revised typography scale, added components, or changed conventions. A monthly review works well for most teams. Stale CLAUDE.md files with outdated tokens cause more confusion than having no file at all, because Claude trusts the file over its own judgment.

What is the difference between CLAUDE.md and Claude Code Skills?

CLAUDE.md contains project-specific configuration. Skills (SKILL.md files) contain reusable capabilities that work across projects, like the Anthropic frontend-design skill with 277K+ installs. They complement each other. Your CLAUDE.md encodes your specific design system. Skills encode general design knowledge and workflows.

Will CLAUDE.md slow down Claude Code?

No. CLAUDE.md adds a small amount of text to Claude's context window, which has no meaningful impact on response speed. A 200-line CLAUDE.md file uses roughly 1-2% of Claude's available context. The time saved by not repeating instructions far outweighs any marginal context cost.

How much does output quality improve with a CLAUDE.md file?

Based on our experience across client projects, a well-structured CLAUDE.md improves first-pass design accuracy by 60-80%. The biggest gains come from typography and color token compliance, where Claude goes from guessing to exact implementation. Layout and interaction patterns still require iteration, but starting from the correct visual foundation reduces total design-to-code time significantly.

Building a design project with Claude Code? Talk to our team. We will set up your CLAUDE.md, design system, and AI workflow so your output matches your Figma from the first prompt.

If you're building a product and want a second opinion on your UX, talk to 925Studios. We work with SaaS, fintech, healthtech, web3, and AI startups.

See our work or book a free 30-minute call.

Follow us on Instagram and YouTube for design breakdowns and case studies.