The design.md specification

A design.md file is a hybrid artifact: YAML frontmatter carries the structured, machine-readable token set; the MDX body carries the human narrative — brand voice, layout principles, and component guidance.

Token model

Tokens follow a W3C DTCG-inspired shape — group.subgroup.name with { value, type }. Colors are authored in oklch and convert to hex/rgb on export. Tokens may alias one another with { value: "{color.brand.primary}" }.

Required vs. optional

A file is valid when it has brand/text/surface colors, a font family + type scale, spacing, and radius. 100% completeness adds shadows, motion, breakpoints, state colors, iconography, imagery, and the body sections (Brand, Components, Accessibility).

Minimal valid file

---
$schema: https://designmd.in/schema/v1.json
id: my-system
name: My System
category: saas
version: 0.1.0
colorMode: [light]
tokens:
  color:
    brand:   { primary: { value: "oklch(0.55 0.20 250)", type: color } }
    text:    { primary: { value: "oklch(0.20 0.02 250)", type: color } }
    surface: { base:    { value: "oklch(1 0 0)",         type: color } }
  typography:
    family: { sans: { value: "Inter, sans-serif", type: fontFamily } }
    scale:  { base: { value: "1rem", type: dimension } }
  spacing: { base: { value: "0.25rem", type: dimension } }
  radius:  { md: { value: "0.5rem", type: dimension } }
---

# My System
## Brand & Voice
Clean and direct.

Export targets

design.md — the canonical file (paste into Claude/Cursor)
tokens.json — W3C DTCG tokens
theme.css — Tailwind v4 @theme
figma.tokens.json — Tokens Studio
ai-prompt.md — an LLM-optimized system prompt