This website was rebuilt from scratch this week. Not with a new design tool or a new framework — but with a new process. Instead of starting in Figma or writing CSS by hand, I wrote a DESIGN.md file: a plain-text design system specification that an AI coding agent can consume and implement.
The DESIGN.md philosophy
The idea is deceptively simple. A single markdown file in your project root — DESIGN.md — contains a complete design system: colors with semantic names and roles, a full typographic hierarchy, component specifications with states, spacing scales, shadow systems, and design guardrails. An AI agent reads it and generates consistent UI.
No Figma exports. No JSON token schemas. No special tooling. Just structured prose in the format that language models read natively.
The philosophy comes from the awesome-design-md project, which curates DESIGN.md files extracted from the public-facing design of companies like Apple, Stripe, Linear, and Vercel. Each one captures the visual DNA of a brand in a form an agent can understand.
Why this works
Three things make this approach powerful:
Readability by AI agents is the primary constraint. Markdown is what LLMs read best. By making the design system text-first, you optimize for the consumer that matters most in an AI-assisted workflow.
Token completeness forces clarity. Every color must include a semantic name, a hex value, and a functional role. You can’t just write #b5643c — you have to explain that it’s the copper accent reserved for primary CTAs and should appear at most twice per viewport.
Do/Don’t lists encode taste. The guardrails section tells agents what not to do, which is often more important than what to do. “Don’t use pure white or pure black.” “Don’t add new accent colors.” These constraints are what keep a system coherent when an agent is generating code.
Building this site
I wrote the DESIGN.md for this site in about an hour — defining a warm editorial palette (cream canvas, burnished copper accent, warm ink), a serif/sans typographic hierarchy (Source Serif 4 for editorial, Inter for UI), and a set of component patterns (frosted nav, subtle depth cards, hairline dividers). Then I handed it to Claude Code and said: rebuild the site.
The result is what you’re reading now. Every color, every type size, every shadow on every card — all generated from a single markdown file.
The broader shift
I think DESIGN.md points toward something significant about how design systems will evolve. As AI agents become the primary implementation layer between design intent and production code, the format of the design specification matters more than ever. A design system that an agent can’t read isn’t really a system — it’s a picture of one.
The plain-text design system is not a replacement for visual design tools. But it is becoming the most important artefact in the handoff. Write it well.
Comments