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.

Argent Machined design system preview, built from the DESIGN.md template

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.

DESIGN.md (frontmatter, shortened)
---
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

DESIGN.md outline
# 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.css

How 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.

Frequently asked questions

The structure of a design system file for AI coding agents: YAML frontmatter with exact tokens, followed by sections for color, typography, spacing, shape, motion, components, imagery, a Do / Don't list and a tokens.css block.

How to use this file, then 1 Overview and personality, 2 Color, 3 Typography, 4 Spacing and layout, 5 Shape and elevation, 6 Motion, 7 Components, 8 Imagery and iconography, 9 Do / Don't and 10 tokens.css.

Yes. Every one of the 31 design systems on freedesignmd is this template filled in. Copy the closest one and change the brand color, fonts and personality.

Both. YAML frontmatter gives the agent exact values to read, and a tokens.css block gives your project the same values as CSS variables. Keep them in sync by generating one from the other.
Tammo Elsner, founder of freedesignmd

Written by Tammo Elsner

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

Keep reading. More on DESIGN.md.

Clinic Pearl design system preview, a calm healthcare DESIGN.md

DESIGN.md

How to write a DESIGN.md file your AI coding agent actually follows

A step-by-step guide to writing a DESIGN.md: start from a feeling, turn it into exact tokens, write component recipes and a Do / Don't list, then test it with one screen.

Nov 16, 2026 · 4 min read

Linear Orbit, one of the DESIGN.md examples: a dark hairline product workspace

DESIGN.md

31 DESIGN.md examples for AI coding agents, by style and industry

Every DESIGN.md example in the freedesignmd library, grouped by style and industry, with what each one is built for. Pick the closest one, copy it, change the brand color.

Nov 16, 2026 · 8 min read

free design.md library

DESIGN.md

What is a DESIGN.md file? The design spec AI coding agents read

A DESIGN.md file is one markdown document that tells AI coding agents how your product looks. What it is, why it works better than a Figma link, and how to wire it into Claude Code, Cursor and Lovable.

Nov 16, 2026 · 7 min read

Start with a free DESIGN.md. Or install a component.

Free design systems, React components and landing page templates for Claude Code, Cursor, Lovable and v0. No signup.