What is a design.md file, and how should AI coding tools use it?
A design.md is a design system written for a reader that never attends design reviews: an AI coding tool. It's plain markdown, lives in the repository next to the code, and states the design's rules with exact values.
Why markdown, why in the repo
AI coding assistants read project files. A design specification that lives in Figma, a wiki, or someone's head is invisible to them - so they fall back on defaults, and the defaults are generic. A markdown file in the repo is context they parse natively: headings give structure, tables give values, and prose gives the why that keeps decisions consistent.
What belongs inside
The useful core, in rough priority order:
- Identity - two paragraphs on what makes this design itself. This steers a model's thousand small choices more than any table.
- Color roles - each color with its exact value and its job: "background", "primary action", "text-secondary". One canonical role table prevents drift.
- Type hierarchy - a table of roles (display, heading, body, caption…) with family, size, weight, line-height, and tracking.
- Component specs - the recurring components with real dimensions and their hover/focus/active states.
- Spacing and radii - the scale, and where each step is used.
- Motion - durations, easing curves, and what is not animated.
- Do / Don't rules - explicit constraints ("never use pure black", "shadows only on overlays"). Models follow constraints better than descriptions.
How tools should consume it
- As standing context: reference the file once ("all UI follows design.md") and let every generation inherit it.
- As a review checklist: after generating UI, ask the assistant to audit its own output against the file.
- As per-component prompts: for high-fidelity single components, a prompt with the exact values inlined beats a general reference.
Mateo generates this file automatically from a URL, a screenshot, or both - but the format is worth adopting even if you write yours by hand.