← home setup · markdown

DESIGN.md

A design system in a single markdown file. Tells your AI assistant how every screen, page, and component should look. Stops it from inventing generic AI aesthetics every time it makes something for you.

70 lines · plain text 
---
version: alpha
name: [Your design system name]
description: [One paragraph on the feel. What it looks like, what it doesn't]
colors:
  primary: "[#hex, your main ink colour]"
  secondary: "[#hex, secondary text]"
  neutral: "[#hex, page background]"
  surface: "[#hex, cards and elevated surfaces]"
  surface-muted: "[#hex, soft backgrounds]"
  border-subtle: "[#hex, dividers]"
  accent: "[#hex, the one colour that lands]"
  error: "[#hex, destructive actions]"
typography:
  display: { fontSize: 64px, fontWeight: 600, lineHeight: 1.05, letterSpacing: "-0.02em" }
  h1: { fontSize: 48px, fontWeight: 600, lineHeight: 1.1, letterSpacing: "-0.02em" }
  h2: { fontSize: 32px, fontWeight: 500, lineHeight: 1.2 }
  h3: { fontSize: 22px, fontWeight: 500, lineHeight: 1.3 }
  body-lg: { fontSize: 18px, fontWeight: 400, lineHeight: 1.6 }
  body-md: { fontSize: 16px, fontWeight: 400, lineHeight: 1.6 }
  body-sm: { fontSize: 14px, fontWeight: 400, lineHeight: 1.55 }
  label-md: { fontSize: 14px, fontWeight: 500, lineHeight: 1.2, letterSpacing: "0.02em" }
  caption: { fontSize: 12px, fontWeight: 400, lineHeight: 1.4 }
rounded: { none: 0px, sm: 4px, md: 6px, lg: 10px, full: 9999px }
spacing: { xs: 4px, sm: 8px, md: 16px, lg: 32px, xl: 64px }
---

# Design system

## Overview
[One paragraph. What the inspiration is. What feeling you want a viewer to have. What you DON'T want]

## Colors
Light backgrounds by default. Accent appears in one or two moments per screen, never everywhere.
- Primary: near-black ink for text. Never pure black.
- Neutral: warm or cool off-white as the page background.
- Surface: white cards on the neutral background.
- Accent: the one colour that lands. Should feel luminous, not flat.

## Typography
Family: [your chosen font(s)]. Sentence case for every heading, label, and button.

## Layout
Max width 1200px on desktop, fluid on mobile. 8px spacing scale, 4px half-step. Nothing eyeballed.

## Elevation
Depth from tonal contrast and soft shadow. Never strokes or borders on cards.

## Shapes
Small radii (4-10px). Circles only as structural elements (status dots, focal points), never decoration.

## Do
- Sentence case everywhere.
- Light backgrounds by default.
- Generous whitespace.
- Precision alignment (cap-height, centre-line, scale values).
- Soft shadow and tonal contrast for depth.
- WCAG AA contrast (4.5:1 normal text, 3:1 large).

## Don't
- No em dashes, anywhere, ever.
- No title case, no all caps.
- No borders or strokes on cards.
- No dark backgrounds by default.
- No glassmorphism, neon, gradients, floating blobs, iridescent surfaces.
- No flat corporate blues, muddy earths, or neon accents.
- No two primary buttons on one screen.
- No mixing sharp (0px) corners with rounded in the same view.
- No eyeballed spacing.

Why this works

A design system you can hand to an AI assistant and have it actually obey. The frontmatter is machine-readable so the assistant can pull exact values; the body is the philosophy and rules in plain English.

Why this exists: AI assistants default to a generic aesthetic. Glassmorphism, gradient hero sections, three-column feature grids, neon accents, the same Tailwind buttons everyone has. That’s not design, that’s slop. A DESIGN.md is the brief that stops it.

What’s in it:

  • Frontmatter (YAML): the machine-readable bit. Colours, typography, spacing, components. The assistant pulls exact values from here.
  • Body (markdown): the philosophy. The feel. The do’s and don’ts. The reasoning that lets the assistant make judgement calls in unfamiliar situations.

How to use it:

  1. Save as DESIGN.md in your project root
  2. Fill in the colours, fonts, and spacing you actually use
  3. Write the Overview paragraph in your own voice — what’s the inspiration, what’s the feel
  4. Reference it in your CLAUDE.md (“read DESIGN.md before any UI work”)
  5. Update it whenever a design decision lands

Project-level overrides: This is the global one. Specific projects can have their own DESIGN.md that overrides — usually changing the accent colour or adding a project-specific font.

If you’re not technical, you don’t need the YAML frontmatter. Skip it and just write the body. The assistant will read the rules and follow them.

← back home