Give agents reliable design context
Instead of asking an agent to infer a brand from a logo or screenshot, hand it a structured spec it can read before writing UI code.
free design.md
What is a design.md?
A design.md is a portable Markdown spec that explains a brand's visual system to humans and AI agents. It captures the colors, typography, spacing, radii, components, and usage rules needed to recreate a product's UI with consistency.
design.md
Agent-readableBrand foundations
Design tokens
Components
Usage rules
Definition
The short version
A design.md turns a website's observed design system into a structured Markdown artifact. It is not just documentation and it is not only a token dump. It is implementation context for the next agent, engineer, or designer who needs to build something in the same visual language.
Move design systems between tools
Markdown travels through Git, chat, docs, pull requests, and agent workflows without locking the team into one vendor format.
Create a fast source of truth
A design.md is small enough to review, edit, version, and paste, but structured enough to preserve the decisions that matter.
Contents
What belongs in the file
The best design.md files combine deterministic evidence with designer-readable judgment. They name reusable pieces, preserve measurements, and explain when to use each pattern.
Color tokens with roles, hex values, and contrast intent.
Typography scales, weights, line heights, and font families.
Spacing, border radius, elevation, layout rhythm, and density.
Components such as buttons, cards, nav, forms, badges, and hero patterns.
Brand voice, composition rules, accessibility notes, and do/don't guidance.
Example
A design.md is plain text
Because it is Markdown, a design.md can live in a repo, travel in a prompt, sit beside app code, or become the brief for an AI builder. The structure is compact enough for agents, but readable enough for product teams.
Not just a screenshot
Shows what a page looked like, but not why it works or how to rebuild it.
Not just a token json
Great for machines, but usually missing voice, composition, component behavior, and do/don't guidance.
Not just a figma file
Useful for designers, but harder for coding agents to consume as compact implementation context.
Not just a style guide
Helpful for humans, but often too prose-heavy and inconsistent for repeatable agent output.
---
name: Acme Design System
source: https://example.com
---
# Acme Design System
## Colors
- primary: #10b981
- text: #111111
## Typography
- display: Poppins, 48px, 700
- body: Poppins, 16px, 400
## Components
### button-primary
- background: primary
- radius: 5px
- padding: 12px 18px
## Do's and Don'ts
- Do use sharp contrast and direct copy.
- Don't soften corners beyond the brand radius.FAQ
Common design.md questions
Short answers for teams evaluating design.md as a portable design system format for AI-assisted product work.
What is a design.md?
A design.md is a Markdown design-system spec that gives humans and AI agents the practical details needed to recreate a brand's UI: tokens, typography, spacing, components, and usage guidance.
Is a design.md the same as design tokens?
No. Design tokens are part of a design.md, but a design.md also explains component patterns, layout rules, brand voice, examples, and do's and don'ts.
Why use Markdown for design system documentation?
Markdown is portable, versionable, readable in code review, and easy for AI agents to consume as implementation context.
How do you create a design.md?
You can write one manually from an existing design system, or use Free design.md to extract one from a public URL and optionally enrich it with AI.
Related docs
Keep reading
Definition
What Is MDX? Markdown + JSX Explained
A concise answer-first guide to MDX, including syntax, build requirements, use cases, and common tradeoffs.
Developer guide
Free design.md API and CLI: Extract design.md from a URL
Use hosted keyless extraction with JSON, Markdown, or MDX outputs, plus purchased AI runs and Docker/self-hosted environment keys for private AI enrichment.
Comparison
Markdown vs MDX: Differences and When to Use Each
Compare Markdown and MDX side by side, including portability, syntax, tooling, design docs, and interactive documentation.
Free design.md creates a design.md from any public URL.
We load the page in headless Chromium, extract computed CSS and page signals, render a deterministic Markdown file, and optionally enrich it with AI using the screenshot and captured design data.