DESIGN.md: Fix AI UI Inconsistency

Problem: Claude Code has strong local context and weak product context. It knows the file it's editing. It does not know what your product is supposed to look like. Between sessions, your design system evaporates. Buttons appear where links should be. Empty states go missing. A color that was #E07850 in one component becomes orange-400 in the next.

Quick Win: Drop a design.md file at project root and reference it from CLAUDE.md. Your design values travel with the codebase. Every session starts with the same constraints in context.

What design.md Actually Is

A design.md file is a plain-text design system. No special syntax. No tooling required. Colors, spacing, typography, component rules, and interaction states written in readable Markdown.

Google Stitch introduced the format in March 2026 and positioned it as interoperability infrastructure, similar to how README.md became a universal convention. The awesome-design-md collection on GitHub hit 62.3k stars by April 2026 and includes 60+ brand design systems in the format: Stripe, Linear, Supabase, Vercel, Notion, and others.

The idea is simple. Claude Code reads files. If the design system is a file, Claude Code reads the design system.

Why Sessions Drift Without It

Claude Code loads context at the start of each session. It reads CLAUDE.md, scans open files, and builds a picture of your project. Without an explicit design file, there is nothing tying UI decisions to a source of truth.

You might describe the primary color in a comment somewhere. Or a Tailwind class in one component. Claude reads whatever it opens first and extrapolates from there. Three sessions in, your UI is a collection of best guesses.

A design.md file in CLAUDE.md changes the input. Values are explicit, not inferred. Every session opens with the same source of truth in context.

Get design.md from Google Stitch

Google Stitch is a UI design tool from Google Labs, launched at Google I/O in May 2025. It runs on Gemini 2.5 Pro, lives at stitch.withgoogle.com, and is free during the Labs phase (Google account, no waitlist, 350 generations per month on the free tier). The design.md export landed in Stitch 2.0 on March 18, 2026.

The workflow to generate your file:

1. Go to stitch.withgoogle.com. Click the Web tab (not App). Select the highest Pro model available.
2. Optionally upload a reference screenshot of your current UI or an inspiration image.
3. Write a brief describing your brand: colors, tone, component style, what the product does.
4. Iterate conversationally until the output matches your intent.
5. Click Export, choose DESIGN.md, save the file to your project root.

Stitch builds a structured file covering color tokens, typographic scale, spacing units, component patterns, and state definitions (hover, focus, active, disabled). The output is portable. It works with Claude Code, Cursor, Windsurf, or any tool that reads files.

Wire CLAUDE.md to the File

Dropping design.md in the root is not enough. Without explicit instructions in CLAUDE.md, Claude treats the file as reference material it may consult. With explicit instructions, Claude treats the values as constraints it must follow.

The block that works:

## Design System
This project uses a design system defined in `design.md` at the project root.
Always refer to this file when generating or modifying any UI component.
- Use only colors, fonts, and spacing values defined in design.md.
- Do not invent new values or use defaults from any framework.
- Match component states (hover, focus, active, disabled) to the patterns in design.md.
- Follow the typographic scale and weight assignments in design.md.
@design.md

The @design.md import at the bottom injects the full file contents at session start. The four bullet points turn a passive reference into active constraints. Both parts matter. The import alone gives Claude a document. The instructions give Claude a rule.

Verify the Wire Before You Build

After updating CLAUDE.md, confirm Claude actually loaded the values correctly:

Ask Claude: What primary color is defined in design.md?

If it returns the correct hex, the import is working. If it hedges or guesses, check that @design.md appears at the end of the block and that the file path is exactly right (case-sensitive on Linux).

Run this check at the start of any session involving UI work. It takes ten seconds and catches a missing import before it becomes a drift problem.

Add a Tailwind Enforcement Layer

CLAUDE.md is context. Tailwind is enforcement. The two work together.

Translate your design.md token values into tailwind.config.js. When Claude writes bg-blue-500 instead of bg-primary, the build fails. That is the correct behavior. A type error at build time beats a visual inconsistency you catch on the fourth screen.

A minimal config block for a two-color brand looks like this:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#E07850',
        'primary-dark': '#C5613A',
        surface: '#1A1A1A',
        'surface-elevated': '#1E1B18',
        text: '#FFFFFF',
        'text-muted': '#999999',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
    },
  },
}

Any value in design.md should have a named token in this config. Claude then writes tokens, not raw values. The build catches anything that slips through.

Six Failure Modes

These are the ways the setup breaks in practice.

Export too early. Stitch generates placeholder colors and missing states if your brief is thin. Iterate until the output is complete before exporting. Gaps in design.md become gaps in Claude's constraints.

Vague CLAUDE.md instructions. The import alone is not enough. The four bullet points in the block above turn a document into a ruleset. Without them, Claude reads the file and then decides how much to follow it.

No Tailwind translation. Drift caught in a visual review after four screens costs more than a build error caught after one component. Add the config layer before you start building.

design.md not in version control. If it's not in the repo, a new clone or a new team member starts with no design system. Commit the file the moment you create it.

Stale file after redesign. When you change the brand, re-export from Stitch. A design.md that describes last quarter's colors is worse than no file at all: it gives Claude confident wrong answers.

Context rot in long files. Information in the middle of a long context window is recalled less reliably than information at the start or end. Keep design.md under 2,000 to 3,000 tokens. Split by category (color, typography, spacing, components) if the file grows past that.

Alternatives to Stitch

Stitch is the fastest path to a complete design.md, but four other approaches work.

Manual extraction from DevTools. Open Chrome DevTools, inspect key elements (buttons, headings, cards), copy the computed CSS to Claude, then ask: Turn this into a design system as a markdown file. Five minutes. Works well for existing products where you need to capture the current state rather than define a new system.

awesome-design-md on GitHub. The collection at github.com/VoltAgent/awesome-design-md has 60+ brand design systems in DESIGN.md format as of April 2026. If you're building something adjacent to an existing brand aesthetic, start from a reference and edit rather than generating from scratch.

Figma MCP. Claude Code connects to Figma directly through MCP and reads design tokens in real time. A case study from Parallel HQ reported 62% fewer design inconsistencies and 78% better workflow efficiency across six months. The tradeoff is authentication friction. Stitch exports a self-contained file; Figma MCP requires a live connection and token management.

Extract from a URL. Stitch accepts public URLs as input. Paste a clean marketing site URL and Stitch reads the visual style. Works well for clean public-facing pages, struggles with authenticated dashboards.

Claude Design vs. design.md

Claude Design launched on April 17, 2026, powered by Opus 4.7 with a new 2,576px vision mode. It creates visual work through conversation and produces a handoff bundle inside the Anthropic ecosystem. One edtech company reported that pages needing 20+ prompts on other tools needed only 2 in Claude Design.

The difference from the design.md workflow comes down to portability. Claude Design produces artifacts tied to the Anthropic stack. A design.md from Stitch is a plain file that works with any tool that reads files: Claude Code, Cursor, Windsurf, or a custom build script.

Claude Design is faster if you stay inside the Anthropic ecosystem. design.md is better if you want the design system to travel with the codebase, version-controlled alongside the code it governs.

What You Get

One file in the repo root. Four lines in CLAUDE.md. Named tokens in tailwind.config.js.

Every session opens with the same design constraints in context. Every build fails on raw values instead of letting drift accumulate. Every screen Claude touches follows the same rules as the last one.

Design consistency is not a review process. It is a file.

Common Questions

What is design.md in Claude Code?

design.md is a plain-text file at your project root that defines your design system: colors, typography, spacing, component rules, and interaction states. When referenced in CLAUDE.md with the @design.md import, Claude Code loads these values at session start and treats them as constraints rather than suggestions, keeping every screen consistent across sessions.

How do I use design.md with Claude Code?

Export a design.md file from Google Stitch or write one manually, place it at your project root, then add a ## Design System block to CLAUDE.md that includes the @design.md import and four bullet-point rules. Finally, translate your token values into tailwind.config.js so the build fails on any raw value that bypasses the system.

Is Google Stitch free?

Yes, during the Google Labs phase. The free tier at stitch.withgoogle.com includes 350 generations per month with access to all core features and requires only a Google account with no waitlist. Stitch 2.0, which introduced the design.md export, launched on March 18, 2026. Pricing may change when Stitch exits the Labs phase.

What is the awesome-design-md repo?

awesome-design-md is a GitHub collection maintained by VoltAgent at github.com/VoltAgent/awesome-design-md. It contains 60+ ready-to-use DESIGN.md files modeled on real brand design systems including Stripe, Linear, Supabase, Vercel, and Notion. You can drop one directly into your project as a starting point and edit it to match your brand rather than generating from scratch.

How do I stop Claude Code from ignoring my design system?

Two things are required together, not separately. First, add the @design.md import at the end of the design block in CLAUDE.md so the file contents load at session start. Second, add explicit bullet-point rules above the import that tell Claude to use only values from the file and not invent new ones. The import alone gives Claude a document; the rules give Claude a constraint.

design.md vs Figma MCP: which is better for Claude Code?

They solve the same problem differently. Figma MCP connects Claude to Figma in real time, giving it access to live design tokens and components, but it requires authentication setup and a persistent connection. A design.md from Stitch is a self-contained file that works offline, travels with the repo, and version-controls alongside your code. Figma MCP suits teams already deep in Figma; design.md suits solo builders who want zero infrastructure.