CLAUDE.md for designers: turn Claude Code into a design partner

Most product designers using Claude Code spend the first ten minutes of every session re-explaining the same things: who the product is for, which components already exist, what the brand actually sounds like, and which patterns are explicitly off-limits. That repetition is not just expensive in tokens—it is the reason AI output keeps drifting toward generic SaaS templates instead of the product you are actually trying to ship. The fix is a CLAUDE.md template for product designers: a small, structured file that turns Claude Code from a clever autocomplete into a design partner that loads your taste, your rules, and your anti-patterns before the first prompt is ever typed. This post walks through the exact blocks that file needs and gives you the complete template to copy—no downloads, no repository to clone, everything you need is below.

What CLAUDE.md actually is, and why designers should care

CLAUDE.md is the persistent context file Claude Code reads at the start of every session. It sits at the root of your project, gets loaded automatically, and stays in scope for the entire conversation. Think of it as the agent’s onboarding doc—except instead of being read once and forgotten, it gets re-read every time the agent boots. The equivalent in other tools is AGENTS.md for Cursor and Codex; the file name varies, the function is identical: structured, opinionated context that the agent does not have to be reminded of.

For engineers, the pattern is familiar. CLAUDE.md files in the wild are dense with build commands, deploy hooks, test runners, and folder conventions. That works for engineering because the work product is mostly verifiable code. Product design is different. The signal is taste, hierarchy, interaction quality, content tone, and judgment about when to break a pattern. None of that lives in a package.json. If you want AI to ship work that looks designed, you have to encode the design layer in the same place engineering encodes its layer—and most designers have not done that yet.

This is the same lens I covered in AI agent infrastructure beyond prompt engineering: individual prompts are the smallest unit of leverage. The infrastructure around the prompt—skills, scripts, persistent memory—is where the compounding returns live. CLAUDE.md is the persistent-memory slot for design judgment.

Why most CLAUDE.md files fail product design work

Walk into any AI-first codebase and you will find a CLAUDE.md. Read it carefully and you will notice what is missing: visual hierarchy, density rules, layout intent, content voice, accessibility floors, brand-safe color usage, and the specific patterns this product avoids on purpose. The file was written by engineers, for engineers. It produces code that lints, tests, and deploys—and looks like every other AI-generated SaaS app on the internet.

That visual sameness is not a model problem. It is a context problem. When an agent is asked to “build a settings screen” without design context, it pattern-matches against the most common shape of a settings screen in its training data: card, header, toggles, save bar. The output is technically correct and visually anonymous. The only way to push it toward your product is to give it the design decisions up front—what density, what typography scale, what the empty state looks like, which interaction patterns you have explicitly rejected, and what “good” actually means for this surface.

The failure mode I see most often is designers treating CLAUDE.md as optional documentation. It is not documentation. It is the operating contract between you and the agent. If you do not write it, the agent writes one for itself based on whatever it has seen most. That default is almost never what your product needs.

CLAUDE.md is not documentation. It is the operating contract between you and the agent — and if you do not write it, the agent writes one for itself.

What does a designer’s CLAUDE.md actually need to contain?

Seven blocks. Each one maps to a specific failure mode in AI-assisted design output. The template below includes all of them; the work is filling them in with answers that are true for your product, not generic ones.

1. Project context. Product type, audience, primary user tasks, and the non-negotiable principles that shape every decision. This is the section that tells the agent what kind of product it is working on. “B2B SaaS for finance teams—density matters, data legibility is non-negotiable, marketing-style hero patterns are wrong here” is infinitely more useful than “a web app.” The first 30 lines of the file shape behavior the most; do not waste them on platitudes.

2. Hard rules. Things the agent must never do. “Never use arbitrary Tailwind values—always reference theme tokens.” “Never add a hover state without a focus-visible equivalent.” “Never invent a new component when an existing one can be composed.” Hard rules are the floor. They prevent the worst categories of drift without requiring you to police every interaction.

3. Preferences. Things the agent should default to when there is no explicit instruction. Spacing scale, type ramp, motion easing, copy voice, error tone, empty-state pattern. Preferences are softer than rules—they bend when context demands it—but they keep output inside your visual grammar by default.

4. Anti-patterns. This is the block most designers forget, and it is the one with the highest leverage. AI defaults toward the most common visual idioms in its training data: card-heavy dashboards, gradient hero sections, three-column feature grids, “modern SaaS” type scales. If your product is dense, technical, or deliberately uncomfortable, you have to name those defaults and rule them out explicitly. “We do not use card-based dashboards.” “We do not use hero gradients.” “Do not propose marketing-style layouts inside the product.” The agent will not infer your refusals from your principles—you have to write them down.

5. Success criteria. Outcome-oriented checks the agent applies before declaring work done. Accessibility floor (WCAG AA), responsive behavior, keyboard navigation, content variability (long copy, missing data, error states), and any product-specific gates. Success criteria turn the agent from “generated something plausible” into “verified it meets the bar.”

6. Interactive intake. A short, scripted onboarding the agent runs when you start a project where context is missing. This is what makes the template usable on day one of a new repo: the agent asks five to ten targeted questions—product, audience, stack, primary surfaces, design system status—and writes the answers into CLAUDE.md and supporting docs. No more staring at a blank file wondering what to put in it.

7. Routing to deeper docs. A pointer table that tells the agent where to look when it needs more detail. docs/design-system.md for tokens, components, and spacing. docs/ux-principles.md for flow, hierarchy, and progressive disclosure rules. docs/intake-workflow.md for the interactive setup itself. The root file stays short; the depth lives in the docs.

These seven blocks are the spine of the file. Everything else—the supporting docs and any scoped per-surface files—exists to keep the root prompt focused while still giving the agent a path to deeper context when a task warrants it.

The complete CLAUDE.md template, ready to copy

Here is the full file. Copy it into a CLAUDE.md at the root of your project, then replace every bracketed placeholder with answers that are true for your product. The comments explain what each block is for; you can delete them once you have filled in your own content. This is the whole template—nothing is hosted elsewhere.

# CLAUDE.md — Design operating contract

> This file is loaded at the start of every Claude Code session. It encodes the
> design judgment for this product so the agent ships work that looks designed,
> not generic. Keep it under ~200 lines; push depth into docs/ (see Routing).

## 1. Project context

- **Product:** [e.g. B2B observability platform for SRE teams]
- **Audience:** [who uses it, their context, their constraints]
- **Primary user tasks:** [the 3–5 jobs the product exists to do]
- **Non-negotiable principles:**
  1. [e.g. Density and data legibility win over visual polish]
  2. [e.g. Every surface must be keyboard-navigable]
  3. [e.g. Content is the interface; chrome stays out of the way]

## 2. Hard rules — never do these

- Never use arbitrary Tailwind values; always reference theme tokens.
- Never add a hover state without a focus-visible equivalent.
- Never invent a new component when an existing one can be composed.
- Never ship copy that leads with an apology; lead with the action.
- [Add your own non-negotiables here.]

## 3. Preferences — defaults when no instruction is given

- **Spacing:** [your scale, e.g. 4px base, 8/12/16/24/32 steps]
- **Type ramp:** [your scale and intended hierarchy]
- **Motion:** [easing + duration defaults, when to animate]
- **Copy voice:** [tone, person, sentence length, error tone]
- **Empty / loading / error states:** [the default pattern for each]

## 4. Anti-patterns — explicitly rejected defaults

> The highest-leverage block. Name the generic idioms the model reaches for so
> it stops proposing them.

- We do not use card-based dashboards.
- We do not use hero gradients or marketing-style layouts inside the product.
- We do not use three-column feature grids.
- [Add the drift categories you keep rejecting in review.]

## 5. Success criteria — checks before work is "done"

- Meets WCAG AA contrast and has visible focus states.
- Works at all breakpoints; no horizontal scroll on mobile.
- Handles content variability: long copy, missing data, error states.
- Keyboard-navigable end to end.
- [Add product-specific gates here.]

## 6. Interactive intake — run when context is missing

When starting a project where this file is incomplete, ask 5–10 targeted
questions (product, audience, stack, primary surfaces, design-system status),
then write the answers back into this file and the docs/ files below. Confirm
the plan with me before generating any code or content.

## 7. Routing to deeper docs

| Need                              | Read this file            |
| --------------------------------- | ------------------------- |
| Tokens, components, density       | docs/design-system.md     |
| Flow, hierarchy, disclosure rules | docs/ux-principles.md     |
| The interactive setup script      | docs/intake-workflow.md   |

That single file is enough to change how every session starts. The three docs/ files referenced in the routing table are optional at first—create them when the root file starts to feel crowded.

Progressive disclosure: keeping the root prompt short and the docs deep

The single most common failure I see with CLAUDE.md is bloat. Designers who learn the pattern keep adding to the root file until it is 800 lines of mixed rules, preferences, color values, component APIs, and product trivia. At that size, the agent loses the signal in the noise—and you pay the token cost on every single session.

The fix is progressive disclosure. Keep the root CLAUDE.md under 200 lines. Move depth into supporting documents the agent loads only when relevant.

The routing table in the template points to three:

• docs/design-system.md — tokens, components, layout density, states, accessibility patterns. Loaded when the agent is building or modifying UI.
• docs/ux-principles.md — flow design, hierarchy, interaction quality, progressive disclosure rules, AI output review checklist. Loaded when the agent is making product decisions, not just rendering them.
• docs/intake-workflow.md — the interactive onboarding script. Loaded once per new project.

You create these the same way you created the root file: a markdown heading per topic, your real content underneath. There is nothing to install—they are just plain files the agent reads on demand.

You can also scope CLAUDE.md files by directory. The agent respects the nearest relevant CLAUDE.md, so a /app/CLAUDE.md overrides the root for frontend work, and /app/dashboard/CLAUDE.md overrides both inside the dashboard surface. This is how you encode that the marketing site uses one density and type scale and the analytics dashboard uses another—without forcing every rule into one file.

This is the same operating model behind portable design systems for agentic workflows: structured, scoped, versioned context that survives tool changes and team turnover. Your CLAUDE.md is the design-system layer for the AI agent itself.

Interactive intake: a starter prompt that adapts to your product

The other failure I see is the empty-file problem. Designers copy the blocks, open CLAUDE.md, and stare at the headings. Filling it in feels like writing a brand book from scratch.

Block 6 above solves this with an interactive intake. Once the file is in your project root, start a session with one of two messages:

Use this as an interactive setup prompt. First infer what you can from
this repository, then ask only for missing information that affects the plan.

Or, if there is no repository yet:

Use this as an interactive setup prompt. I want to answer a short guided
intake instead of having you inspect a repository.

The agent then does the work it is best at: reading what it can, asking only about the gaps that change the plan, and producing a draft CLAUDE.md plus a list of files to create or update. You review the plan before any code or content lands. This is the same discipline behind spec-driven development for designers in the age of AI: you specify intent, the agent surfaces gaps, you align before production. CLAUDE.md is just the persistent, project-level version of that contract.

The intake is not a one-time event. As the product matures and patterns drift, you re-run targeted portions of it—“add an anti-patterns block based on the last three reviews where AI output missed the mark”—and the file evolves with the work. The file is alive.

What changes when product designers ship this layer

The behavioral shift is concrete and shows up within the first few sessions.

Four shifts you feel within a week

Output starts on-brand

The agent’s first draft of a screen, component, or content block looks like your product, not a generic template. Review cycles move from color values and spacing to hierarchy and storytelling.

Handoffs get cleaner

Engineering reads the same CLAUDE.md the agent reads. Cross-functional context becomes a shared file, not a Slack thread. Disagreements about “what we said the pattern was” disappear because the pattern is in version control.

Junior collaboration gets safer

A junior designer or PM can ask the agent for a draft and trust that the output respects the system. You stop being the bottleneck for “is this on-brand?” because the system answers most of those questions before the work reaches you.

Anti-patterns stop reappearing

Generic dashboards, gradient heroes, marketing patterns inside the product — the drift categories you used to flag every other review stop landing in the work because the agent rules them out before generating.

This is the practical version of the principle I argued in AI-assisted design workflows that actually work: AI is a multiplier on intent that is well-specified, and CLAUDE.md is where that intent lives across every session. It is also the enablement model from shipping landing pages with Claude Code and GitHub — distributed contribution inside design-led guardrails.

For founders, the visible effect is speed-to-market without brand fragmentation. For VPs, it is delivery consistency across an AI-assisted team. For designers, it is the realization that the agent can finally be trusted with the parts of the job that used to require constant supervision—and that the time saved goes back into the parts of design that still demand human judgment.

How to adapt this template for your team in one afternoon

You do not need a quarterly initiative to ship this. The full adoption fits in a focused afternoon.

1. Create the file structure at the root of your project. Add a CLAUDE.md and a docs/ folder with the three supporting files described above. Add scoped CLAUDE.md files inside the surfaces where you want different behavior—copy the shared structure and override only what diverges.

2. Rewrite the first 30 lines. Replace the generic project overview with your actual product type, audience, primary user tasks, design constraints, and the three or four non-negotiable principles your work is built on. Be specific. “B2B observability for SRE teams; density and data legibility win over visual polish” beats “we build great products.”

3. Extract hard rules from what you already have. Walk your design system docs, critique notes, and recent PR reviews. Anything you have said more than twice—“never use arbitrary spacing values,” “all components ship with focus states,” “error messages lead with the action, not the apology”—is a hard rule. Pull it into the file verbatim.

4. Add anti-patterns as drift appears. Do not try to predict every failure mode on day one. After the first week of AI-assisted work, log the categories of output you rejected. Those rejections become the anti-patterns block. The list grows fastest in the first month and stabilizes after that.

5. Layer scoped CLAUDE.md files where surfaces diverge. Marketing site, product app, internal dashboard, admin tooling—if the design rules are meaningfully different, give each surface its own scoped file. Copy the same seven-block structure into a /app/CLAUDE.md or /app/dashboard/CLAUDE.md and override only what is local; the agent respects the nearest relevant file. The root file holds what is shared; the scoped files hold what diverges. This is the same architecture that keeps real design systems coherent across multiple products.

By the end of an afternoon you will have a CLAUDE.md that is opinionated, project-specific, and ready to load on every session. The compounding starts immediately. The rest is maintenance—prune what stops being true, add what you keep repeating, evolve the file as the product evolves.

You do not need to download anything to start—the template above is the whole thing. Copy it into a CLAUDE.md at your project root, rewrite the placeholders for your product, and ship the AI operating layer your team has been missing.

Key Takeaways

• CLAUDE.md is the persistent context Claude Code loads every session—if you do not write the design layer into it, the agent fills the gap with generic defaults from its training data.
• A designer’s CLAUDE.md needs seven blocks: project context, hard rules, preferences, anti-patterns, success criteria, interactive intake, and routing to deeper docs.
• Anti-patterns are the highest-leverage section and the one most designers skip—name the visual defaults you reject explicitly so the agent stops proposing them.
• Use progressive disclosure: keep the root file under 200 lines and push depth into docs/ and scoped per-directory CLAUDE.md files for product, marketing, and internal surfaces.
• Add an interactive intake prompt to the template to turn the empty-file problem into a guided onboarding the agent runs against your repository.