The Right Way to Set Up DESIGN.md in Any Project

Most developers use DESIGN.md wrong. They paste it into a chat, get one good component, then forget about it. Next session, the design drifts.

The right setup takes 10 minutes. After that, every AI tool you use picks up your design system automatically. Here is exactly how to do it.

Where to put the file

Project root. Always. Not in src/, not in docs/, not in .config/. The root.

Every AI coding tool reads project root files for context. Putting DESIGN.md here means it gets picked up without any extra configuration.

What to name it

Name it DESIGN.md. Capital letters, .md extension. This is the convention every tool in this guide expects. Do not name it design-system.md or tokens.md or styles.md.

Consistency across projects means you never have to remember where you put your design rules. It is always DESIGN.md in the root.

Reference it from CLAUDE.md

CLAUDE.md is Claude Code's project instruction file. Add a design system section that tells Claude to check DESIGN.md before writing any UI code.

Claude Code reads CLAUDE.md at the start of every session. Your design rules are now automatically in scope for every conversation in this project.

Reference it from .cursorrules

If you use Cursor, add the same instruction to .cursorrules. Cursor reads this file the same way Claude Code reads CLAUDE.md.

Same rule, different file. Cursor picks it up automatically.

Reference it from .windsurfrules

Windsurf uses .windsurfrules in the same way. Add the same block there if your team uses Windsurf.

The last point matters for Windsurf specifically. Cascade touches multiple files in one flow. You want the same tokens applied everywhere.

Gitignore? No. Commit it.

Your design system should be version controlled. It is part of your project. Treat it like you treat your package.json.

When the design changes, you commit the update. The history is there. You can see exactly when you changed your primary color or adjusted the type scale. That is useful.

Putting DESIGN.md in .gitignore defeats the whole point. Everyone on your team needs the same file.

When to update it

When you change your brand. Not every session. Not every sprint. Not when you feel like tweaking a color.

DESIGN.md should be stable. That stability is what makes it useful. When your AI tools know the rules won't change day to day, they can apply them consistently without second-guessing.

The right trigger: you made a deliberate decision to update your design direction. That is when you open DESIGN.md, update it, and commit the change.

Team setup

One DESIGN.md in the repo. Everyone commits their changes through it. Every AI tool every team member uses reads the same file.

This is the key insight: DESIGN.md is not a personal note. It is the team's shared design contract. When a designer updates the color system, they update DESIGN.md and commit it. Every developer's AI tools pick up the change on the next pull.

The result: consistent AI output across the whole team, without anyone manually syncing design decisions. One file, one source of truth, zero drift.