Getting Started
DESIGN.md vs CLAUDE.md
Keep engineering behavior and visual behavior separate so agents can follow both well.
CLAUDE.md scope
When Claude Code starts work in a repository, CLAUDE.md is the first file it reads — the engineering contract that tells the agent how to navigate the codebase, which commands to run, which libraries are in use, and which patterns to follow or avoid. It typically contains engineering rules: how to run the project, where the source files live, naming conventions, architectural constraints, how to handle migrations, testing expectations, and what patterns to avoid in code. A well-written CLAUDE.md gives the agent the information it needs to navigate the codebase, understand the technical context, and make engineering decisions consistent with the project's standards. It is the engineering contract between the team and the agent. Its scope is intentionally technical: it does not cover visual design, UI layout, component behavior, or product presentation. That separation is by design.
DESIGN.md scope
DESIGN.md covers the visual layer that CLAUDE.md deliberately leaves out. Where CLAUDE.md handles engineering decisions — which component library to use, how to structure a feature module, which API pattern to follow — DESIGN.md handles design decisions: what the UI should look like, how visual elements relate to each other, how components behave in different states, and what the overall product personality is. A good DESIGN.md makes visual decisions that would otherwise be left to the agent's trained defaults. It answers the questions that CLAUDE.md does not: should this card have a shadow or a border, should this heading be 20px or 24px, should this empty state have a background fill, should this action button use the primary or secondary variant? Those questions matter for product quality, and DESIGN.md is the file that answers them consistently.
Why two files work better than one
A combined instruction file that tries to cover both engineering behavior and visual design ends up serving neither well — and the problems compound with every new rule that gets appended. First, they have different audiences: CLAUDE.md is primarily useful for backend and full-stack work, DESIGN.md is primarily useful for UI and frontend work. A session focused on building an API endpoint does not need to read component density rules, and a UI polish session does not need migration instructions. Second, they change at different rates: engineering invariants like "use TypeScript throughout" rarely change, while design rules like "the card radius changed from 8px to 6px" may change each design sprint. Separate files make version control cleaner. Third, they are maintained by different people: engineers own CLAUDE.md, designers and product owners own DESIGN.md. Separation prevents one file from growing awkwardly around two incompatible organizational concerns.
Best pairing
The best pairing of CLAUDE.md and DESIGN.md produces a codebase where an AI agent can work on any feature with full context about both engineering and visual requirements. The prompt that takes full advantage of both files is simple: "Read CLAUDE.md for engineering rules and DESIGN.md for visual rules. Implement this feature. If there is any conflict between the two files, explain it before editing." That prompt delegates both types of decisions to stable, maintained files rather than to per-session prompts. A team that maintains both files consistently will find that the gap between AI output and production-ready code narrows steadily over time. The engineering decisions are correct because CLAUDE.md governs them. The visual decisions are consistent because DESIGN.md governs them. The remaining work is product-level judgment: whether the feature is the right feature.
What goes in each file
A simple heuristic for sorting content: if the rule governs how code is structured, it belongs in CLAUDE.md. If the rule governs how the product looks, it belongs in DESIGN.md. Engineering architecture, command syntax, test expectations, library version constraints, naming conventions, import rules, and deployment notes go in CLAUDE.md. Color tokens, typography scale, component behavior, spacing rhythm, page layout patterns, accessibility requirements, and anti-patterns go in DESIGN.md. Edge cases arise when a rule spans both dimensions — for example, "use Tailwind for all styling; do not introduce CSS modules." This is an engineering constraint that is also relevant to UI work. In that case, include it in both files with a pointer: CLAUDE.md says "all styling uses Tailwind," DESIGN.md says "color and spacing values use the following Tailwind classes." Overlap is acceptable; contradiction between the files is not.
Common mistake: putting design rules in CLAUDE.md
Over time, CLAUDE.md tends to grow by accumulation — teams append notes as they think of them, and design-adjacent rules often end up alongside engineering ones. A bloated CLAUDE.md might read: "Use TypeScript throughout. API routes follow REST conventions. All UI uses shadcn/ui primitives. Keep the palette minimal — primary blue (#3B82F6), grays from slate. Cards should feel spacious with generous padding. Buttons should look clean and professional." The problem is not any individual rule; it is their co-location. When Claude Code works on an API endpoint, it reads the entire file including card padding preferences. When it builds a component, the design rules are buried between migration notes and import conventions. Agents treat CLAUDE.md holistically — they try to satisfy all rules simultaneously, which creates a competition between engineering constraints and loosely stated design preferences. The deeper problem is specificity: "generous padding" does not produce a number, "clean and professional" does not produce a style. Design rules written inside CLAUDE.md stay vague because they are added as afterthoughts rather than written as the primary purpose of a file. When those same rules move to DESIGN.md, they get the concrete values they need: "card padding is 16px, primary button uses font-weight 500, radius is 8px." The separation is what forces specificity.
Scaling the pair over time
The real payoff of maintaining both files shows up around the six-month mark, when AI-assisted development stops needing visual cleanup and starts requiring only product-level review. CLAUDE.md accumulates architectural decisions, new dependency constraints, and module-level rules. DESIGN.md accumulates new component rules, updated layout patterns, and refined anti-patterns. The key to keeping both files useful is to maintain them close to the code that implements their rules. When building a new feature surface, update DESIGN.md with the layout and component rules for that surface in the same pull request as the feature code. When adding a new library or changing a key architectural pattern, update CLAUDE.md. Stale files are worse than no files because they give agents wrong instructions. A culture of updating agent memory files as part of normal feature work — not as a separate documentation task — keeps both files current with minimal overhead. After six months of maintained files, the AI-assisted development workflow becomes measurably more efficient because the agent starts each session with genuinely current and accurate context.
Use DESIGN.md with a real product reference
Browse curated DESIGN.md examples from product teams, design systems, developer tools, SaaS dashboards, and AI-native apps. Use them as references before your agent builds the next screen.
Related guides
What is DESIGN.md?
DESIGN.md is a markdown file that explains a product visual system to AI agents before they generate UI.
Best DESIGN.md examples
Examples of DESIGN.md files, templates, and public tools for AI-readable design systems.
DESIGN.md vs AGENTS.md
A clean mental model for splitting agent instructions by domain.