---
title: "CLAUDE.md for Design Teams: Teaching AI Your Brand"
description: "How design teams use CLAUDE.md and agent context files to teach AI their brand: tokens, typography, voice, and do/don't rules that keep output on-brand."
date: "2026-07-27"
updated: "2026-07-27"
lang: "en"
tags: ["design systems", "ai workflows", "claude code", "brand guidelines"]
---

# CLAUDE.md for Design Teams: Teaching AI Your Brand

AI coding agents now ship real interfaces: buttons, layouts, copy, entire pages. Whether that output looks like your brand or like generic bootstrap soup depends on one thing: what the agent knows before it starts. A CLAUDE.md file is where that knowledge lives. This post is a design team's guide to writing one.

## What is a CLAUDE.md file?

**CLAUDE.md is a plain-text instruction file, checked into a project's repository, that Claude Code and similar AI agents read automatically at the start of every session.** Think of it as a standing brief: before the agent touches a single file, it has read your rules.

Engineers have used these files for build commands and architecture notes since agentic coding tools appeared. But nothing about the format is engineering-specific. It is a Markdown document. It can hold color tokens, typography rules, tone-of-voice guidance, and accessibility requirements just as easily as it holds test commands.

CLAUDE.md is Claude Code's convention, but it has siblings. **AGENTS.md** is an emerging cross-tool standard read by multiple coding agents. **Cursor rules** (`.cursor/rules` or `.cursorrules`) do the same job for Cursor. GitHub Copilot has `copilot-instructions.md`. The names differ; the idea is identical: a file in the repo that tells the AI how this project works and what its output must respect. Many teams write one canonical document and symlink or mirror it across conventions.

If you have read our companion piece on generic `design.md` files, note the distinction: that post covers standalone design-spec documents you can hand to any tool or human. This one is about the agent context file itself, the file that gets read *automatically, every session, without anyone remembering to paste it in*.

## Why should design teams care about a file in a code repo?

**Because AI agents are already making design decisions in your product, and an unbriefed agent makes them badly.** Every time an engineer asks an agent to "add a settings page" or "write the empty-state copy," the agent chooses colors, spacing, typography, and words. If your brand rules live only in a Figma library and a PDF nobody opens, the agent cannot see them. It will default to Tailwind blue, generic sans-serif hierarchy, and copy that sounds like every other SaaS product.

Designers do not need to write code to write a CLAUDE.md. It is prose and lists. Writing it is closer to writing brand guidelines than to programming, except this version is actually enforced, because it sits directly in the tool's field of view at the moment of creation.

There is a second reason: leverage. A brand deck persuades humans who read it. A CLAUDE.md instructs a machine that never skips the briefing. It is the highest-leverage brand document your team can write, per word, because it is read on every single generation.

## What design knowledge belongs in a CLAUDE.md?

**Everything an agent needs to produce on-brand output without asking: tokens, type, spacing, voice, component conventions, art direction, accessibility, and explicit do/don't rules.** Concretely:

- **Color tokens with actual hex values.** "Use brand blue" is useless to an agent. `--color-primary: #1A4FD8` is executable. List semantic roles (primary, surface, danger) and forbidden uses ("never place primary text on the accent color").
- **Typography rules.** Typefaces, the exact scale (sizes, weights, line-heights), and usage rules: which weight headlines take, whether you ever use italics, casing conventions.
- **Spacing scale.** The base unit and the allowed steps (4/8/12/16/24/32...), so the agent never invents a 13-pixel margin.
- **Tone of voice.** Adjectives alone drift; pair each with an example. "Confident, not boastful: say 'This works,' not 'This revolutionary feature...'"
- **Component conventions.** Naming patterns, variant vocabulary (primary/secondary/ghost, not blue/gray/outline), where components live, and the rule that agents extend existing components before creating new ones.
- **Art-direction keywords.** For image generation and illustration prompts: photography style, lighting, composition rules, forbidden clichés (no handshakes, no lightbulbs, no purple gradients).
- **Accessibility requirements.** Minimum contrast ratios, focus-state rules, touch-target sizes, alt-text expectations. Stated as requirements, not suggestions.
- **Do/don't lists.** The fastest-reading format for an agent. Every recurring mistake you have caught in review belongs here as a "don't."

Keep it tight. An agent context file competes for limited attention; a 400-line brand essay dilutes itself. Rules, values, examples. Cut everything else, and link out to deeper docs the agent can open on demand.

## What does a design-focused CLAUDE.md actually look like?

Here is an annotated snippet for a fictional brand, Fernwood, a plant-care app:

```markdown
## Brand: Fernwood

### Color: use tokens only, never raw hex in components
- --color-moss: #2F5D3A (primary; buttons, links, active states)
- --color-clay: #C4552F (accent; sparingly, one accent element per view)
- --color-paper: #FAF7F0 (default background; never pure white #FFFFFF)
- --color-ink: #1C2321 (body text)
- Don't: moss text on clay, or clay at large sizes. Clay is a spice, not a base.

### Typography
- Headings: "Fraunces", weight 600, tracking -0.01em. Sentence case, never ALL CAPS.
- Body: "Inter", 400, 16px/1.6. Minimum body size: 14px.
- One weight jump max between adjacent hierarchy levels.

### Spacing
- Base unit 4px. Allowed steps: 4, 8, 12, 16, 24, 32, 48, 64. Nothing else.

### Voice
- Warm, plainspoken, lightly botanical. A knowledgeable friend, not a lab.
- Say: "Your monstera looks thirsty." Don't say: "Hydration levels suboptimal."
- Errors are calm and blame-free: "That didn't save. Try again?" No exclamation
  marks in error states, ever.

### Components
- Extend components in src/ui/ before creating new ones. New components require
  a design review; flag them in your summary instead of inventing silently.
- Variants are named primary / secondary / ghost.

### Accessibility (non-negotiable)
- Text contrast ≥ 4.5:1 (verify moss-on-paper for small text before using).
- Every interactive element: visible focus ring (2px, --color-moss), 44px
  minimum touch target.

### Art direction (for generated imagery)
- Natural light, shallow depth of field, real homes. Never studio white.
- Don't: neon, stock-photo smiles, top-down "flat lay" clichés.
```

Notice the pattern: every rule is either a concrete value or a paired example. "Warm" alone would drift; "warm" plus a sample sentence holds.

## How does a CLAUDE.md prevent off-brand AI output?

**By moving your standards from review time to generation time.** Without context, an agent samples from the average of the internet, and the average of the internet is off-brand for everyone. Corrections then happen in review, one pull request at a time, forever.

With a good CLAUDE.md, the agent's first draft starts inside your constraints: the spacing is on the scale, the error message already sounds like you, the contrast check already happened. Reviews shift from "this is the wrong blue" to actual design judgment. You will still review (the file narrows the error space, it does not eliminate it), but the difference in baseline quality is immediate and obvious the first week you try it.

## Why version the file with the codebase?

**Because design decisions that live in the repo persist, travel, and have history, like the code they govern.** When the file is in git:

- A rebrand is a pull request. The diff *is* the changelog: you can see exactly when the accent color changed, who changed it, and why.
- Every engineer, every agent session, every CI environment gets the same brand context automatically. No stale PDFs, no "which deck is current?"
- Disagreements become reviewable. If someone wants to loosen the ALL-CAPS rule, they propose it, and the team decides in review, the same governance code enjoys.

A brand guideline in a repo is a living constraint. A brand guideline in a slide deck is a hope.

## Who owns the file: designers or engineers?

**Both, deliberately.** The file fails when either side owns it alone: engineer-only files are all build commands and no brand; designer-only files drift from what the codebase actually contains.

A structure that works: designers own the brand sections (color, type, voice, art direction, do/don't) and are required reviewers on changes to them; a `CODEOWNERS` entry makes this automatic. Engineers own the technical sections and keep token names in sync with the code. Both sides treat review comments like design critique: when an agent produces something off-brand *despite* the file, the fix is usually a new line in the file, not just a fix in the code. That feedback loop (catch a mistake once, encode the rule, never catch it again) is the entire game.

## How does Things do this?

At Things, every product repo carries agent context files alongside the code, and two of them are design-owned: an art-direction document and a copy document. The art-direction doc holds the visual system: tokens with values, imagery rules, composition keywords for generation tools. The copy doc holds voice: sample sentences, banned phrases, terminology, casing rules, per-surface guidance for errors and empty states.

Our designers review changes to these files the way they review interfaces, and our AI-augmented workflows read them on every session. When an agent output misses, the miss becomes a rule. It is one reason "Design. Code. Mastery." is not a slogan split across departments: we are a studio, not an agency, and the file where design meets code is co-owned like everything else we ship.

## FAQ

**Does CLAUDE.md only work with Claude Code?**
The filename is Claude Code's convention, but the practice is portable. AGENTS.md, Cursor rules, and Copilot instructions serve the same role in other tools. Write one canonical document and mirror it across the conventions your team uses.

**Do I need to know how to code to contribute?**
No. It is a Markdown text file. If you can write brand guidelines, you can write the design sections. Ask an engineer to show you the pull-request flow once; that is the entire technical barrier.

**How long should the file be?**
As short as it can be while still preventing your most common off-brand mistakes. Favor rules, values, and paired examples over prose. Link to deeper documents rather than pasting them in.

**Can it replace our design system documentation?**
No. It is the executive summary your design system delivers to an AI at the moment of creation. The full documentation still matters; the CLAUDE.md is the layer that makes it operational.

**What if the agent ignores a rule?**
It happens. Treat it like critique: tighten the wording, add a concrete example or an explicit "don't," and move the rule higher in the file. Specific and prominent beats long and buried.

## Teach your tools before they ship your brand

Every unbriefed agent session is a small withdrawal from brand equity. A well-written CLAUDE.md turns the same sessions into deposits, and it costs an afternoon to start.

Things is a digital design and engineering studio, founded in 2018, working from Istanbul and Elazığ for leading brands in Turkey and worldwide. Research-driven, Red Dot awarded, 50+ products shipped, with AI-augmented workflows built into how we design and build. If you want your brand to survive contact with AI tooling, we can help you encode it.

Write to us: **hello@things.ist**