Design systems with AI: from brand chaos to one Markdown file
Here's the problem everyone hits the moment they let AI generate UI: the output looks different every time. A landing page with an ocean-blue hero, a dashboard with violet buttons, a deck with red accents — none of it reads as the same brand.
The fix is boring, small and powerful: a design spec file. One Markdown document the AI reads before every generation. It's the difference between "an AI made this" and "our team made this with AI".
DESIGN.md: the one-file design system
The pattern got its name and its momentum from the open-source awesome-design-md collection — 73 real brand specs, 100K+ stars, written in one format. The premise: if your design system lives in one Markdown file, any agent (Claude, Codex, Figma plugins, your own scripts) can consume it. No Figma handoff, no token export script, no "please read the style guide PDF".
What a good DESIGN.md contains
- Identity — one paragraph on the brand: who it's for, the personality (e.g. "expert but warm, never flashy").
- Color — the palette as named tokens, plus explicit usage rules ("accent only for the primary action").
- Typography — font choices, scale steps, and when to use each size/weight.
- Spacing & layout — the rhythm: 8px grid, max container widths, gutter rules.
- Components & states — buttons, inputs, cards — and how they change on hover/press/disabled.
- Voice & tone — words matter in design; say "never use exclamation marks in headlines".
- Anti-patterns — explicitly list what the brand never does (this is gold for keeping AI honest).
Generating yours: extract, don't invent
For most brands, the fastest route isn't writing from scratch — it's extracting from what already exists. The DESIGN.md Chrome extension reads a live site and emits a spec file in one click. Run it on your current site, your best competitor-free reference, or even an old brand PDF, then refine.
If you're starting cold, generate a draft with your AI tool of choice, then spend 20 minutes making it strict. A spec that says "primary blue" is noise; a spec that says "primary: #1E3A8A, used for CTAs and links only; never for backgrounds" is leverage.
Example skeleton
# Brand: Northwind
Identity: calm, precise, independent. Think Scandinavian furniture, not tech hype.
# Color
--ink: #16161A /* text & headers */
--paper: #FBF8F2 /* page background */
--accent: #C2442C /* CTAs, links, hover; never backgrounds */
# Typography
Display: Georgia, serif — headlines only
Body: Inter, sans-serif — 16-18px, 1.6 line height
Rules: never use ALL CAPS headings; never center body text
# Component: Button
Default: ink background, paper text, 6px radius
Hover: accent background
Disabled: 40% opacity, no shadow
# Anti-patterns
- No gradients, ever
- No emoji in UI (icons are line SVG only)
- No dark mode (single light theme)
- No stock photo clichés (handshake, skyscraper, puzzle pieces)Using the spec in your workflow
- Attach it to every generation — paste it at the top of every prompt, or put it in the agent's system context. Consistency comes from the AI never *not* seeing it.
- Reference token names, not values — "use --accent for the button" beats "use #C2442C" because the spec stays the single source of truth.
- Review against the spec, not taste — when an output looks wrong, check the spec first: did the AI violate a rule, or is the rule wrong? Fix the file, not the prompt.
Beyond one file
When your system outgrows a single file, split it the same way codebases split modules — tokens, components, voice, patterns — but keep a master index that references them all. The agents don't care; they read whatever structure you give them. The humans care a lot: a system you can't navigate is a system nobody maintains.
Browse more design-system tools in the resource library.