Notes7 min read
Write your taste down: a DESIGN.md your agents follow
Pick three to five examples you admire, have the agent pull out the patterns, decide which are rules and which are preferences, and save them in DESIGN.md at the root of your project. Then point CLAUDE.md at it so every session reads it, and review new screens against it.
From the course · lesson 2.1
Every Claude Code session starts with a fresh memory. Whatever you told the agent yesterday about your fonts, your colors and the tone of your buttons is gone today unless it's written in a file the agent reads. Without that file, the agent falls back on its defaults, which Anthropic describes as drifting toward the safe middle of everything it has seen.
So you end up repeating yourself, or you stop noticing the drift. The way to get AI to follow your design taste is to write it down once.
In this course that place is a file called DESIGN.md. It's a plain Markdown file in the root of your project that describes how your product should look, read and feel, written as rules an agent can follow and you can check.
Pick model examples
Start with three to five examples of work you admire, and mix them on purpose. If all five come from the same kind of app, the patterns will describe that genre, not your taste. In a well-known study, people who saw artists' paintings mixed together learned the styles far better than people who saw one artist at a time (the taste gap covers it).
Include at least one thing that isn't software. For Kudos, a made-up testimonial app, the set includes a handwritten thank-you card, a magazine pull quote and a museum wall label. You'll see them again in the template below.
For each one, write a line about what you admire, in words you could point at. "The quote is set three times larger than anything else" is useful. "It feels premium" is not.
Have the agent pull out the patterns
Next, ask the agent to do the close reading. Give it screenshots or links and a prompt like this:
Here are four examples I admire, with a note on each. Find the
patterns they share across type, color, spacing, layout, motion and
tone of voice. For each pattern, name which examples show it and how
confident you are. Don't suggest anything that isn't in the examples.
Katie Parrott at Every did a version of this when she wrote her publication's editorial standards down for Claude. She gathered the pieces everyone pointed to as the house style and asked the model what they had in common. The model came back with structural patterns, such as how the strongest pieces open and how they end. Her summary of the experience is worth keeping: "When you can teach taste to a machine, you're forced to make it legible for yourself."
Rules or preferences?
The agent will return a long list. Most of the value comes from sorting it.
Parrott describes the same step. To make the editor work for a whole team, she had to separate her own preferences from the publication's values, and decide which instincts deserved to become rules for everyone. You're doing the same thing for your product.
- A rule is a must. Breaking it is a bug. It's specific enough that someone could check it.
- A preference is a default. An agent may break it if it says which one and why.
One test sorts most items: would I reject a screen for breaking this? If yes, it's a rule. If you'd only sigh, it's a preference.
| Instinct | Rule or preference | Why |
|---|---|---|
| Body text at least 16px | Rule | Easy to check; smaller hurts reading |
| Customer's words come before stars or logos | Rule | It's the point of the product |
| Corners rounded at 8px | Preference | Nice, but a sharp corner wouldn't make you reject a screen |
| Motion kept to short fades | Preference | Fine to break for a moment that earns it |
Then cut. Claude Code's own docs suggest keeping its instruction file under about 200 lines, because longer files take up more of the agent's attention and get followed less reliably. They also advise writing instructions concrete enough to verify, such as an exact indentation width instead of a request for tidy formatting. The design version is "Body text at least 16px" rather than "Readable type."
A starter DESIGN.md
Here's a complete starter file, filled in for Kudos. Copy it, then replace every line with your own.
# Kudos design rules
## What Kudos is
Kudos helps freelancers, coaches and small businesses collect
testimonials from their customers and show them on their own sites.
## The feeling
A thank-you card, not a review site. Calm, warm and personal.
The customer's words are always the hero.
## Rules (must follow)
### Type
- Quotes: Fraunces, at least 24px on the testimonial wall.
- Interface text: IBM Plex Sans. No other font families.
- Body text at least 16px, line height at least 1.5.
### Color
- Background #FAF7F2, text #1F1B16.
- One accent, #C2410C, only for the main action and active states.
- No gradients.
- Text contrast at least 4.5:1 (WCAG AA).
### Spacing and layout
- Spacing comes from this scale only: 4, 8, 16, 24, 32, 48, 64px.
- One main action per screen.
- On the wall: quote first, then name, then role. Never stars on top.
### Words
- Say "testimonial", never "review".
- Sentence case everywhere. Buttons start with a verb ("Send request").
- AI polish always shows the customer's original next to the edit.
Nothing is published without the customer's approval.
- Never write sample testimonials that look like real customers.
Placeholder content is labeled "Example".
## Preferences (defaults; break one only if you say which and why)
- Cards have 8px corners and no shadow.
- Motion: fades of 150 to 200ms, ease-out. No bounce.
- Empty states: one short, warm sentence and one action.
- Show a customer photo only if they agreed to it; otherwise initials.
## Avoid (the average)
- Inter, Roboto, Open Sans or Lato as the default font.
- Purple gradients on white.
- Three-card feature grids with icons.
- Vague claims like "Trusted by thousands".
## Examples we admire
- A handwritten thank-you card: one message, nothing else.
- A magazine pull quote: the quote is the design.
- A museum wall label: quiet text that doesn't compete.
- A plain receipt email: clear order, nothing extra.
## How to check a screen
1. Does it do its job, and is the flow obvious?
2. Does it pass every rule above? Note any that fail.
3. Which preferences did it break, and is the reason good?
Claude Code loads CLAUDE.md on its own, but it won't open DESIGN.md unless you tell it to. So add one line to your CLAUDE.md (the starter file /init creates, as in Claude Code for designers) to pull the design file in:
Design rules: @DESIGN.md
Read the rules before changing any UI. Rules are must-follow.
If you break a preference, say which one and why.
The @ tells Claude Code to load that file at the start of every session, alongside CLAUDE.md itself.
Check it's followed
Writing the file is half the job. Claude Code's docs are clear that instruction files are context the agent reads, not settings it's forced to obey. So check.
When the agent builds a new screen, ask for a review against the file, not against vibes:
Review this screen against DESIGN.md. For each rule, say pass or
fail and show the evidence. Then list any preferences you broke
and why.
Do your own pass in a sensible order. Julie Zhuo, who led product design at Facebook, advises critiquing function and flow before visuals and polish, and always pairing a criticism with a suggestion.
If a rule keeps getting broken, it's usually too vague, so rewrite it until a stranger could check it. Fully mechanical rules, like a banned font name, can later become hooks: small scripts that block a change automatically.
The file will never hold all of your taste, only the part you can put into words. That frees your attention for the rest. In lesson 2.1 of Chief of Agents, you write your own DESIGN.md with the Designer agent, sort its rules from its preferences, and then use it to cut a batch of fifty variants down to one.
Sources
- Improving frontend design through Skills (Anthropic, November 2025)
- How Claude remembers your project (Claude Code docs)
- Stitch's DESIGN.md format is now open-source (Google, April 2026)
- google-labs-code/design.md (draft spec on GitHub)
- I taught Claude Every's standards. It taught me mine. (Katie Parrott, Every, August 2025)
- Learning concepts and categories: Is spacing the "enemy of induction"? (Kornell and Bjork, Psychological Science, 2008)
- How to improve your product design taste (Herbert Lui, The Next Web, 2014)
Learn this inside Claude Code.
Join the waitlist for Chief of Agents. You'll get the free beginner's handbook and skills right away, and hear first when the course opens.
Keep reading
6 min read
Your first Claude Code skill in 15 minutes
How to make a Claude Code skill: pick a weekly chore, write it down once as a SKILL.md, and run it any time by typing its name.
7 min read
Write the press release before you build
How to know an idea is worth building: write the press release first. Amazon's PR/FAQ, a skeptic agent and the 11-star exercise.
6 min read
Claude Code for designers: what it is, and why it isn't just for engineers
What a coding agent does, why directing one is a design skill, and a safe first hour for designers new to Claude Code.