Docs / Integrations

Claude Code

Claude Code reads DESIGN.md automatically when you start a session in a project directory that contains the file. No configuration required.

How it works

When Claude Code starts a session, it reads all context files in the project root — including DESIGN.md. The file’s YAML front matter gives Claude exact token values; the markdown body gives Claude the design rationale. Both layers are used when the agent generates UI code.

The file is read on session start and remains in context for the entire session. You do not need to reference it in every prompt.

Placement

Place DESIGN.md at the root of your project — the same directory as package.json:

your-project/
├── DESIGN.md        ← place here
├── package.json
├── src/
└── app/

Importing into CLAUDE.md

If your project already uses a CLAUDE.md file for project-level context, you can import DESIGN.md directly using the @ import syntax. This keeps the design spec in its canonical location while making it part of the structured context:

# CLAUDE.md

## Visual language
Follow the design system strictly: @DESIGN.md

The @DESIGN.md reference is resolved relative to the location of CLAUDE.md. If both files are in the project root, the path works as-is.

Example prompts

Once DESIGN.md is in context, you can reference it naturally in your prompts:

"Build a settings page using the design system in DESIGN.md"

"Create a pricing card component. Follow the card and button-primary
tokens from DESIGN.md exactly."

"Refactor this component to use the spacing and color tokens defined
in DESIGN.md instead of hardcoded values."

"Add a badge showing the user's plan tier. Use badge-accent from
DESIGN.md for the Pro tier."

Verifying Claude reads the file

You can confirm Claude has read your DESIGN.md by asking:

"What color is the primary button background in this project's design system?"

Claude should respond with the exact value from your colors.primary token — not a generic answer.

Tips for best results

The following practices improve output quality when using Claude Code with DESIGN.md:

• Keep the file concise. Claude loads it into context — dense, accurate prose beats long aspirational descriptions.
• Name your tokens semantically. colors.primary is more useful than colors.dark-navy-blue because the agent can infer intent from the name.
• Use the Do’s and Don’ts section for hard constraints — Claude treats these as firm rules.
• After generating UI code, ask Claude to check its output against the design spec: “Verify this component uses only the tokens from DESIGN.md and no hardcoded values.”