How to Write a CLAUDE.md That Makes AI Code On-Brand

You ask Cursor to build a pricing card. It spits out a generic component using bg-blue-600, rounded-3xl, standard Inter font, and heavy drop shadows. Your actual app uses bg-emerald-500, sharp corners, Geist Sans, and flat borders. You spend the next 10 minutes manually fixing Tailwind classes across 45 lines of code. Multiply that by 20 components a day, and you are wasting hours translating AI output into your actual brand identity.

AI coding assistants default to their training data. When Claude or Cursor writes a React component, it relies on the most statistically common UI patterns on GitHub circa 2023. Unless you intervene, your codebase will look like a generic SaaS template.

You fix this by writing a CLAUDE.md file.

The System Prompt Injection Mechanism

When you place a file named CLAUDE.md (or .cursorrules for Cursor specifically) in the root directory of your project, the AI assistant automatically reads it and prepends its contents to your system prompt.

This file acts as the permanent context for your codebase. Instead of typing "use our brand primary color, which is a dark purple, and make sure buttons have sharp corners" in every single chat interaction, you define those constraints once.

LLMs process design instructions differently than human developers. A human understands "make it look playful." An LLM interprets "playful" by hallucinating rounded corners, bright pinks, and bouncing animations. You must translate aesthetic preferences into deterministic CSS rules and Tailwind classes.

Mapping Design Tokens to LLM Directives

Your CLAUDE.md file needs to bridge the gap between your design system and the AI's code generation engine. You do this by explicitly mapping semantic concepts to hardcoded values.

1. Color System Definitions

Never give an LLM raw hex codes in your system prompt if you are using Tailwind. If you tell Claude "our primary color is #0F172A," it will generate inline styles like style={{ backgroundColor: '#0F172A' }} or arbitrary Tailwind values like bg-[#0F172A]. This breaks your design system.

Instead, define your 7 color shades (50-950) in your tailwind.config.ts or as CSS variables, and instruct the AI to strictly use the semantic class names.

Here is the exact mapping you need in your codebase:

/* src/app/globals.css */
@layer base {
  :root {
    --brand-50: 240 100% 98%;
    --brand-500: 243 75% 59%;
    --brand-900: 242 47% 34%;
    --surface: 0 0% 100%;
    --surface-muted: 240 5% 96%;
  }
  .dark {
    --brand-50: 242 47% 34%;
    --brand-500: 243 75% 59%;
    --brand-900: 240 100% 98%;
    --surface: 240 10% 4%;
    --surface-muted: 240 5% 10%;
  }
}
In your `CLAUDE.md`, you reference these mapped variables explicitly. Tell the AI exactly which Tailwind prefix corresponds to which use case.
 
### 2. Typography and Spacing Constraints
 
LLMs love to mix fonts and apply inconsistent padding. You must lock down the utility classes it is allowed to use. If your brand uses a strict 4px baseline grid, explicitly ban the use of arbitrary spacing values. 
 
If you use a specific font stack, map it out. Tell the AI that headers use `font-display` and body copy uses `font-sans`. 
 
### 3. Component Architecture Patterns
 
If you use shadcn/ui, Radix, or Headless UI, the AI needs to know. Otherwise, it will attempt to build custom dropdowns from scratch using raw React state and `div` elements, introducing accessibility bugs and bloating your file size.
 
## The Production-Ready CLAUDE.md Template
 
Here is a complete, copy-pasteable `CLAUDE.md` file designed for a modern React/Tailwind project. It enforces strict brand constraints, prevents hallucinated hex codes, and standardizes component structure.
 
```markdown
You are an expert frontend engineer building components for our SaaS platform. You must strictly adhere to the following design system and brand guidelines. Do not deviate from these rules or invent new utility classes.
 
## 1. Color System
We use CSS variables mapped to Tailwind classes. NEVER use arbitrary hex values (e.g., `bg-[#FF0000]`). NEVER use default Tailwind colors like `blue-500` or `red-500` for primary UI elements.
 
- **Primary Brand**: Use `bg-brand-500` for primary buttons and active states. Use `text-brand-600` for prominent links.
- **Surfaces**: Use `bg-surface` for main backgrounds and `bg-surface-muted` for secondary backgrounds (cards, sidebars).
- **Text**: Use `text-foreground` for primary text and `text-muted-foreground` for secondary text.
- **Borders**: Use `border-border` for all structural lines. Do not use `border-gray-200`.
 
## 2. Typography
- Headers (h1, h2, h3): Must use the `font-display` class and `tracking-tight`. 
- Body copy: Must use `font-sans`.
- Font weights: Use `font-medium` for buttons and labels. Use `font-bold` only for primary marketing headers. Never use `font-black`.
 
## 3. Shape & Spacing
- **Border Radius**: Our brand is sharp and technical. NEVER use `rounded-full` or `rounded-3xl` unless building an avatar. All cards, buttons, and inputs must use `rounded-sm`.
- **Shadows**: We use a flat design system. Do not use `shadow-md` or `shadow-lg`. For elevation, use a 1px border (`border border-border`) instead of a drop shadow.
- **Spacing**: Stick to the 4px grid. Use `p-4`, `p-6`, or `p-8`. Avoid odd spacing values like `p-3` or `p-5`.
 
## 4. Component Architecture
- We use `shadcn/ui`. When asked to build a button, input, dialog, or dropdown, ALWAYS import the component from `@/components/ui/` rather than building it from native HTML elements.
- Example: `import { Button } from "@/components/ui/button"`
- Do not write custom CSS or inline styles under any circumstances.
 
## 5. Copywriting & Tone
- When generating placeholder text, use a direct, technical tone. 
- Do not use exclamation marks.
- Keep button copy actionable and short (e.g., "Deploy Project" instead of "Click here to deploy your new project").

You can spend 3 hours tweaking these variables manually and writing this documentation, or you can use a tool to automate the boilerplate. When you generate a brand with OneMinuteBranding, the $49 one-time package outputs your CSS variables, your tailwind.config.ts, and a pre-configured CLAUDE.md tailored exactly to the visual identity you just created. The generation takes 60 seconds, and you drop the files directly into your repository.

Vague vs. Deterministic Prompting

The difference between a failing system prompt and a successful one is precision. LLMs process tokens, not visual concepts. Look at how standard developer requests fail compared to deterministic instructions.

Enforcing Dark Mode Constraints

Dark mode is a notorious failure point for AI generation. If you don't provide explicit instructions, Claude will manually hardcode dark:bg-gray-900 and dark:text-white onto every single div. This bloats your markup and ruins your centralized CSS variable architecture.

You must explicitly ban the use of dark: variants in your CLAUDE.md if you are using CSS variables for theme inversion.

Add this specific block to your ruleset:

## Dark Mode Implementation
- We use CSS variables for theming. The background and text colors automatically invert based on the `.dark` class on the root element.
- STRICT RULE: NEVER use Tailwind `dark:` variants (e.g., `dark:bg-gray-800`).
- Always use semantic variables (e.g., `bg-surface`) which handle their own dark mode state.

This single rule reduces the token count of AI-generated components by roughly 30% and ensures your dark mode remains perfectly synchronized with your global stylesheet.

Structuring the AI's Brain for File Organization

Brand consistency extends beyond the visual layer. It includes how your codebase is organized. If you ask Cursor to "create a new pricing section," you need it to place the file in the correct directory, use the correct naming conventions, and export it properly.

Add a file structure directive to your CLAUDE.md:

## File Structure & Naming
- Page components belong in `src/app/(routes)/[route]/page.tsx`.
- Reusable UI blocks belong in `src/components/blocks/`.
- Always use PascalCase for component filenames (e.g., `PricingCard.tsx`).
- Always use named exports, never default exports.

When you enforce this, you eliminate the friction of moving files and renaming components after the AI generates them. You copy, paste, and ship.

Testing Your Brand Implementation

Do not write your CLAUDE.md file and blindly assume it works. You must run a zero-shot component test to verify the LLM is correctly parsing and applying your design tokens.

Open a new chat in Cursor or Claude. Ensure the context window is entirely empty, except for the automatic inclusion of your CLAUDE.md.

Send this exact prompt: Build a login card component. Include an email input, a password input, and a submit button.

Analyze the output immediately.

1. Did it use bg-brand-500 for the submit button, or did it default to bg-blue-600?
2. Did it use rounded-sm, or did it hallucinate rounded-xl?
3. Did it import the inputs from @/components/ui/input, or did it write native <input className="..."> tags?

If the AI fails any of these checks, your CLAUDE.md instructions are either too ambiguous or conflicting with another rule. Locate the failure point, make the instruction more aggressive (use ALL CAPS for strict negative constraints like "NEVER use default tailwind colors"), and run the test again.

FAQ

Does CLAUDE.md consume my context window?

Yes. Every word in your CLAUDE.md file is counted against your token limit for every single prompt you send. A highly optimized file like the one above consumes roughly 350-400 tokens. In a model with a 200k context window, this is a negligible cost (0.2%) for a massive increase in output accuracy. Keep the file under 1000 words.

Should I use CLAUDE.md or .cursorrules?

If you only use Cursor, .cursorrules is the native standard and offers slightly better integration with Cursor's specific features. If you use the Claude web interface alongside your IDE, or if your team uses a mix of Cursor, Copilot, and web-based Claude, use CLAUDE.md. Both standard formats are widely recognized by modern AI tooling.

Why is the AI still hallucinating colors even with the file?

LLMs suffer from recency bias. If you paste a code snippet from a Tailwind UI template that contains bg-indigo-600, the AI will often mimic the style of the pasted code rather than adhering to the CLAUDE.md rules. When asking the AI to refactor an existing component that violates your brand guidelines, you must explicitly add: "Refactor this component to strictly match the color system defined in CLAUDE.md."

How do I handle multiple brands in a monorepo?

Do not put a global CLAUDE.md at the root of a monorepo if the apps have different visual identities. Place a specific CLAUDE.md or .cursorrules file inside the root directory of each individual application (e.g., apps/web/.cursorrules and apps/admin/.cursorrules). The AI assistant reads the rules file closest to the active working directory.

Create your CLAUDE.md file right now. Open your code editor, create the file at the root of your project, and paste in the template provided above. Replace the color variables with your exact Tailwind configuration, adjust the border radius to match your preference, and save it. Open a fresh AI chat window, prompt it to build a settings panel, and watch it generate code that actually looks like your product.