What is design.md? Design System File for AI

design.md is a markdown file that documents a complete design system in plain text: color tokens for light and dark mode, a typography scale, spacing and radius rules, component specs, motion, accessibility rules and brand voice. Because it is plain markdown, AI coding tools and human developers can both read it as context.

The name follows the convention of README.md and CLAUDE.md: a markdown file with a job. README.md explains a project, CLAUDE.md briefs a coding agent, and design.md carries the design system. Logofai introduced the format, and its design.md generator produces the file from a logo.

A design.md file gives AI coding tools the context they otherwise guess at. Paste one into Cursor, Claude Code, v0, Lovable or Bolt and the tool stops inventing colors and fonts and starts following yours: every button uses your exact primary hex, every heading uses your typeface, every card follows your radius and shadow rules. The file contains twelve sections: brand essence, color tokens as CSS variables for light and dark mode, a full type scale, spacing and layout rules, button, card and form specs, voice and copy guidance, motion, accessibility minimums, logo usage and a do-and-don't table. Logofai generates the entire file from a logo in about a minute, together with a live HTML style guide and matching developer exports: tokens.css, tailwind.config.js and tokens.json. The same source of truth then works pasted in a prompt, committed to a repo, or handed to a designer.

What does a design.md file contain?

Every Logofai design.md follows the same twelve-section structure. It opens with brand essence, three lines that pin down the attitude, then moves through color tokens (CSS variables with usage notes, light and dark mode), typography (a Google Fonts pairing and an 11-level type scale), spacing and layout, button specs, card specs, form specs, voice and copy, motion, accessibility, logo usage, and a closing do-and-don't table that summarizes the whole brand as decisions a builder can follow.

Here is the actual opening of the design.md generated for Strike9, a streetwear brand from our case study gallery:

# DESIGN.md · Strike9

## 1. Brand essence
- Loud discipline: high-impact, never sloppy.
- Night-market grit: built for concrete, queues, clubs, and cold sidewalks.
- Sharp confidence: graphic, direct, and cut with intent.

Tagline: Built loud. Cut for the street.

How does design.md relate to design tokens?

They answer different questions. A design.md carries the reasoning, usage notes, component specs, voice and do-and-don't rules, in text an AI tool or a person can read. Design tokens carry the raw values a build imports. A Logofai run produces both from the same logo, so they cannot disagree. We compare the two properly, and explain why a hand-off needs each, in brand guidelines vs design tokens.

How do you create a design.md?

You can write one by hand, and some teams do, but the point of the format is that it can be generated. In Logofai you pick or upload a logo, optionally add a brand name and art direction, and generate: the palette is extracted from the mark itself, typography is paired to match, and the complete file arrives in about a minute. A generation costs 9 credits and is available on the Pro and Business plans; failed runs refund automatically.

How do AI tools use a design.md?

Drop the file in your repo root and mention it in your prompt, or paste it at the start of a session. Cursor and Claude Code treat it as project context; v0, Lovable and Bolt follow it from the first render. The practical setup, with real prompts and file placement, is covered step by step in our guide to giving Cursor your brand style with design.md.

Want to read a full example first? The complete, unedited Strike9 file lives on the design system generator page, with the style guide the app rendered from it.

If you would rather see the finished article than read about it, there is a complete design.md example you can copy in full, and a guide to writing one yourself that covers the sections in order. If you are weighing this against a traditional brand document, design.md versus a style guide sets out what each is for.