How to Use DESIGN.md with Claude Code and CLAUDE.md

Why connect DESIGN.md to Claude Code?

A task prompt explains what to build now. A repository design specification explains how the product should look across tasks, sessions, contributors, and models. The strongest setup separates concerns: production components are executable truth, DESIGN.md describes the visual system and its constraints, and CLAUDE.md makes reading that context an explicit habit.

Persistent context

Anthropic documents CLAUDE.md as persistent project instructions loaded for sessions.

Focused instructions

Instructions should be specific and concise; large files can reduce adherence.

System before invention

For large projects, path-scoped rules can keep front-end guidance focused.

Human review remains essential

Agent instructions reduce arbitrary choices; they do not replace design judgment, accessibility testing, or visual QA.

Four-step setup

Place DESIGN.md at the repository root

Keep exact semantic roles, component recipes, layout patterns, states, motion, responsive rules, accessibility expectations, and “do not” guidance in one reviewable file.

Create CLAUDE.md

Use the concise rule below. It tells the agent when to consult the detailed specification without copying the whole document into another file.

Give the task measurable acceptance criteria

Name the existing component to reuse, the approved page to compare against, required states, responsive widths, and the visual decisions that must not change.

Review code and pixels

Search the diff for new hard-coded colors, fonts, shadows, radii, duplicate components, and one-off breakpoints. Then inspect the rendered result.

Copy-ready Claude Code rule

# CLAUDE.md

## User interface work
- Read @DESIGN.md before planning or changing UI.
- Reuse the existing component library and semantic tokens.
- Do not add visual values that conflict with DESIGN.md.
- Preserve accessibility, responsive behavior, and reduced-motion support.
- Compare the result with an approved page before declaring the task complete.

A better task prompt

Read DESIGN.md and the existing UI components before coding.
Build the account settings page using the approved page shell, form controls,
buttons, spacing rhythm, typography, and responsive breakpoints.

Acceptance criteria:
- no new colors, fonts, radii, shadows, or animation styles
- reuse existing components before adding variants
- include loading, validation, success, keyboard-focus, and mobile states
- compare at 1440px and 390px with the approved dashboard page
- list any intentional exception before implementing it

Common failure modes

Only saying “follow the design.” Point to DESIGN.md and concrete implementation sources.
Duplicating all tokens in the rule file. This creates two sources of truth.
Ignoring non-default states. Empty, error, loading, focus, and narrow-screen states expose drift first.
Allowing “improvements” during feature work. Treat visual changes as explicit design-system decisions.

Original implementation example

Suppose an approved card uses the semantic surface token, a 16px radius, one border token, and no shadow. A weak prompt may yield a visually plausible card with a 24px radius and a purple glow. The integrated workflow prevents that by requiring the agent to identify and reuse the card recipe before writing markup. If a new variant is genuinely needed, it must be named, implemented centrally, documented, and reviewed.

Frequently asked questions

Where should DESIGN.md go for Claude Code?

Put DESIGN.md at the repository root so it is easy to discover, version, review, and reference from the agent instruction file.

Does Claude Code read DESIGN.md automatically?

Do not assume it will. Add an explicit persistent instruction that requires the agent to read DESIGN.md before front-end work.

Should DESIGN.md duplicate the component library?

No. Point to real components and tokens, then document usage, composition, responsive behavior, states, and guardrails that code alone does not explain.

How do I know the integration is working?

Ask the agent to identify the relevant tokens and components before coding, then inspect the diff and compare the rendered result at desktop and mobile widths.