Glossary
What is DESIGN.md?
A design brief for coding agents so generated UI looks like your product.
Updated 2026-09-09
DESIGN.md is a file that records the visual direction of a project so an agent building UI follows your design language instead of its own defaults.
It exists because of a very specific problem. Ask any agent for a landing page and you get the same output: a purple to blue gradient, oversized rounded corners, a pricing table nobody asked for. The model has no idea what your product looks like, so it falls back to the average of its training data. DESIGN.md is where you tell it.
What actually helps is specific: the type scale and font families, hex values with their roles, border radius, spacing rhythm, density, motion rules, which components to reuse instead of inventing, and one or two reference products for tone. Google Labs published a spec for the idea and a handful of generators will draft one from a screenshot or a live site, which is a reasonable starting point before you edit it by hand.
This is the newest of the agent markdown conventions and the least settled, so treat it as a house convention rather than a standard. The value is not the file name. It is having your visual decisions written down somewhere an agent can read.
DESIGN.md, the parts that matter
## Type
- Display: Fraunces, 600. Body: Geist Sans, 400. Mono: IBM Plex Mono.
- Scale: 12 / 14 / 16 / 20 / 28 / 40. No sizes in between.
## Colour
- paper #0B0B0C ink #F4EFE7 ink-soft #A8A29B
- ember #E1613A is the only accent. One accent per screen.
## Shape and space
- Radius: 0 for cards and inputs. Full only for pills.
- Spacing: multiples of 4. Section padding 40 mobile, 56 desktop.
## Rules
- No gradients. No drop shadows. Borders do the separation.
- Reuse Button and Card from components/ui. Do not create variants.Where people get this wrong
- Adjectives do not survive the trip. Clean and modern means nothing. Numbers, hex values, and component names do.
- Keep it next to AGENTS.md and reference it from there, or agents that only read one file never see your design rules.
- It goes stale fast. When the design changes and the file does not, agents confidently ship last quarter's look.