# DESIGN.md with Claude Code > Import DESIGN.md into CLAUDE.md with @DESIGN.md so Claude Code follows your colors, type and spacing. Includes a sample CLAUDE.md and checks. Canonical page: https://sitepeel.dev/guides/design-md-claude-code/ Save DESIGN.md in your project root and add @DESIGN.md to CLAUDE.md. Claude Code then loads your design tokens and rules at the start of every session. Published: 2026-10-24 Tool used in this guide: [Design MD generator](https://sitepeel.dev/design-md-generator/index.md) ## How to use it 1. **Add DESIGN.md to the root** Generate it from a site with Sitepeel or write it, then save it next to CLAUDE.md in your project root. 2. **Import it in CLAUDE.md** Add a line with @DESIGN.md. No CLAUDE.md yet? Run /init to create one first. 3. **Start a new session** CLAUDE.md loads at launch. Run /context to check it loaded, then ask Claude for your primary color. 4. **Ask for one screen** Name the page, its content and its main action. Ask Claude to list the tokens it used. 5. **Review and correct** Compare the result at phone and desktop widths. Fix DESIGN.md when the same mistake comes back. ## Import DESIGN.md in CLAUDE.md Claude Code reads ./CLAUDE.md or ./.claude/CLAUDE.md at the start of every session. An @path line expands another file into that context, so one import keeps your design rules loaded without pasting them in. Example: CLAUDE.md ``` # Project instructions ## Design Follow the design system in @DESIGN.md for all UI work. - Use its color, typography, spacing and radius tokens. No new hex values. - Reuse components in src/components before creating new ones. - If DESIGN.md has no rule for a case, ask before inventing one. - After UI changes, list the tokens and components you used. ``` ## How @ imports resolve - Paths resolve from the file that holds the import, not from where you launched Claude - Keep DESIGN.md in a subfolder? Write @docs/DESIGN.md, or use an absolute path - Imported files can import others, up to four hops deep - For a path with spaces, put a backslash before each space; quoted paths aren’t imported - Files outside the project trigger a one-time approval prompt - Imports organize files but don’t save context: the whole file loads every session ## Already using AGENTS.md? Claude Code (version 2.1.277 or later) reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in your working folder or above it. If both exist, it reads CLAUDE.md. To share one setup with Codex or Cursor, put @AGENTS.md in CLAUDE.md and keep the DESIGN.md line in AGENTS.md. - [Sample AGENTS.md section for DESIGN.md](https://sitepeel.dev/guides/design-md-codex/index.md) ## Load design rules only for UI files In a large repository, move the design rules into .claude/rules/ui.md and add a paths list to its front matter, such as src/components/**/*.tsx. Claude Code loads that rule only when it reads or edits a matching file. Tell it there to read DESIGN.md first. ## Check what Claude built - Ask which DESIGN.md tokens it used, and look for raw hex values in the diff - Open the page at a phone width and a desktop width - Compare buttons, headings and spacing with the Components and Typography sections - When the same miss repeats, add a Do or Don’t to DESIGN.md - After editing DESIGN.md, run npx @google/design.md lint DESIGN.md - [Claude still ignores the design? Check these five things](https://sitepeel.dev/guides/ai-ignoring-design-md/index.md) ## Questions and answers ### Does Claude Code read DESIGN.md automatically? No. Claude Code loads CLAUDE.md files, or AGENTS.md when there is no CLAUDE.md. Add @DESIGN.md to CLAUDE.md and the file loads into every session. ### Does Claude Code read AGENTS.md? Yes, from version 2.1.277, when there is no CLAUDE.md or CLAUDE.local.md in your working folder or above it. If both exist, it reads CLAUDE.md only, unless CLAUDE.md imports @AGENTS.md. ### How do I import a file in CLAUDE.md? Write @ followed by the path, such as @DESIGN.md or @docs/DESIGN.md. Relative paths resolve from the CLAUDE.md file. Imported files can import others, up to four hops deep. ### Where should DESIGN.md go for Claude Code? The project root, next to CLAUDE.md, is simplest: the import is just @DESIGN.md. Any folder works as long as the import path matches. ## Further reading - [Claude Code docs: CLAUDE.md, @ imports, rules and AGENTS.md](https://code.claude.com/docs/en/memory) ## Related pages - [What is DESIGN.md](https://sitepeel.dev/guides/what-is-design-md/index.md): DESIGN.md is a Markdown design-system file for AI coding agents. See its format, a small example, the official linter and how to make one from any site. - [DESIGN.md with Cursor](https://sitepeel.dev/guides/design-md-cursor/index.md): Point Cursor at DESIGN.md with a project rule in .cursor/rules, AGENTS.md or an @ mention. Includes a sample .mdc rule and the four rule types. - [DESIGN.md with Codex](https://sitepeel.dev/guides/design-md-codex/index.md): Make OpenAI Codex follow DESIGN.md with a few lines in AGENTS.md. See where Codex looks for instructions, its size limit and how to check what loaded. - [Use Design MD with AI](https://sitepeel.dev/guides/use-design-md-with-ai/index.md): Hand DESIGN.md to Cursor, Claude Code or another AI coding assistant: where to save it, two prompts to copy and how to review what it builds. - [When AI ignores DESIGN.md](https://sitepeel.dev/guides/ai-ignoring-design-md/index.md): Your agent has DESIGN.md but the UI is still wrong? Check that it loads, remove conflicting rules, name real components and verify the result.