Claude Code CLAUDE.md

DESIGN.md + Claude Code

Configuration reference: Follow visual rules from @DESIGN.md

Prerequisites

  • Claude Code installed (VS Code or terminal)
  • A project with an initialized Git repository
  • A DESIGN.md file — grab one from the library or generate with the design-md skill

Setup

1. Place your DESIGN.md

Drop the file at the project root:

my-project/
├── DESIGN.md
├── CLAUDE.md
├── src/
└── ...

2. Create or edit your CLAUDE.md

CLAUDE.md is the config file Claude Code reads automatically on every session. Add a reference to your DESIGN.md:

# CLAUDE.md

## Visual rules
Follow strictly the rules defined in @DESIGN.md for all UI generation.
Do not invent colors, fonts, or spacing outside the design system.
Before generating any visual component, read @DESIGN.md in full.

The @ prefix tells Claude Code to read the contents of the referenced file. Without it, the agent treats the filename as plain text.

3. Verify the setup

Ask Claude Code to generate a simple component:

Create a primary button and a card following the DESIGN.md

Check that colors, fonts, and spacing match what’s defined in your DESIGN.md. If the agent used different values, revisit step 2.

4. Refine your instructions

For more consistent output, be specific in CLAUDE.md:

## Visual rules
- Follow @DESIGN.md for all UI generation
- Use ONLY colors defined in the Colors section
- Respect the spacing scale from the Spacing section
- Apply component patterns from the Components section
- Never violate constraints from the Do's and Don'ts section

Troubleshooting

  • Agent ignored DESIGN.md — check that the file is at the project root and that CLAUDE.md uses @DESIGN.md (with the @ prefix). Without it, Claude Code won’t read the file contents.
  • Colors partially correct — your Colors section might be missing semantic names or usage rules. Add context: brand-primary (#1A73E8): CTAs and links only.
  • Inconsistent components — add a Components section to DESIGN.md with explicit states (hover, disabled, focus). Without defined states, the agent invents different patterns on every generation.
  • Agent forgets between prompts — Claude Code re-reads CLAUDE.md on each session, but can lose context in long conversations. Reinforce with “follow the DESIGN.md” when needed.

Useful combinations

  • DESIGN.md + AGENTS.md — visual rules plus code conventions. AGENTS.md defines code patterns (naming, folder structure, linting), while DESIGN.md covers visual standards. Together they cover everything the agent generates.
  • DESIGN.md + Do’s and Don’ts — the constraints section has the most impact on consistency. LLMs respond well to negative instructions. Telling the agent what NOT to do matters as much as telling it what to do.
  • Multiple DESIGN.md files — for projects with sub-apps or themes, create separate DESIGN.md files and reference the correct one in CLAUDE.md by context.

Next steps

Useful links