5.1 What CLAUDE.md Is and Why Designers Need It

What CLAUDE.md Is and Why Designers Need It

Every Claude Code session needs a reliable source of design truth. CLAUDE.md is the project file that carries your design decisions from one session to the next.

You have built prototypes. You have learned to prompt for design outcomes. You can generate a button, a card, a navigation bar. But you may have noticed a problem: the output is inconsistent. Session to session, Claude picks different blues, different border radii, different font sizes. The button you generated on Tuesday does not match the one you generated on Thursday.

This happens when the session has no controlled project instructions. Claude Code may have user-level or product-level memory features, but those are not a substitute for a checked-in project source of truth. Without one, Claude defaults to generic design decisions, and "generic" changes every time.

CLAUDE.md fixes this. It is a plain text file that lives in your project folder. Claude reads it at the start of every session, before you type your first prompt. Think of it like your brand style guide in Figma — a document that defines your colors, typography, spacing, and component rules. Except this one is read by Claude before every conversation, not by a human developer.

CLAUDE.md is not a single global file. Claude loads multiple files, layered by scope, and concatenates them. Your personal preferences live in one file. Team conventions live in another. Project-specific rules live in a third.

All discovered files load and merge. Claude walks up the directory tree, gathering instructions from each level. The content is additive, not overriding. If your user-level file says "use Inter" and your project file says "use Inter," they agree. If they conflict, you will see inconsistent behavior.

5.2 Creating Your First CLAUDE.md

Creating Your First CLAUDE.md

You do not write CLAUDE.md from scratch. You generate a starting point and refine it with your design decisions.

The fastest way to create a CLAUDE.md is to let Claude build one for you. Open Claude Code in your project folder and run the init command:

/init

Claude analyzes your project structure, detects your build system, identifies your test framework, and produces a starter CLAUDE.md. It will not be design-specific, because Claude does not know you are a designer yet. That is your job: take the generated file and add your design system.

Here is what a starter design CLAUDE.md looks like. Use it as a working example, but generate the final values from your real token source when possible: Figma variables, Style Dictionary, Tokens Studio, a theme file, or your component library. Manually copied values drift; generated values can be reviewed and refreshed.

# Design System

## Colors
- Primary: #4F46E5 (indigo)
- Secondary: #7C3AED (purple)
- Accent: #F59E0B (amber)
- Background: #FFFFFF (light) / #111827 (dark)
- Text: #1A1A1A (primary) / #6B7280 (muted)
- Error: #DC2626, Success: #059669, Warning: #D97706

## Typography
- Headings: Inter, bold (700)
- Body: Inter, regular (400)
- Mono: JetBrains Mono, for code
- Scale: 12 / 14 / 16 / 20 / 24 / 32 / 48px

## Spacing
- Base unit: 4px
- Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64px
- Component padding: 12px (compact), 16px (default), 24px (spacious)

## Border radius
- Small: 4px (inputs, tags)
- Medium: 8px (buttons, cards)
- Large: 16px (modals, dialogs)
- Full: 9999px (pills, avatars)

## Components
- Use kebab-case for CSS classes: .btn-primary, .card-header
- All interactive elements need hover, focus, and disabled states
- Buttons: min-height 44px for touch targets
- Use CSS custom properties, not hardcoded values

# Workflow
- Always use style.css for styles unless I specify otherwise
- Generate responsive markup by default (mobile-first)
- Include hover and focus states for all interactive elements

That is 35 lines. It fits comfortably under the 200-line limit that Anthropic recommends. It covers colors, typography, spacing, border radius, and basic component rules. Every section is something Claude needs to know to produce consistent design output.

What you include matters as much as what you leave out. Claude already knows standard CSS, common layout patterns, and responsive design conventions. You do not need to teach it those things. You need to teach it the things it cannot infer: your specific brand choices.

The pruning test is simple: for each line, ask yourself, "Would removing this cause Claude to make mistakes?" If the answer is no, cut it. If Claude already uses Inter without being told, you do not need a rule for Inter. If Claude keeps picking the wrong blue, you need a rule for your blue.

5.3 Design Tokens and Brand Colors

Design Tokens and Brand Colors

Design tokens are the named values that carry your brand from Figma to code. CLAUDE.md is where you write them down so Claude uses them.

If you use Figma Variables, Tokens Studio, or any design token system, you already think in tokens. A token is a design decision given a name. Instead of #4F46E5, you write color-primary. Instead of 16px, you write space-4. The name stays the same even if the value changes. That is the whole point.

In CSS, tokens are implemented as custom properties. You define them once in a :root block and reference them everywhere else. When Claude reads your CLAUDE.md and sees "Primary: #4F46E5," it generates CSS that uses --color-primary: #4F46E5 and references var(--color-primary) throughout the component. That is the bridge between your design decision and the code Claude produces.

:root {
  /* Colors */
  --color-primary: #4F46E5;
  --color-secondary: #7C3AED;
  --color-accent: #F59E0B;
  --color-bg: #FFFFFF;
  --color-bg-dark: #111827;
  --color-text: #1A1A1A;
  --color-text-muted: #6B7280;
  --color-error: #DC2626;
  --color-success: #059669;
  --color-warning: #D97706;
}

When your CLAUDE.md lists these colors, Claude references them by name in generated CSS instead of hardcoding random values. The difference is immediate and measurable. Here is what happens when you prompt "Create a primary button" before and after encoding your color tokens:

.btn-primary {
  background-color: var(--color-primary);
  color: #FFFFFF;
  border-radius: var(--radius-md);
  padding: var(--space-3) var(--space-6);
  font-family: var(--font-body);
  font-size: var(--font-size-base);
}

.btn-primary {
  background-color: #3B82F6;
  color: white;
  border-radius: 6px;
  padding: 10px 20px;
  font-family: system-ui, sans-serif;
  font-size: 14px;
}

The version without CLAUDE.md uses Tailwind's default blue, a random border radius, and system-ui as the font. None of these match the brand. The version with CLAUDE.md uses the exact tokens you defined. Same prompt, different results, because Claude read your design decisions before starting.

Each token type has a specific format in CLAUDE.md and a specific way Claude applies it in generated code. Here is the reference:

For color systems with light and dark modes, encode both variants in CLAUDE.md:

## Colors
- Primary: #4F46E5 (light) / #818CF8 (dark)
- Background: #FFFFFF (light) / #111827 (dark)
- Text: #1A1A1A (light) / #F9FAFB (dark)
- Use prefers-color-scheme media query for auto-switching
- Dark mode should reduce saturation on accent colors

Claude will generate both the :root and @media (prefers-color-scheme: dark) blocks when it encounters these dual values. You can also ask Claude to generate a toggle-based dark mode using a .dark class on the <html> element if your project prefers manual control.

The same token approach applies to your full color palette. Semantic colors — error, success, warning, info — should be explicit. Claude defaults to common associations (red for error, green for success) but may not pick your specific shades.

5.4 Typography and Spacing

Typography and Spacing

Typography and spacing are where design systems live or die. Encode them as scales, not individual values.

A type scale is a series of font sizes that relate to each other by a consistent ratio. In Figma, you might define this as text styles: "Caption / 12px," "Body / 16px," "H3 / 24px." In CLAUDE.md, you write the same information in a format Claude can parse.

## Typography
- Headings: Inter, bold (700)
- Body: Inter, regular (400)
- Mono: JetBrains Mono, monospace, for code
- Scale: 12 / 14 / 16 / 20 / 24 / 32 / 48px
- Line height: 1.5 for body, 1.2 for headings
- Letter spacing: -0.025em for headings over 24px

When Claude reads this, it maps your scale to CSS custom properties:

:root {
  --font-heading: 'Inter', sans-serif;
  --font-body: 'Inter', sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
  --font-weight-heading: 700;
  --font-weight-body: 400;
  --font-size-xs: 12px;
  --font-size-sm: 14px;
  --font-size-base: 16px;
  --font-size-lg: 20px;
  --font-size-xl: 24px;
  --font-size-2xl: 32px;
  --font-size-3xl: 48px;
  --line-height-body: 1.5;
  --line-height-heading: 1.2;
}

Spacing follows the same pattern. Define a base unit and a scale. In Figma, this is your auto-layout spacing. In CSS, it is padding, margin, and gap values. The scale should be a multiplier of your base unit.

## Spacing
- Base unit: 4px
- Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64px
- Component padding: 12px (compact), 16px (default), 24px (spacious)
- Section spacing: 64px between major sections
- Card internal padding: 16px (mobile), 24px (desktop)

The component padding line is worth calling out. Without it, Claude will choose padding that looks reasonable in isolation but does not match your design system. By specifying compact, default, and spacious variants, you give Claude a choice that always lands within your system.

:root {
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-6: 24px;
  --space-8: 32px;
  --space-12: 48px;
  --space-16: 64px;
}

Notice the naming convention: --space- followed by the value divided by the base unit. --space-4 is 16px (4 times 4px). This is the same convention used by Tailwind CSS and most design token systems. If your project uses Tailwind, your CLAUDE.md should specify that Claude should use Tailwind spacing utilities (p-4, gap-6) instead of raw CSS custom properties.

5.5 Component Patterns

Component Patterns

Naming conventions and structural rules are the difference between code that works and code you can maintain.

Design tokens handle colors, spacing, and typography. Component conventions handle structure: how you name things, how you organize HTML, what states every interactive element needs. Without these rules, Claude generates functional code that follows no consistent pattern. With them, the code looks like it came from one person.

Component conventions go into your CLAUDE.md under a ## Components heading:

## Components
- Use kebab-case for CSS classes: .btn-primary, .card-header
- Structure: container > header (optional) > body > footer (optional)
- Interactive elements: always define :hover, :focus-visible, :active, :disabled
- Responsive: mobile-first. Use min-width media queries to scale up
- Touch targets: minimum 44x44px for any clickable element
- CSS class naming (BEM-like):
  - Block: .card
  - Element: .card-header, .card-body, .card-footer
  - Modifier: .card--featured, .card--compact

The BEM-like naming convention is the part that makes the biggest difference. Without it, Claude generates semantic but inconsistent class names. With it, every component follows the same pattern. Compare the output:

<article class="card">
  <header class="card-header">
    <h3 class="card-title">Title</h3>
  </header>
  <div class="card-body">
    <p>Body text</p>
  </div>
</article>

<div class="card">
  <div class="top">Title</div>
  <div class="content">Body text</div>
</div>

The version with conventions uses semantic HTML (<article>, <header>) and follows the BEM naming pattern. The version without conventions uses generic <div> elements and non-descriptive class names. Both render identically. One is maintainable. The other is not.

For interactive components, encode state requirements explicitly:

## Interactive states (IMPORTANT)
- Every button, link, and form control must include:
  - :hover — subtle background change or shadow
  - :focus-visible — outline ring using --color-primary
  - :active — pressed state
  - :disabled — reduced opacity (0.5) and cursor: not-allowed
- Transitions: 150ms ease for all state changes
- Focus rings: 2px solid var(--color-primary), offset 2px

The "IMPORTANT" tag is not decoration. Anthropic's documentation confirms that adding emphasis markers like "IMPORTANT" or "YOU MUST" improves Claude's adherence to specific instructions. Use it sparingly, for rules that Claude tends to skip.

Responsive conventions belong in CLAUDE.md too. Without them, Claude picks breakpoint values at random:

## Responsive
- Mobile-first: use min-width media queries
- Breakpoints: 640px (sm), 768px (md), 1024px (lg), 1280px (xl)
- Navigation collapses to hamburger below 768px
- Grid switches from 1-column to multi-column at 768px
- Padding doubles from mobile to desktop (16px → 32px)

These breakpoint values come from Tailwind's defaults. If your project uses different breakpoints, specify them. The point is to fix the values so Claude does not invent new ones each session.

When you ask Claude to build a component that references your CLAUDE.md conventions, the output carries through every level — HTML structure, CSS class names, state definitions, and responsive behavior. That is the compound value of CLAUDE.md. Each rule reinforces the others.

5.6 Maintaining Your CLAUDE.md Over Time

Maintaining Your CLAUDE.md Over Time

CLAUDE.md is a living document. An outdated CLAUDE.md is worse than no CLAUDE.md because it teaches Claude the wrong things.

You wrote your CLAUDE.md. It works. Sessions are consistent. Buttons come out right. But your design system evolves. Colors change. Spacing adjusts. New components get added. If CLAUDE.md does not keep up, Claude keeps generating the old version.

Treat CLAUDE.md like code: review it when things go wrong, prune it regularly, and test changes by observing whether Claude's behavior actually shifts. Anthropic's guidance is clear on this: "Treat CLAUDE.md as the place you write down what you would otherwise re-explain." Add to it when Claude makes the same mistake a second time, when a code review catches something Claude should have known, or when you type the same correction you typed last session.

The /memory command is your diagnostic tool. It shows every CLAUDE.md file loaded in the current session, plus Claude's own auto-memory notes. Use it when output feels inconsistent — you may discover that an old user-level CLAUDE.md is conflicting with your project-level one.

/memory

When CLAUDE.md grows beyond what fits in a single file, you have two escape valves. The first is path-scoped rules. You create files in .claude/rules/ with a YAML frontmatter that specifies which files they apply to:

---
paths:
  - "src/components/**/*"
  - "**/*.component.*"
---

# Component Rules
- Every component gets its own file
- Include JSDoc comments with @component and @props tags
- Export both the component and its props interface
- Write a usage example in the same directory

This file only loads when Claude works with component files. The rest of the time, it stays out of context. Think of it like Figma's component documentation: available when you need it, invisible when you do not.

The second escape valve is skills. Skills are loaded on demand, not every session. They are the right place for large reference material: full brand guidelines, icon library references, animation specs, or detailed component documentation. The rule of thumb is simple: if Claude needs it every session, put it in CLAUDE.md. If Claude needs it sometimes, put it in a skill.

Claude also maintains its own notes, stored in auto-memory at ~/.claude/projects/<project>/memory/MEMORY.md. This is separate from your CLAUDE.md. Claude saves observations here, like "this user prefers pnpm over npm." For design-specific rules, CLAUDE.md is more reliable because you control the content. Auto-memory is Claude's best guess about what matters.

Here is a maintenance workflow that works. Run it once a quarter, or whenever you notice output quality dropping:

CLAUDE.md is the most impactful file you will create in your Claude Code workflow. It is the thing that turns an AI code generator into a design collaborator that knows your brand. Write it well, maintain it often, and it compounds in value every session.