Skip to content

Search design systems

Search for a design system by domain or name

Back
·7 min read

The DESIGN.md File Format Explained

By DesignMD Team

A DESIGN.md file in one screen

To understand the DESIGN.md file format, it helps to read one directly. The file acts as the bridge between human designers and AI coding agents.

Here is what a complete, highly-rated extraction looks like. If you browse our gallery or view the Stripe design system breakdown, you will see files that look exactly like this structure.

markdown
---
version: "alpha"
name: "Example SaaS"
colors:
  primary: "#635BFF"
  surface: "#FFFFFF"
  textPrimary: "#111827"
typography:
  fontFamily: "Inter, sans-serif"
  fontSize: "16px"
spacing:
  sm: "8px"
  md: "16px"
---

## Overview
This file defines the visual identity for Example SaaS.

## Components

### Primary Button
The primary action button uses the {colors.primary} background and {colors.surface} text.

The format is intentionally plain. It requires no specialized parsers or proprietary tools to read, yet it provides the exact structure a Large Language Model needs to write accurate user interfaces. To see how this compares to other approaches, read our breakdown of design tokens vs CSS variables.

The frontmatter block

The top of the file contains a YAML frontmatter block. We use YAML because it's the industry standard for metadata in markdown files.

This block is strictly for the machine. It serves as an exact dictionary. Required fields include the file version, the project name, and explicit blocks for colors and typography. By placing variables here, the AI agent has a guaranteed, static lookup table. It never has to guess what "blue" means; it simply references the hex code defined in the YAML.

Optional blocks include spacing, border radius, and shadows. The structure forces absolute precision. For a more technical breakdown of the schema requirements, consult the full DESIGN.md specification.

The body sections

Below the frontmatter, the file switches to standard markdown.

Markdown headings matter a lot for AI parsing. Large Language Models assign semantic weight to H2 and H3 tags. When an agent reads "## Colors," it primes its attention mechanism to absorb the subsequent text as visual constraints.

The recommended section order moves from abstract to concrete. It starts with an Overview, defines the base tokens (Colors, Typography, Spacing), and then builds up to specific UI blocks (Components). This sequence ensures the AI builds its internal context sequentially, just as a browser cascades its styles. If you need a refresher on the foundational concepts, review our guide on what DESIGN.md is.

Token references

The body text uses a specific syntax to refer back to the YAML frontmatter: the {colors.primary} syntax.

This curly-brace dot-notation is the connective tissue of the file format. When the markdown text says a header requires a {typography.fontSize} of 24px, the dot notation instructs the AI to perform a dereferencing operation. The agent looks up the exact value defined at the top of the file.

If a reference is broken—perhaps a developer deleted a color from the YAML but left the reference in the markdown—the extraction pipeline catches it. You can learn more about how validation works in our guide to confidence scores and design extraction.

The components block

The components block demonstrates how the foundational tokens combine into interactive elements.

This section defines the style, variant, and state fields for core UI pieces. We intentionally limit this section to a small set of foundational elements: primary button, secondary button, card, and text link.

We restrict the list because AI agents are highly capable of extrapolating. If an agent understands how your primary button uses border radius and hover states, it can accurately infer how a dropdown menu or a modal should look. The file provides the seed logic; the AI handles the expansion.

Do's and don'ts

The final recommended section is the opinionated guidance block: Do's and Don'ts.

This section works exceptionally well for AI grounding. While the frontmatter provides the variables, the Do's and Don'ts section provides the guardrails. A rule like "Do not use {colors.primary} for background surfaces" prevents the agent from generating visually aggressive layouts. It acts as a negative prompt, filtering out common hallucinations before the AI writes a single line of code.

How agents actually consume the file

When you drop this file into your repository and start an AI session, the process is seamless.

During a prompt-to-output cycle, the agent reads the entire file into its context window. It indexes the YAML block into its working memory. When you ask it to "build a pricing card," it scans the markdown body for the "Card" component definition.

It ignores narrative filler and locks onto the token references. It sees that a card requires {colors.surface} and a {spacing.md} padding. It looks up those exact values from the YAML memory bank and generates the corresponding React or HTML code, perfectly aligned with your brand.

Frequently asked questions

What does the YAML frontmatter do?

The YAML frontmatter provides a strict, machine-readable dictionary of your design tokens, ensuring the AI uses exact hex codes and pixel values.

Do I need to define every component?

No. The file only needs to define core elements like buttons and cards. The AI extrapolates the rest of your UI based on those foundational examples.

What happens if a token is missing?

If a reference in the markdown points to a missing YAML key, the built-in linting process will catch it and flag it as an error.

Get Started

See a real DESIGN.md file — browse 50+ extracted from popular sites. Head to the designmd.run gallery to explore the format in action.