DESIGN.md, CLAUDE.md and AGENTS.md are plain-text, repo-resident files that give AI coding agents persistent context. CLAUDE.md and AGENTS.md cover code and conventions; DESIGN.md covers the visual identity. Complementary layers an agent reads on every interaction.
What each file covers
CLAUDE.md / AGENTS.md -> code & project context
(stack, conventions, commands)
SKILL.md -> on-demand capabilities
DESIGN.md -> the design system
(tokens + rationale)
Each handles a different concern, and they do not overlap.
Why separate files?
Separation keeps each focused and lets you adopt them independently. A team might start with CLAUDE.md for code context, add DESIGN.md when agent-generated UI drifts off-brand, and layer in skills later. All plain text, so they version and review like code.
They work together
The cleanest setup wires them: a CLAUDE.md that tells the agent to read DESIGN.md for UI work links code context to design context. The agent gets one coherent picture - how to write the code and how to make it look right.
Which to adopt first
Start with the file that solves your biggest pain:
- Agent gets code conventions wrong -> CLAUDE.md / AGENTS.md
- Agent writes correct code that looks off-brand -> DESIGN.md
Most teams end up with more than one, added as the need appears.
FAQ
One universal format? AGENTS.md is closest to a cross-tool standard for code context; DESIGN.md is the emerging standard for design context.
Can I have all three? Yes - code context, capabilities, and design context, each in its own file.
Bottom line
The pattern is the same across all of them: persistent, plain-text, repo-resident context an agent reads every time. DESIGN.md is the design member of the family.
Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet
Go deeper: The full guide covers the entire format — the token schema, the CLI in depth, accessibility, Tailwind and DTCG export, agent integration, and a complete walkthrough: DESIGN.md: The Complete Guide to Design Systems for AI Agents
How many of these files are in your repos already - none, one, or the full set? Curious where everyone is on this.
Top comments (0)