How to Write DESIGN.md Files That AI Agents Can Actually Follow

A structured DESIGN.md file helps AI agents apply design systems correctly by explaining intent and rules rather than just listing token values. For example, instead of stating a color hex code, effective prose explains that a color is reserved for the single most important action on screen. Large language models parse markdown with high fidelity, making well-written prose an efficient channel for communicating design rationale. Key sections include an overview, color roles, typography, layout, and a Do's and Don'ts list that sets hard guardrails against common mistakes. The core principle is that tokens tell an agent what a value is, but only prose tells it how and when to use that value.