About DesignMD
The home for design systems your AI can read
DesignMD is the open format, directory, and engine for design.md — a single, portable file that describes a complete design language for humans and AI coding tools alike.
Why it exists
Great design shouldn't be locked away
AI coding tools build most UI today — and by default that UI is generically “good” but undifferentiated. Teams and indie builders spend hours nudging bootstrap-flavored output toward a real aesthetic.
Meanwhile, design systems live in proprietary tools. Figma libraries, Storybook, and internal token files aren't portable, aren't greppable, and aren't promptable. There has been no canonical, shareable format for “make it look like this” that both a person and a model can act on deterministically.
design.md is that format — and DesignMD is the place you get one, and the place you publish one.
The format
What is design.md?
A design.md is a hybrid Markdown/MDX document with two parts working together:
- YAML frontmatter holds the structured, machine-readable token set — color, typography, spacing, radius, shadow, and motion — following a W3C DTCG-inspired shape, with colors authored in
oklch. - The Markdown body holds the human narrative — brand voice, layout principles, component guidance, and explicit do's and don'ts.
The result is deterministic enough for a machine to apply exactly, and rich enough for a person to understand at a glance. Tokens can reference each other with aliases, so systems layer cleanly from primitive → semantic → component.
---$schema: https://designmd.in/schema/v1.jsonid: auroraname: Auroracategory: saascolorMode: [light, dark]tokens: color: brand: primary: { value: "oklch(0.55 0.18 265)", type: color } surface: base: { value: "oklch(0.99 0 0)", type: color } text: primary: { value: "oklch(0.22 0.03 265)", type: color } typography: family: { sans: { value: "Inter, sans-serif", type: fontFamily } } scale: { base: { value: "1rem", type: dimension } } radius: md: { value: "0.625rem", type: dimension }---# Aurora## Brand & VoiceCalm, precise, trustworthy. Copy is direct and jargon-light.## ComponentsPrimary buttons use color.brand.primary, radius.md, and weight.medium.The use case
How AI uses a design.md
The strategic wedge is simple: AI agents produce generic UI by default. A design.md dropped into a repo — or pasted into a prompt — gives them a consistent, opinionated design language to follow.
- 1
Grab or author a design.md
Pick a system from the directory, fork one to tweak it, or generate your own. You get a single portable file that fully describes the design language.
- 2
Drop the rules file into your tool
Export a tool-native file — CLAUDE.md, .cursor/rules, .windsurfrules, or copilot-instructions.md — and save it at the path your AI tool reads automatically.
- 3
The agent reads the tokens and rules
Because the values are structured (real oklch colors, a type scale, radii, motion) and the prose is explicit (brand voice, component rules, do's and don'ts), the model has unambiguous instructions — not vibes.
- 4
It generates on-brand UI — every time
Instead of generic bootstrap-flavored output, your AI produces components that already match the system: the right colors, spacing, radius, and tone, consistently across every screen.
Works with Claude Code, Cursor, Windsurf, GitHub Copilot, and v0 — each gets a file at exactly the path it reads.
How it works
Three pillars, one format
The Directory
A curated, searchable catalog of design.md systems across categories — fintech, editorial, brutalist, SaaS, and more. Browse, preview live, and grab one in seconds.
Browse the directory →The Generator
A guided builder that takes you from a blank canvas to a complete, accessible design.md — pick a brand hue and it derives an AA-safe palette, type scale, and spacing for you.
Create a system →The Engine
The core library that parses, validates, scores, previews, and exports any design.md — into Markdown, W3C tokens, a Tailwind theme, Figma tokens, or an AI prompt, with zero loss.
Read the spec →Who it's for
Use cases
AI builders & vibe-coders
The problem: Your AI output looks generic and off-brand.
With design.md: Drop a design.md rules file in and every generation follows one consistent design language.
Founders & PMs
The problem: You want a credible, consistent look without hiring a designer.
With design.md: Start from a polished system or generate one, then ship UI that looks intentional from day one.
Designers
The problem: You want to document and distribute a system portably.
With design.md: Publish a design.md that humans read and machines consume — no proprietary tool lock-in.
Agencies & teams
The problem: You spin up many projects and re-derive the same tokens each time.
With design.md: Keep reusable starting points and export per-brand tokens in one click.
One file, every format
Export anywhere, with zero loss
The engine round-trips a single design.md into every format your stack and your tools already speak — so a system applies to real codebases, not just a webpage.
The canonical file — drop into a repo or paste into any AI tool.
A Tailwind v4 @theme block, ready to import.
W3C DTCG design tokens for any build pipeline.
Tokens Studio format, for designers.
An instruction-shaped system prompt for coding agents.
Why it matters
The importance of design.md
As AI becomes the default way UI gets built, the bottleneck shifts from writing components to directing them. The teams that ship distinctive, consistent products will be the ones whose tools understand their design language — not the ones re-explaining it in every prompt.
A design.md captures that language once, in a form that travels: into your repo, your AI tools, your build pipeline, and your design files. It's greppable, diff-able, version-controlled, and license-clear. It turns “make it look like us” from a vibe into a specification.
Own the format, and you own a durable advantage: every screen starts on-brand.
FAQ
Frequently asked questions
What is a design.md file?
A design.md is a single portable file that fully describes a design language. Its YAML frontmatter holds the structured token set — color, typography, spacing, radius, shadow, and motion — while its Markdown body holds the human narrative: brand voice, layout principles, component guidance, and do's and don'ts. It is readable by people and consumable by AI coding tools.
How do AI tools use design.md?
Coding agents like Claude, Cursor, Windsurf, GitHub Copilot, and v0 read the structured tokens and explicit rules and apply them to everything they generate. DesignMD exports a tool-native rules file (CLAUDE.md, .cursor/rules, .windsurfrules, copilot-instructions.md) that you save in your repo; from then on, your AI produces on-brand UI automatically.
Why not just use a Tailwind config or a Figma library?
Tailwind configs and Figma libraries aren't portable, greppable, or promptable. design.md is one file that's human-readable, machine-readable, version-controllable, and exports to all of those formats — including a Tailwind theme and an AI prompt — without lock-in.
Is DesignMD free and open?
Yes. Browsing, forking, and exporting are free, no account is needed, and entries carry an explicit open license (CC-BY-4.0 by default).
Why are colors written in oklch?
oklch is a perceptually uniform color space that maps directly onto modern CSS and Tailwind v4. It makes palettes predictable to derive and adjust, and the engine converts to hex, rgb, or hsl on export.
Can I customize a system before using it?
Yes — fork any entry into the live editor, adjust the tokens, and re-export. The preview and every export format update instantly.
Give your AI a design language
Browse a system, grab the file for your tool, and ship UI that looks like you meant it.