A design system in a single markdown file. Tells your AI assistant how every screen, page, and component should look. Stops it from defaulting to glassmorphism, gradient hero sections, and three-column feature grids.
This is one of a family of five templates that customise AI for the way you actually work.
| Template | What it covers | When to do it |
|---|---|---|
| CLAUDE.md | Who you are, how you work, what's on your desk | First. Even if you do nothing else, this gets you 70% of the value |
| COPY.md | How things should sound. Voice + banned phrases | Second. Voice is the most-violated AI default |
| DESIGN.md (this repo) | How things should look. Design tokens + banned aesthetics | Third. Only if you make visual things (websites, slides, social posts) |
| CONTEXT.md | What each project is and where it's going | Per project, when you start working in a specific folder |
| NORTH-STAR.md | Career-level direction. The why behind the projects | Last, and only if you have multiple businesses or want to think strategically |
You don't have to do all five. The minimum useful set is CLAUDE.md + COPY.md. Add the others as you need them.
They reference each other. Your CLAUDE.md tells AI to read the others when the relevant work comes up, so you do not have to think about which file is needed when.
AI assistants have a default aesthetic and it's bad. Glassmorphism. Gradient backgrounds. Neon accents. Floating blobs. Three-column features sections. Same Tailwind buttons everyone has. That's not design, it's the visual equivalent of "delve" in copy.
A DESIGN.md is the brief that stops it.
This template aligns with a forming standard, not invents one. If anything in here is good, the credit goes to:
- Google Labs DESIGN.md spec published 22 April 2026. This template's structure follows that spec with a few additions.
- Brad Frost: Atomic Design for the philosophy that maps cleanly to tokens, components, patterns.
- Shopify Polaris for the rationale-first writing pattern (always explain why, not just what).
- Hardik Pandya: "Expose your design system to LLMs" for naming the failure mode I built around: unwired DESIGN.md files get ignored. The "wiring step" exists because of his article.
- VoltAgent's awesome-design-md for curating brand examples that showed what works across many categories.
What's mine is the non-tech-friendly framing, the "banned aesthetics" list with specific AI defaults, the conversational walk-through, and the integration with CLAUDE.md and COPY.md as a coherent family.
Three things they don't include:
- Plain-English explanations alongside the YAML (the bit at the top in
---marks, machine-readable), for non-technical owners who can't read design tokens - A "banned aesthetics" list that explicitly kills the generic-AI defaults
- Wiring instructions: the line you add to your CLAUDE.md so AI actually reads DESIGN.md (most templates skip this step, which is why they get ignored)
- Solo founders who need their AI assistant to design things consistently for their brand
- Designers working with AI agents and tired of fighting defaults
- Small teams sharing a single design source of truth via git
- Anyone using Claude, Cursor, v0, Lovable, or similar to generate UI
| File | What |
|---|---|
DESIGN.md |
The template. Walk through it with Claude (paste it into a chat) or fill it in by hand. |
README.md |
This file. |
LICENSE |
MIT. |
There are two ways to use this template:
- Open
DESIGN.mdin this repo, copy the whole file - Paste it into a Claude chat. Claude reads the meta-instruction at the top and walks you through it section by section
- Claude will propose specific colour values, fonts, and tokens based on your description of the feel
- At the end, you get a clean version (comments stripped) to save as
DESIGN.mdin your project folder
- Copy
DESIGN.mdto your project folder - Fill in the YAML frontmatter (your colour hex codes, font choices, spacing scale)
- Write the body sections (Aesthetic direction, Inspiration, Do's and Don'ts) in your own words
- Delete the HTML comments. Save.
Whichever way you use it, you must add this line to your CLAUDE.md so AI actually reads DESIGN.md before any visual work:
Read DESIGN.md before any visual or UI work. Use only the tokens defined in its frontmatter. Do not invent values.
Without that line, AI treats DESIGN.md as inspiration, not law. With it, AI treats it as a rule.
The standard DESIGN.md has twelve sections:
- Frontmatter: machine-readable tokens (YAML)
- Wiring: the line that goes in your CLAUDE.md
- Product context: who, what, what it isn't
- Aesthetic direction: the feel, references, decoration level
- Colour: palette, semantic roles, dark mode strategy
- Typography: families, scale, weight assignments
- Spacing: base unit and scale
- Layout: grid, max width, breakpoints
- Shape and elevation: radius scale, shadow tiers (or "no shadows" rule)
- Motion: easing, duration, when to animate
- Components: atoms with states, referencing tokens
- Do's and don'ts: guardrails and banned patterns
- Decisions log: date-stamped record of what changed and why
- Wire it explicitly via CLAUDE.md or AI ignores it. This is the single biggest finding. A DESIGN.md sitting unwired in the repo is treated as optional context.
- Banned patterns matter as much as preferred ones. "No glassmorphism" is more useful than "modern and clean."
- Keep total file under ~3,000 tokens. Larger files get partially ignored mid-context. Use variants for different scales.
- Tokens with prose, not tokens or prose. YAML alone leaves AI guessing when to use what. Prose alone leaves it inventing values.
- A decisions log compounds. Future-you needs to know why the radius is 4px and not 6px.
This is the highest-leverage section. The current AI defaults that this list is fighting:
- Glassmorphism (frosted glass effects)
- Gradient hero sections
- Neon glow, iridescent surfaces
- Floating blobs and organic shapes
- Three-column feature grids
- Dark mode by default
- Strokes and borders on cards
- Pill-shaped buttons everywhere
- Title case headings
- Em dashes in copy and labels
Edit the list to match your brand. The act of writing it down is what makes it stick.
- CLAUDE.md: context file Claude reads on every session
- CONTEXT.md: per-project context file
- NORTH-STAR.md: career-level direction
- COPY.md: brand voice and banned phrases
MIT.
Made by Catrin Donnelly.