DESIGN.md

Simple Definition

DESIGN.md is a reusable Markdown file that stores a project’s visual design rules, colors, typography, spacing, component patterns, and layout conventions, so an AI coding or design agent reads and follows them automatically instead of guessing at your brand each session.

Why It Matters

Without a written design system, an AI agent asked to build something new has to infer your visual rules from whatever it can see in the existing code, and it drifts: a slightly different color, an inconsistent spacing value, a button that doesn’t match the rest of the product. DESIGN.md turns those recurring corrections into a standing file the agent checks before generating anything visual.

DESIGN.md vs. CLAUDE.md

CLAUDE.md holds general project instructions: tech stack, commands, coding standards. DESIGN.md is the narrower, visual-specific counterpart: colors, type, spacing, and component rules. Teams reference DESIGN.md from CLAUDE.md so an agent working on anything visual knows where to look.

Example

A team keeps getting AI-generated buttons in slightly different shades of blue. Instead of correcting it each time, they add a rule to DESIGN.md: “use only the primary token defined in tokens.css, never a raw hex value.” Future sessions follow the rule without being reminded.

CLAUDE.md, the general project instruction file DESIGN.md pairs with
LLM-Safe Design System, a design system structured so agents can’t easily go off-system
Intent-Based Design Tokens, naming colors and values by purpose, a common DESIGN.md building block
AI Coding Agent, the kind of tool DESIGN.md guides

For a full walkthrough and starter template, see How to Build an AI Design System With DESIGN.md and CLAUDE.md.