DESIGN.md template: the structure every design file for AI agents needs
The DESIGN.md template behind every file in the freedesignmd library: YAML tokens on top, then ten sections an AI coding agent can follow without guessing. Copy the outline or start from a finished system.

Key takeaways
- A solid DESIGN.md template has machine-readable tokens on top and short, specific prose below.
- The ten sections run from color and type to components, a Do / Don't list and a tokens.css block.
- The fastest start is a finished file: all 31 systems in the library use this exact template.
A DESIGN.md template is the skeleton of a design system file: which sections exist, in which order, and what goes in each. Get the skeleton right and an AI coding agent can follow the file without guessing. This is the template every system in the freedesignmd library uses, explained section by section, with an outline you can copy.
The two layers of a DESIGN.md template
A good template has two layers that do different jobs:
- Frontmatter tokens in YAML at the top. Exact values the agent can read without interpretation: fonts, colors for light and dark, type roles, spacing, radius, shadow, motion and layout.
- Markdown sections below. The reasons and rules around those values: when to use the accent, how a card should feel, what never to do.
Tokens without prose produce correct but soulless screens. Prose without tokens produces screens with the right mood and the wrong values. You want both.
The frontmatter
This is a shortened version of the frontmatter of the Minimalistic system. The real file also lists every color role, all eight type roles, shadows, motion and layout.
---
name: "Minimalistic"
slug: "minimalistic"
schema: "freedesignmd/v2"
default_mode: "light"
fonts:
display: "Inter"
body: "Inter"
mono: "JetBrains Mono"
colors:
light:
background: "#ffffff"
foreground: "#1d1d1f"
primary: "#1d1d1f"
accent: "#e8f1ff"
ring: "#1e6ef4"
dark:
background: "#000000"
foreground: "#f5f5f7"
type:
h1: { font: display, size: 52, size_mobile: 35, leading: 1.06, weight: 500, tracking: "-0.03em" }
body: { font: body, size: 17, size_mobile: 17, leading: 1.53, weight: 400, tracking: "-0.01em" }
spacing: [4, 8, 12, 16, 20, 24, 32, 40, 56, 64, 88, 144]
radius: { sm: "10px", md: "16px", lg: "24px", xl: "28px", full: "9999px" }
---Notice what is not there: no adjectives. "Soft blue" is not a token. #1e6ef4 is.
The ten sections of the template
# Your Product, DESIGN.md
## How to use this file
## 1. Overview & personality
## 2. Color
### Light mode
### Dark mode
## 3. Typography
## 4. Spacing & layout
## 5. Shape & elevation
## 6. Motion
## 7. Components
### Button
### Input
### Card
### Badge
### Navigation bar
### Tabs
### Table
### Dialog / modal
### Text link
## 8. Imagery & iconography
## 9. Do / Don't
## 10. tokens.cssHow to use this file
The first section talks to the agent directly. It says where the file lives, where the tokens go, and the exact line to add for each tool: a line in CLAUDE.md for Claude Code, a rule in .cursor/rules/design.mdc with alwaysApply: true for Cursor, and Project Knowledge for Lovable. It also says to use semantic names only, and that a value not in the file does not belong in the UI.
1. Overview and personality
A short paragraph on how the product should feel, then an "at a glance" list (aesthetic, industry, default mode, fonts, brand color, corners, container width, base motion) and the signature moves: the three to six things that make this system recognizable.
2. Color
A table per mode with role, CSS variable, value, contrast and usage. Roles, not names: background, foreground, primary, muted-foreground, border, ring, destructive, plus chart colors in order. Agents that ask for "primary" instead of a hex value stay on brand.
3. Typography
Every type role (display, h1 to h3, body, small, label, mono) with font, size, mobile size, line height, weight and tracking. This is where most generic AI UI goes wrong, so be exact.
4. Spacing and layout
The spacing scale, container width, columns, gutter, section padding and reading measure.
5. Shape and elevation
The radius scale and shadows for light and dark. A small named menu (sm, md, lg, xl, full) stops the agent from inventing a new radius per component.
6. Motion
Durations, easing curves and reveal rules. Without them, every hover gets a different speed.
7. Components
Recipes as HTML and CSS for the components agents build most: button, input, card, badge, navigation bar, tabs, table, dialog and text link. Recipes beat descriptions because the agent can copy the structure.
8. Imagery and iconography
What photos and illustrations look like, and which icon style and stroke to use.
9. Do / Don't
The most underrated section. Name the mistakes you expect: glass on content cards, bold headings, a second accent color. Agents follow explicit "don't" lines well.
10. tokens.css
The tokens as CSS variables for light and dark, ready to paste into a global stylesheet. The library also includes a Tailwind v3 config block.
How long should a DESIGN.md be?
Long in tokens, short in prose. The token tables and component CSS can run to hundreds of lines and that is fine: they are lookups, not reading. The paragraphs around them should be a few sentences each. If a paragraph does not change what the agent builds, cut it.
Fill in the template or start from a finished one?
Writing every section from scratch is real work. For most projects it is faster to take the closest of the 31 DESIGN.md examples, keep its structure, and change the primary color, fonts and personality. If you do want to write your own, the step-by-step is in how to write a DESIGN.md.
Where the template sits next to other agent files
DESIGN.md holds the look. CLAUDE.md, AGENTS.md and Cursor rules hold how the agent should work, and point to DESIGN.md for anything visual. If you are unsure what goes where, read DESIGN.md vs CLAUDE.md vs Cursor rules and AGENTS.md and DESIGN.md.
Use it in the library
Frequently asked questions

Written by Tammo Elsner
Founder of freedesignmd, a free DESIGN.md library for AI coding agents. About the project · LinkedIn


