AI Agents

DESIGN.md for Claude Code

How to use DESIGN.md as persistent visual context for Claude Code so multi-file UI work stays consistent with your product design system.

April 15, 20267 min read

Why Claude Code benefits from a DESIGN.md file

A single Claude Code session can span a dashboard page, a settings section, and a profile route — and without a stable visual reference, each screen ends up with subtly different spacing decisions, type choices, and component density that no one made intentionally. That power makes design memory more important, not less. When Claude Code works across a codebase, visual drift can compound quickly. A session that adds a dashboard section, a settings page, and a profile route can produce three screens that each look slightly different because the agent made independent decisions for each. DESIGN.md gives Claude Code a stable visual contract that persists across all those decisions. It works as a shared design source of truth that the agent reads before editing any UI file — the same way CLAUDE.md governs engineering behavior. Together the two files cover both dimensions of implementation quality: whether the code is architecturally correct and whether the UI is visually intentional. Without both, even well-structured code produces inconsistent interfaces.

Pairing DESIGN.md with CLAUDE.md

The most effective setup for Claude Code is two instruction files with distinct scopes. CLAUDE.md handles engineering rules: how to run commands, which directories contain what, naming conventions, architectural constraints, which libraries to use, and what to avoid. DESIGN.md handles visual rules: color tokens, typography scale, spacing rhythm, component behavior, page density, and anti-patterns. Keeping them separate has a practical advantage: CLAUDE.md can focus on technical invariants without being crowded by design details, and DESIGN.md can focus on visual decisions without technical noise. Claude Code uses both files naturally when referenced in a prompt. A strong opener for UI work: "Read CLAUDE.md for engineering context and DESIGN.md for visual rules. Implement [task]. Reuse existing components. Explain conflicts between the two files before editing." This keeps both dimensions active without combining them into one harder-to-maintain document.

Best prompt pattern for Claude Code UI work

Claude Code performs best on UI tasks when the prompt mirrors how a designer briefs an engineer: describe the goal, identify the source of truth, and set acceptance criteria. A prompt structured this way: "Read DESIGN.md. Add a user profile settings page. Use the form layout, button variants, input states, and section spacing defined there. Do not add decorative elements. The page should match the density of the existing AccountSettings component." That structure gives Claude Code less room to improvise and more ability to produce a consistent result. For larger sessions — redesigning a feature surface, building a new product flow, or migrating a legacy UI — ask Claude Code to audit before editing: "Scan the components in /features/settings and identify which already follow DESIGN.md and which have visual inconsistencies." The audit step makes the implementation plan more accurate and reveals which components need cleanup before new ones are added.

What to include in a Claude Code-ready DESIGN.md

A Claude Code-ready file should cover the most common UI surfaces in your product. For a SaaS application, that usually means the dashboard home, data tables, settings sections, forms, modals, empty states, and navigation. For each surface type, include a short description and explicit constraint values. Dashboard home: "Uses a 3-column grid at desktop, 1-column on mobile. Top section is a stats row with compact metric cards. Cards have 20px padding, 8px radius, a subtle bottom border rather than a shadow." Data table: "Headers are medium-weight 13px. Row height is 44px. Selected rows use a muted background, not a strong accent. Bulk actions appear in a floating bar, not a toolbar above the table." These surface descriptions are what make a DESIGN.md file useful for multi-file implementation — they tell the agent what the entire page should look like, not just what color the button should be.

Using DESIGN.md for repository-scale UI work

Repository-scale Claude Code sessions — those that touch five or more files across a product surface — are where DESIGN.md provides the most leverage. In these sessions, Claude Code may create new components, update existing ones, add new routes, and modify shared layout code. Without a design brief, each file can drift in a slightly different direction. With DESIGN.md, the agent has a reference it applies consistently across all touched files. A useful workflow for large sessions: start by asking Claude Code to read DESIGN.md and list the five most relevant rules for the current task. This creates a lightweight commitment the agent will try to honor. After implementation, ask it to check each modified file against those five rules and flag any deviations. This makes review fast: instead of checking every line of UI code, you verify whether the specific rules were followed. The file also becomes a shared reference for human reviewers — the PR reviewer can check the same rules without relying on institutional knowledge.

Review loop and updating the spec

The review loop for Claude Code is more important than for single-file editors because the output surface is larger. After a session, compare the generated UI against DESIGN.md section by section. Start with the rules most likely to be violated: spacing consistency, component reuse, empty state treatment, and anti-patterns. When a violation appears, decide whether the rule was unclear, incomplete, or simply missed. Unclear rules should be made more concrete with exact values. Incomplete rules should be extended with the missing case. Rules that were missed despite being clear may need to be repeated at the top of the file in a high-priority summary section. As DESIGN.md grows, keep it scannable: use clear headings, keep rules concise, and put the most important constraints first. A 200-line file that Claude Code reads completely is more valuable than a 2000-line file it truncates. The goal is a spec that is specific enough to produce consistent output and short enough that an agent reads all of it every time.

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.

Browse directory Submit DESIGN.md

Related guides

AI Agents5 min read