TL;DR
AI design tools are powerful, but give them nothing and they hand you generic slop - teal accents, three-column grids, blinking dots. The fix is not a better prompt, it is a DESIGN.md file: one plain-markdown file that holds your entire visual language so Claude Code, Cursor, and any design tool make your brand their default. Write it once, stop re-briefing every session.
Why a DESIGN.md works
Most people write design files for humans. A DESIGN.md is written for AI agents, and that changes the format. The one core rule: keep the name, the value, and the rule on the same line. An agent that only has a hex code will use it at random. An agent that has the name, the value, and when to use it will use it correctly every time.
The six layers of an airtight DESIGN.md
- 1Visual vibe - 2 to 4 adjectives for how the brand feels, not what it looks like. 'Airy, precise, confident' tells an agent something. 'Modern, clean, professional' tells it nothing, because every brand says that.
- 2Color palette - for each color: name, hex, role, and when NOT to use it. Cover background, surface, text, accent, and danger at minimum.
- 3Typography - font family, weight-to-role mapping, tracking, and line height. Skip this and your H1 and your caption come out identical.
- 4Geometry and shadows - sharp, rounded, or pill corners; flat, soft, or high-contrast shadows. This is the fastest signal of personality; skip it and everything feels slightly off even when the colors are right.
- 5Component rules - buttons, cards, inputs, navbars, each with default, hover, and disabled states. Without this, every button looks the same and your primary, ghost, and danger actions lose their hierarchy.
- 6Agent prompt guide - the layer most people skip. Three to five reusable prompt templates for the things you build most (hero, pricing table, dashboard card) so you edit a brief instead of starting from scratch.
The copy-paste DESIGN.md starter
Fill in the brackets, delete what does not apply, and save it as DESIGN.md in your project root.
markdown# DESIGN.md
## Visual Vibe
[2-4 adjectives: how your brand FEELS, not what it looks like]
## Color Palette
- [Name] ([#hex]) - [role]. Use for [X]. Never for [Y].
- [Name] ([#hex]) - [role]. Use for [X]. Never for [Y].
- Background: [Name] ([#hex])
- Surface/Card: [Name] ([#hex])
- Text Primary: [Name] ([#hex])
- Accent: [Name] ([#hex])
- Danger: [Name] ([#hex])
## Typography
- Primary Font: [Name]
- H1: [weight]w, [tracking], [size]
- Body: [weight]w, [line-height]
- Labels: [weight]w, [size]
- Accent Font: [Name] - [use case only]
## Geometry & Shadows
- Border Radius: [value + rules, e.g. "4px all containers. Pills for tags only."]
- Shadows: [style + CSS value]
- Borders: [style + when to use/not use]
## Component Rules
### Buttons
- Primary: [bg, text, radius, hover]
- Ghost: [outline, hover]
- Danger: [color, when to use]
- Disabled: [opacity, cursor]
### Cards
- Default: [bg, border, shadow, radius, padding]
- Featured: [how it differs]
### Forms
- Input: [border, focus ring, placeholder color, error state]
- Labels: [above or floating]
## Layout
- Grid: [columns, gutter, max-width]
- Whitespace: [rhythm, e.g. "48px between sections"]
- Alignment: [rules, e.g. "Left-aligned text always"]
## What We Never Do
- [Anti-pattern 1]
- [Anti-pattern 2]
## Agent Prompt Templates
- Hero: "Build a hero using this DESIGN.md. Aesthetic: [vibe]. Lead with [value]. CTA: [text]. Export HTML."
- Card: "Build a [type] card. Pull colors from palette. Max 3 data points per card."
- [Add your own]How to load it into your tools
A file you never load is just documentation. In Claude Code, add one line to your CLAUDE.md so it reads the design rules before any UI work. In Cursor, add DESIGN.md as a file reference in your rules or paste it into the always-include context. In a dedicated AI design tool, attach it as the brand context file before you generate anything.
markdownWhen doing any UI work, first read DESIGN.md and follow its rules exactly before writing any code.Common questions
What is a DESIGN.md file?
A plain markdown file that holds your brand's full visual language - colors, fonts, geometry, components, and the feel - written so an AI tool can read and follow it. Drop it in your project and Claude Code, Cursor, and design tools all build to your brand instead of a generic default.
How is this different from a CLAUDE.md file?
CLAUDE.md holds how you work and your operating rules; DESIGN.md holds how things should look. They pair together - your CLAUDE.md can simply tell Claude to read DESIGN.md before any UI work. See our Ultimate CLAUDE.md File guide for the other half.
Do I need a designer to write one?
No. The starter template above walks you through every layer in brackets. If you already have a website, point an AI tool at the live URL, have it extract your existing system, and use that as your first draft - then refine it.
Why does the format keep the name, value, and rule on one line?
Because an agent that only sees a hex code uses it randomly. When the name, the value, and the when-to-use-it live together on one line, the agent applies it correctly every time. That single rule is what makes a DESIGN.md actually work.
Which tools can read a DESIGN.md?
Any AI coding or design tool that accepts context files. The common three are Claude Code (reference it from CLAUDE.md), Cursor (add it to your rules), and AI design tools (attach it as the brand context). The file itself is tool-agnostic markdown.
How often should I update it?
Every time you make a deliberate design decision - a new color, a changed radius, an added font weight. It takes 30 seconds. A current file is the single biggest difference between people who get on-brand output first try and people who re-brief the AI every session.
Want your whole starter stack on-brand from day one?
Get the other 3 in the starter stack - free, with 5,000+ builders.
Join the Club