Documentation

What is DESIGN.md?

A DESIGN.md is a plain-text design system document that AI coding agents read to generate consistent UI. Think of it as the design counterpart to AGENTS.md orREADME.md — humans and agents can both read it, edit it, and enforce it.

Under the hood, DESIGN.md has two layers:

• YAML front matter — machine-readable design tokens (colors, typography, spacing)
• Markdown body — design rationale explaining how and why to apply the tokens

What's Inside

A DESIGN.md typically includes eight canonical sections:

How to Get One

Using with AI Agents

Three simple steps:

1. 1Get or create your DESIGN.md file
2. 2Place it in your project root or docs/ folder
3. 3Tell your AI agent: “Use DESIGN.md as the style guide”

# Tell your AI agent:
"Read DESIGN.md and use it as the style reference
for all UI components in this project."

Supported Tools

Any AI coding tool that reads markdown files can use DESIGN.md:

Best Practices

• Keep DESIGN.md in the project root for easy discovery
• Update it when your design changes — it's a living document
• Use it as the single source of truth for visual decisions
• Pair with AGENTS.md for behavior rules + style rules
• Include both tokens (YAML) and rationale (markdown prose)
• Reference it in your AI prompts explicitly