Skip to content

Search design systems

Search for a design system by domain or name

Back
·6 min read

How to Use DESIGN.md with Claude Code

By DesignMD Team

Claude Code already reads CLAUDE.md — what about visuals?

Engineers using Claude Code have widely adopted the CLAUDE.md convention to govern behavioral instructions. You drop the file in the repository root, and Claude instantly knows how to format commit messages, write tests, and structure API responses. It solves the problem of behavioral context permanently.

But a major gap remains regarding visual context. When you ask Claude Code to generate a user interface component, it defaults to generic utility classes or invents hex codes. Pasted screenshots fail because the vision models approximate colors and spacing rather than pulling the exact tokens. Pasted Figma frames don't survive session resets, forcing the developer to re-explain the brand guidelines every time they initialize a new terminal session. To fully understand why we need a dedicated file for this, review our guide on what DESIGN.md is.

The two-file pattern

The solution is adopting a two-file pattern at the repository root.

The CLAUDE.md file remains responsible for engineering behavior, testing conventions, and architectural preferences. The DESIGN.md file takes absolute ownership of the visual identity. It dictates the hex codes, spacing scales, and component compositions.

This separation of concerns matters. Mixing visual tokens into a behavioral instruction file dilutes the context window and confuses the agent. By isolating the design tokens in a file specifically formatted for visual data, Claude Code can index the variables accurately and retrieve them when generating frontend code. We cover this architectural pattern extensively in our guide to AI coding agent design files.

Step 1 — Generate your DESIGN.md

Before you can instruct Claude Code, you need the file.

You can extract a complete file from any live URL using designmd.run. The pipeline will parse the site and generate the markdown file in about three minutes. Ensure you check the confidence score provided at the end of the extraction; a high score indicates that the tokens are reliable. Alternatively, you can write the file by hand, ensuring you follow the YAML frontmatter schema. If you want to see what a high-quality file looks like before generating your own, check the Linear design system breakdown.

Step 2 — Drop the file at repo root

Once you have the DESIGN.md file, move it to the root of your repository, alongside your package.json and existing CLAUDE.md file.

Root placement is critical. Claude Code automatically scans the root directory for context files upon initialization. If you place the file inside a nested docs/ folder, the agent may not index it automatically, requiring you to manually point the agent to the path in every session. By cohabiting with CLAUDE.md and AGENTS.md at the root, the file becomes a permanent part of the environment context.

Step 3 — Prompt with DESIGN.md context

With the file in place, your prompting strategy becomes a lot leaner.

You no longer need to define your primary brand color or spacing scale in the chat. A successful prompt explicitly references the file: "Create a new pricing card component in src/components. Use the spacing scale and card component definition from DESIGN.md."

When grounded in this context, Claude Code accurately pulls the exact hex codes for the background surface and text layers. It applies the correct border radius defined in the YAML frontmatter and utilizes the specified font family, drastically reducing the need for manual CSS corrections. For a comparison on how other IDEs handle this, read our guide on design.md with Copilot.

Step 4 — Verify the output

After Claude Code generates the component, verify the output against the specification.

Check the colors, typography stack, and component layout. The generated code should map one-to-one with the variables defined in the frontmatter. If you notice discrepancies, ensure your prompt explicitly mentioned the file. If you undergo a brand refresh, simply re-extract the new design system, replace the file at the root, and Claude Code will automatically adopt the new visual identity in your next session.

Tips and pitfalls

When working with Large Language Models, context-window budgeting is a reality. Keep your DESIGN.md file focused on core tokens and primary components. Avoid documenting hundreds of edge-case UI states, which can overwhelm the agent's attention mechanism.

If you operate a monorepo with multiple distinct frontend applications, placing a single file at the repository root may cause conflicts. In those instances, place a specific DESIGN.md file at the root of each respective application workspace. Claude Code will prioritize the file located closest to the execution directory. To understand the broader economic impact of adopting this workflow, read about the hidden cost of re-explaining design.

Frequently asked questions

Do I need to restart Claude Code after adding the file?

Yes, it's recommended to start a new session or explicitly ask Claude Code to re-index the workspace to ensure it captures the newly added file.

Can I combine CLAUDE.md and DESIGN.md?

While technically possible, it's strongly discouraged. Separating behavioral rules from visual tokens ensures better parsing and prevents context dilution.

What happens if Claude Code ignores the file?

If the agent ignores the tokens, ensure your prompt explicitly states "reference DESIGN.md for styles" to force the agent to perform a context lookup.

Get Started

Generate your DESIGN.md file in about 3 minutes — paste any URL. Head to the designmd.run homepage to get started.