What is a DESIGN.md file, and how does it relate to the Rebuild Package?

← All guidesOctober 28, 2026 · 2 min read

A DESIGN.md is a design system written for a reader that never attends design reviews: an AI coding agent. It is plain markdown, it lives in the repository next to the code, and it states the design's rules with exact values.

Why markdown, why in the repo

Coding agents read project files. A design system that lives in a design tool, a wiki or someone's head is invisible to them, so they fall back on their defaults, and the defaults are generic. A markdown file in the repo is context they read natively: headings give structure, tables give values, and prose gives the why that keeps decisions consistent.

What Mateo puts inside

Every Mateo capture includes a DESIGN.md that covers the design language only:

  • Colors, with the role each one plays
  • Typography, as a hierarchy of roles with family, size, weight and line-height
  • Spacing and radius scales
  • Components, with their dimensions and states
  • Motion: durations, easing and what moves
  • Responsive behavior
  • Do's and don'ts: explicit constraints, which agents follow better than descriptions

It contains no content and no assets from the source site. That is the point: it describes how a site looks, not what it says.

DESIGN.md and the Rebuild Package

The two outputs answer different questions.

The Rebuild Package answers "how do I rebuild this page?". It is a folder for your coding agent: REBUILD.md (the build specification), evidence.json (every measured value), screenshots/ (visual ground truth), assets/ (the site's original downloadable assets), AGENT_PROMPT.md (the ready-to-paste agent prompt) and DESIGN.md as a supporting reference. Use it for sites you own or have permission to reproduce.

DESIGN.md on its own answers "how do I build something new that feels like this?". Use it to borrow the look of a site you don't own: export the file, drop it into your project, and tell your agent that all UI work follows it.

Inside a Rebuild Package, DESIGN.md plays a supporting role. REBUILD.md and evidence.json carry the measured page, and when anything is ambiguous, evidence.json wins.

How agents should use it

  • As standing context: reference the file once ("all UI follows DESIGN.md") and let every task inherit it.
  • As a review checklist: after the agent writes UI, ask it to audit its own output against the file.
  • For precision work: when one component must be right, point the agent at that component's section.

Read more in Understanding DESIGN.md and The Rebuild Package.