All articles
Getting Started5 min read

What Makes a Good DESIGN.md? The 6 Elements That Actually Matter

Most DESIGN.md files are half-finished. They have colors but no typography. Tokens but no context. Here is what separates a DESIGN.md that works from one the AI ignores.

I have seen a lot of DESIGN.md files. The bad ones have a list of hex colors, maybe a font name, and nothing else. People write them in five minutes and wonder why the AI output still looks generic.

The AI is not ignoring your file. It is using everything you gave it. The problem is you gave it almost nothing.

A good DESIGN.md is specific enough that an AI could rebuild your entire design system from it. A bad one leaves the AI filling in blanks with defaults. Here are the six things that separate them.

1. Color tokens with semantic names, not just hex values

Without

The AI sees #635BFF and has no idea what role it plays. It might use it as a background. It might use it as body text. It will guess.

With

The AI sees --color-primary: #635BFF and --color-primary-hover: #4F46E5 and knows exactly when to use each one. It knows primary is for CTAs, not decorative elements.

Example

--color-background: #0A0A0A;
--color-surface: #111111;
--color-primary: #635BFF;
--color-primary-hover: #4F46E5;
--color-text: #F5F5F5;
--color-muted: #888888;

2. Full typography scale with weights AND letter spacing

Without

The AI defaults to font-size: 16px for everything. Or it picks random sizes. The heading ends up the same weight as the body. Nothing has hierarchy.

With

The AI knows your H1 is 36px / 700 weight / -0.03em tracking. Your body is 16px / 400 weight / -0.01em. It applies this consistently across every component it generates.

Example

--font-sans: 'Inter', system-ui, sans-serif;
--text-xs: 0.75rem;   /* 12px */
--text-sm: 0.875rem;  /* 14px */
--text-base: 1rem;    /* 16px */
--text-xl: 1.25rem;   /* 20px */
--text-2xl: 1.5rem;   /* 24px */
--text-3xl: 1.875rem; /* 30px */
--font-medium: 500;
--font-semibold: 600;
--tracking-tight: -0.03em;
--tracking-normal: -0.01em;

3. A spacing scale that specifies the base unit

Without

The AI applies padding: 20px here, margin: 15px there, gap: 12px somewhere else. Nothing is consistent. The layout feels assembled, not designed.

With

The AI knows your base unit is 4px and your scale is 4, 8, 12, 16, 24, 32, 48, 64. Every gap, every padding, every margin snaps to this rhythm. The whole interface breathes consistently.

Example

/* Base unit: 4px */
--space-1: 0.25rem;  /* 4px  */
--space-2: 0.5rem;   /* 8px  */
--space-3: 0.75rem;  /* 12px */
--space-4: 1rem;     /* 16px */
--space-6: 1.5rem;   /* 24px */
--space-8: 2rem;     /* 32px */
--space-12: 3rem;    /* 48px */
--space-16: 4rem;    /* 64px */

4. Semantic shadow levels (card vs elevated vs modal)

Without

Every component gets box-shadow: 0 2px 4px rgba(0,0,0,0.1). The card, the dropdown, the modal, the tooltip all look the same depth. Nothing has visual hierarchy.

With

The AI uses --shadow-sm for cards, --shadow-md for dropdowns, --shadow-lg for modals. The interface has a clear Z-axis. Elements float at different heights, which tells the user what is on top of what.

Example

--shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
--shadow-md: 0 4px 6px rgba(0,0,0,0.07), 0 2px 4px rgba(0,0,0,0.05);
--shadow-lg: 0 10px 15px rgba(0,0,0,0.1), 0 4px 6px rgba(0,0,0,0.05);
--shadow-xl: 0 20px 25px rgba(0,0,0,0.15), 0 10px 10px rgba(0,0,0,0.04);

5. Motion tokens with real easing values

Without

The AI uses transition: all 0.3s ease. Every animation feels the same. A tooltip appearing uses the same easing as a page transition. Nothing feels considered.

With

The AI knows --ease-out is for elements entering the screen, --ease-in is for elements leaving, and --ease-spring is for interactive feedback. Transitions feel like physics, not CSS defaults.

Example

--duration-fast: 100ms;
--duration-base: 200ms;
--duration-slow: 300ms;
--ease-default: cubic-bezier(0.16, 1, 0.3, 1);
--ease-in: cubic-bezier(0.4, 0, 1, 1);
--ease-out: cubic-bezier(0, 0, 0.2, 1);
--ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);

6. Plain-language component guidance

Without

The AI generates a generic button. It might be the right color, but the border radius is wrong, the padding is off, and the hover state looks like an afterthought.

With

The AI reads: 'Buttons use 8px border radius, 12px horizontal padding, 500 font weight, and scale to 98% on press.' It now builds buttons that match your system every time, not just sometimes.

Example

## Components

### Buttons
- border-radius: 8px
- padding: 10px 16px (default), 8px 12px (sm), 12px 20px (lg)
- font-weight: 500
- Active state: scale(0.98)
- Disabled: opacity 0.5, cursor not-allowed

### Cards
- border-radius: 12px
- border: 1px solid var(--color-border)
- padding: 24px
- Use shadow-sm at rest, shadow-md on hover

You do not have to write this from scratch

The catalog has over 110 DESIGN.md files, each built with all six elements above. Pick one that matches your aesthetic and your use case is covered.

Linear

Dev Tools

Stripi Inspired

Fintech

Vercel Inspired

Dev Tools

Browse the catalog

Every file in the catalog has all six elements. Pick one, copy it, and your next AI session starts with a real design system.

Browse designs