Claude Code design context: setting up DESIGN.md in your project

August 17, 2026 6 min read

How to drop Design Catcher's 3-file bundle into a Claude Code project and write prompts that match your design system perfectly.

Claude Code builds what you describe. The quality ceiling is how precisely you can describe it. When it comes to UI, "make it look clean" produces different results every run. "Use the type scale and spacing tokens from @design/DESIGN.md" produces results you can iterate on.

This post covers the exact workflow for getting Design Catcher's output into Claude Code and writing prompts that reference it reliably: capturing, organizing the files, wiring them into CLAUDE.md, and the prompt patterns that actually work.

Why markdown beats screenshots for design context

The instinct when working with Claude Code on UI is to paste a screenshot and say "build something that looks like this." It works, after a fashion. But screenshots have real limitations:

  • Token opacity: A screenshot shows you that a button is a certain shade of blue. It does not tell the agent that the value is #5E6AD2, or that the same value is used for active navigation states, focus rings, and selected item backgrounds across the application. The agent has to guess.
  • Context window cost: A 1080p screenshot at reasonable quality is thousands of tokens. A DESIGN.md file covering the same design system in full is typically 600–900 tokens. You can reference it in every prompt without feeling the cost.
  • Searchability: You can tell the agent to look up a specific token by name. You cannot ask an agent "what hex value did I show you in that screenshot from three turns ago."
  • Composability: Markdown files can be versioned, diffed, and updated. When you refine your token system, you update the file and every subsequent prompt benefits.

Design Catcher produces three markdown files. DESIGN.md covers tokens. STRUCTURE.md covers layout and page-level patterns. UI-KIT.md covers component anatomy. Together they give Claude Code the full picture without a single image.

Step 1 — Capture your design system

Install Design Catcher from the Chrome Web Store:

chromewebstore.google.com — Design Catcher

Navigate to any live webpage — your own product, a design inspiration site, a competitor — and click the extension icon. Design Catcher reads computed CSS, CSS custom properties, and DOM structure, then sends it to Gemini 2.5 Flash for synthesis. Download the zip when it appears.

For your own project: capture your production site (or your local dev server on localhost). This gives you a ground-truth representation of your current design system — useful for staying consistent as the project grows. Design Catcher's own DESIGN.md was generated this way, from the live designcatcher.aryanshtech.com site.

Step 2 — Organize the bundle in your repo

Create a design/ directory at your project root. Drop the three files in: 

my-project/
├── CLAUDE.md
├── design/
│   ├── DESIGN.md       ← tokens: colors, type, spacing, radius, shadows
│   ├── STRUCTURE.md    ← layout: page anatomy, grid, navigation patterns
│   └── UI-KIT.md       ← components: buttons, forms, cards, badges
├── src/
└── ...

If you have multiple captured systems — your own site plus an inspiration source — use named subdirectories: 

design/
├── current/          ← your production site
│   ├── DESIGN.md
│   ├── STRUCTURE.md
│   └── UI-KIT.md
└── linear-ref/       ← reference inspiration
    ├── DESIGN.md
    └── UI-KIT.md

Step 3 — Wire it into CLAUDE.md

CLAUDE.md is the persistent context file Claude Code reads at the start of every session. This is where you tell the agent where your design system lives and how to use it.

Here is a real-world CLAUDE.md snippet with design context:

# My SaaS Project

## Stack
- React 19, TypeScript, Vite
- CSS Modules for styling (no Tailwind)
- pnpm

## Design System
The project uses a captured design system. Always reference these files
when building or modifying UI components:

- @design/DESIGN.md — color tokens, typography scale, spacing, border-radius,
  shadows. Use the exact hex values and pixel values listed here. Do not
  invent new values.
- @design/STRUCTURE.md — page layout patterns, grid system, sidebar behavior,
  navigation conventions. Reference when building page-level components.
- @design/UI-KIT.md — component anatomy and variant patterns. Reference when
  building or extending individual components.

When in doubt about a visual value, look it up in DESIGN.md rather than
guessing. Consistency with the token system is more important than an
aesthetically pleasing one-off choice.

## Conventions
- Components in src/components/, one file per component
- Shared styles in src/styles/tokens.css as CSS custom properties
- No inline styles except dynamic values

The key instruction is the explicit directive: "use the exact values listed here" and "do not invent new values." Without this, Claude Code will sometimes pick visually similar values from its training rather than your spec. The directive closes that gap.

Step 4 — Reference files in individual prompts

CLAUDE.md sets the baseline. Individual prompts should reference specific files when the task involves them. Claude Code's @ file reference syntax brings the file content directly into the prompt context: 

Build a pricing card component. Requirements:
- Three tiers: Starter, Pro, Team
- Each card: plan name, price, feature list (5 items), CTA button
- Use color tokens from @design/DESIGN.md for background, border, and text
- Use spacing values from @design/DESIGN.md — the 8px base scale
- Use button patterns from @design/UI-KIT.md — primary variant for the
  featured tier, secondary for the others
- Featured tier (Pro): use the accent color as the card border, not just shadow

Stack: React functional component, CSS Modules.

Notice the specificity: "8px base scale" points the agent to a named construct in the file rather than leaving spacing to interpretation. "Primary variant for the featured tier" references a named variant from UI-KIT.md.

Prompt patterns that work

Reference by name, not description

Instead of: "use a light gray background"
Use: "use the surface-secondary token from DESIGN.md"

If your DESIGN.md labels token roles (primary, secondary, accent, destructive), use those labels. If it uses hex values without role labels, copy the exact value. Either is more precise than a description.

Scope the reference to the file

Instead of: "use the design system"
Use: "use the typography scale in @design/DESIGN.md"

Scoping to the specific file and the specific section within it reduces ambiguity. "Use the design system" is an instruction Claude Code will follow in spirit; "use the type scale in DESIGN.md, specifically the 13px / 15px / 20px / 28px steps" is an instruction it will follow exactly.

Tell the agent what not to do

Build a navigation bar matching STRUCTURE.md patterns.
Do not use Tailwind utilities. Do not introduce spacing values not
present in DESIGN.md. Do not add drop shadows unless they are documented
in DESIGN.md.

Negative constraints are underused in UI prompts. They eliminate the most common drift: the agent adding a box-shadow it finds aesthetically pleasing, or using a rounded-full on a button that should be rounded-md.

Ask for token comments in output

For each CSS value you write, add a comment referencing the
DESIGN.md token name or value it corresponds to. Example:
  padding: 16px; /* spacing-md from DESIGN.md */
  color: #F2F2F2; /* text-primary */

This makes output auditable. You can review the generated code, check each comment against your DESIGN.md, and immediately spot any values that drifted from the spec.

Keeping the design files current

Design systems evolve. When you update your production site — new brand colors, revised type scale, refined component patterns — re-capture with Design Catcher and replace the files in design/. The community cache means that if your site was captured before, re-capture will run fresh synthesis against the updated DOM.

Treat the design/ directory as source of truth, versioned in git alongside your code. Include it in code reviews when UI changes are significant. Update it when the design system changes. This discipline pays off as the project grows: six months in, you have a documented design system rather than tribal knowledge.

BYOK mode for private projects

The free tier uses shared GCP infrastructure with a 10-capture-per-IP-per-day limit. For private production sites you would prefer not to send through shared infrastructure, Design Catcher supports BYOK (Bring Your Own Key) mode: provide your own Gemini API key and synthesis runs directly from your browser to your API endpoint. No data touches Design Catcher's servers.

BYOK mode is also useful if you need to capture more than 10 pages per day — research sessions where you are comparing multiple source sites at once.

The workflow in one sentence

Capture once, reference in every prompt, update when the system changes. That is the entire discipline. Claude Code will do the rest.