How to Write DESIGN.md Prose That AI Agents Actually Follow

Short summary

Write design system documentation that teaches AI agents the reasoning behind design choices, not just token values. Well-structured prose explaining intent and hard rules lets agents generalize to cases you never covered. A strong Do's/Don'ts section directly prevents off-brand outputs by setting guardrails on accent usage, contrast ratios, and component mixing.

• •Prose explains intent and rules; tokens alone are insufficient for agent generalization
• •Structure: Overview, Colors, Typography, Layout, Do's/Don'ts — each section removes a category of agent errors
• •Focus effort on the rationale, not the values; good prose turns design tokens into design identity

Generated with AI, which can make mistakes.