Why Every Project Needs a DESIGN.md File: A Markdown Design System Guide

Google Stitch introduced DESIGN.md, a plain‑text design system document placed in a project root that AI assistants such as Claude, Cursor and Copilot can read directly.

What is DESIGN.md?

DESIGN.md is a new concept from Google Stitch: a pure‑text design system file that AI assistants can parse to generate consistent UI.

The file contains color palette, typography rules, spacing scale, button styles, grid system and other basic design specifications, eliminating the need for Figma exports or JSON config files.

DESIGN.md follows the Stitch format and consists of nine core sections:

Visual theme and mood – emotion, density, design philosophy

Color palette and roles – semantic names, hex values, functional roles

Typography rules – font families, full hierarchy table

Component styles – buttons, cards, inputs, navigation and their states

Layout principles – spacing scale, grid, whitespace philosophy

Depth and hierarchy – shadow system, surface hierarchy

Do’s and don’ts – design guardrails and anti‑patterns

Responsive behavior – breakpoints, touch targets, collapse strategy

AI‑assistant prompt guide – quick color reference, ready‑to‑use prompts

Markdown is the format large language models read best, so AI assistants can understand exactly how the UI should look.

---
name: DevFocus Dark
colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
rounded:
  md: 8px
---
# Design System

## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography
- **Headlines**: Inter, semi‑bold
- **Body**: Inter, regular, 14–16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface‑variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain a 4:1 contrast ratio for all text

Ready‑made design system libraries

The Awesome DESIGN.md repository already contains 54 design systems extracted from real products such as Stripe, Vercel, Linear, Notion, Claude, Cursor and Warp. Each system includes a DESIGN.md file and two preview files (light and dark themes) for quick visual inspection.

Fast generation tool

HyperDesign can automatically generate a DESIGN.md file. Feeding it the Anthropic website produces colors, fonts and spacing specifications in 16 seconds and a fully structured DESIGN.md in 9 seconds.

The tool does more than pick colors; it analyses the design language, identifies the overall style (e.g., restrained, academic, print‑inspired) and lists line‑height and weight for each font size.

HyperDesign is open‑source; tasks that previously cost millions for large companies can now be replicated in about 25 seconds.

Real‑world usage

One developer reported placing DESIGN.md in the root of a Cursor project caused Claude to immediately respect the brand tokens, eliminating the AI’s tendency to invent Tailwind‑style classes.

Another user said the approach is crucial for small teams and solo projects because design consistency no longer requires a full‑time designer or an unreadable brand guide; a few‑kilobyte Markdown file in the repo informs every AI tool that touches the code.

DESIGN.md files typically range from a few KB to 20 KB and can be fed directly to large models, offering the advantage of treating design as native text rather than forcing AI to interpret exported Figma files.

Awesome DESIGN.md: https://github.com/VoltAgent/awesome-design-md

hyperbrowser: https://github.com/hyperbrowserai/hyperbrowser-app-examples