Every session, your AI agent starts fresh. It picks generic colors, invents its own spacing, and drifts further from your actual UI. One Markdown file ends that.
Vibe coding works. You describe a feature, the AI builds it, you ship faster than ever. But spend a week on a product and you notice something: the button on page three uses a different blue than page one. The card padding is inconsistent. The font size on the new modal does not match anything else.
The AI did not forget. It never knew. Every prompt starts from zero.
This is the actual problem with vibe coding — not the code quality, not hallucinations, not even bugs. It is the drift. Session by session, page by page, the UI quietly loses coherence.
DESIGN.md is the fix. And paired with Google Stitch and Claude Code, it is quickly becoming the standard way serious builders approach AI-assisted frontend work.
What DESIGN.md actually is
It is a plain Markdown file. No proprietary format, no JSON schema, no Figma plugin required. You drop it in the root of your repo, and every AI agent that reads your project now knows your color palette, your type scale, your spacing system, your component rules.
A basic one looks like this:
# Design System
## Colors
- Primary: #1A73E8
- Background: #F8F9FA
- Text: #1F2937
## Typography
- Font: Inter, sans-serif
- H1: 32px / 500 weight
- Body: 16px / 400 weight
## Spacing
- Base unit: 8px
- sm: 8px, md: 16px, lg: 32px
## Components
- Button (primary): blue bg, white text, 4px radius
- Input: light gray border, 12px radius, focus outline
That is it. No tooling to install. Markdown is what LLMs read best — structured enough to parse, open enough to extend.
The file is not a design system tool. It is a design system memory. It tells the agent what decisions you already made so it stops inventing its own.
Where Google Stitch comes in
The blank-page problem with DESIGN.md is that you still have to write it in the first place.
Google Stitch solves this. It is an AI design tool from Google Labs that takes a natural language prompt — "dark SaaS dashboard, clean, muted greens" — and generates a full UI design. More importantly, it exports a DESIGN.md alongside the visual output.
So instead of writing the spec, you generate it. You explore in Stitch, pick a direction that feels right, and walk away with a Markdown file that encodes every visual decision that went into that design: the exact hex values, the type scale, the component patterns.
For most teams getting started, the file-based export is simpler; the MCP route is useful when you are actively iterating and want the code agent to stay in sync automatically.
Where Claude Code picks it up
Claude Code reads your repo. It picks up CLAUDE.md at the start of every session as a persistent instruction file — a place to write rules the agent follows across every run.
Add this to your CLAUDE.md:
## Design System
This project uses design.md at the project root.
Always refer to it when generating or modifying UI.
- Use only colors, fonts, and spacing from design.md.
- Do not introduce new values or defaults.
- Follow the component rules exactly.Now when you ask Claude Code to build a settings page or refactor a button, it does not guess. It reads DESIGN.md, finds the primary color, finds the button spec, and generates code that matches what already exists in your product.
The UI does not drift because the agent no longer starts from zero — it starts from your spec.
The workflow, step by step
1. Explore in Stitch. Describe your UI in natural language. Iterate on a few directions using Stitch's redesign tools until the look feels right.
2. Export DESIGN.md. Download the design file. Review it — adjust token names, add platform-specific notes, remove anything irrelevant. Treat it as a proposal, not a final truth.
3. Commit it to the repo. Drop DESIGN.md at the project root alongside CLAUDE.md. It is now version-controlled. Changes go through your normal PR process.
4. Instruct Claude Code. Reference DESIGN.md in your CLAUDE.md. From this point, every UI task Claude Code runs stays within your defined system.
5. Build and iterate. Add pages, components, and flows with natural language prompts. When the design evolves, update DESIGN.md first — the agent inherits the change on the next run.
Why this changes how vibe coding works
Vibe coding without DESIGN.md is fast but brittle. Every new session is a coin flip on whether the AI remembers your visual language. With DESIGN.md, the spec is always in context. Different contributors, different sessions, different prompts — they all produce UIs that share the same tokens.
The AI has constraints, and it works within them.
There is also a practical benefit beyond consistency: less rework. The biggest time sink in vibe coding is not writing prompts — it is fixing the output. "Change this blue to our brand blue." "Make the padding consistent." "Why does this button look different from the one on the home page?" DESIGN.md cuts that loop significantly. The first pass is much closer to correct.
And because DESIGN.md lives in version control, your design decisions are auditable. You can diff them, review them in PRs, and roll them back. Design intent stops living in chat history and starts living in code.
What it does not fix
Budget some time to clean up what it exports.
The agent still drifts occasionally. A large or ambiguous DESIGN.md gives Claude less to anchor to. Keep it focused — under 200 lines if possible. Specificity beats completeness.
It does not handle everything that design actually involves.
Format fragmentation is real. Different tools structure DESIGN.md differently. Until something like a common token schema emerges, expect to normalize the file when switching between tools.
Start today
You do not need to overhaul your workflow to try this. Pick one project. Open Stitch, generate a UI direction you like, and export the DESIGN.md. Drop it in your repo. Add three lines to your CLAUDE.md pointing at it. Then ask Claude Code to build your next component and watch what changes.
Add this to your CLAUDE.md:
The stack: design.md (the spec) + CLAUDE.md (the instruction) + Claude Code (the agent).
Stitch handles the blank page. DESIGN.md handles the memory. Claude Code handles the build.
That is the workflow. It is not complicated. It just works better than prompting from zero every time.
