You open a DESIGN.md file for the first time. There are six sections. Colors, typography, spacing, radius, shadows, motion. You nod and think: makes sense.
But if someone asked you to explain what each section actually does for the AI, could you? Most people cannot. They paste the file, get better output, and move on without understanding why it worked.
Understanding why matters. Because when you know what each section does, you can write better ones. And better DESIGN.md files produce better code.
Color Tokens
Color tokens are named variables that map semantic roles to specific hex values. Not just "this hex code" but "this is your primary action color, this is your background, this is your danger state."
Colors without names are just colors. The AI does not know that #635BFF is your brand color and should be used on CTAs. It might slap it on a background, a border, or an icon. Semantic names give every color a job.
Without
The AI picks #3B82F6 because it is the most common blue in Tailwind projects. Your primary color is meaningless. Every component uses different shades.
With
The AI uses --color-primary for buttons, --color-surface for cards, --color-danger for error states. The whole interface speaks one color language.
Example
--color-background: #0A0A0A; --color-surface: #111111; --color-border: rgba(255,255,255,0.08); --color-primary: #635BFF; --color-primary-hover: #4F46E5; --color-text: #F5F5F5; --color-muted: #888888; --color-success: #22C55E; --color-danger: #EF4444;
Typography Tokens
Typography tokens define your font family, the size scale, weights, line heights, and letter spacing. All of them together. Not just the font name.
Font choice is the least important part of typography. What matters is the scale: which size do you use for a heading vs a label? What weight makes a button feel clickable? What tracking makes a headline feel tight and intentional?
Without
The AI uses font-size: 16px for everything and bumps headings to 24px. All text has the same weight. Nothing has hierarchy. It looks like a first draft.
With
The AI knows your H1 is 36px / 700 / -0.03em tracking. Your caption is 11px / 500 / 0.06em. Every text element occupies its own rung on the hierarchy.
Example
--font-sans: 'Inter', system-ui, sans-serif; --font-mono: 'JetBrains Mono', ui-monospace, monospace; --text-xs: 0.6875rem; /* 11px */ --text-sm: 0.875rem; /* 14px */ --text-base: 1rem; /* 16px */ --text-lg: 1.125rem; /* 18px */ --text-xl: 1.25rem; /* 20px */ --text-2xl: 1.5rem; /* 24px */ --text-3xl: 1.875rem; /* 30px */ --text-4xl: 2.25rem; /* 36px */ --font-normal: 400; --font-medium: 500; --font-semibold: 600; --font-bold: 700; --tracking-tight: -0.03em; --tracking-normal: -0.01em; --tracking-wide: 0.06em;
Spacing Tokens
A spacing scale is a fixed set of sizes derived from a base unit. Everything in your layout -- padding, margin, gap -- comes from this list. Nothing is made up on the spot.
Arbitrary spacing is the most common reason AI-generated UI looks amateur. Padding: 20px here, margin: 15px there, gap: 12px somewhere else. The eye picks up the inconsistency even if the user cannot name it.
Without
Every component has different padding. The layout has no rhythm. It looks like four developers eyeballed their sections independently.
With
Every gap, padding, and margin is from the same list. The interface breathes. Elements relate to each other spatially in a way that feels considered.
Example
/* Base unit: 4px */ --space-0: 0; --space-1: 0.25rem; /* 4px */ --space-2: 0.5rem; /* 8px */ --space-3: 0.75rem; /* 12px */ --space-4: 1rem; /* 16px */ --space-5: 1.25rem; /* 20px */ --space-6: 1.5rem; /* 24px */ --space-8: 2rem; /* 32px */ --space-10: 2.5rem; /* 40px */ --space-12: 3rem; /* 48px */ --space-16: 4rem; /* 64px */ --space-20: 5rem; /* 80px */
Border Radius Tokens
Border radius tokens define the roundness of your corners. They set the "shape language" of your product: sharp and technical, or soft and approachable.
Border radius is surprisingly identity-defining. Linear uses 6px and feels like a precision instrument. Notion uses 4px and feels document-like. Airbnb uses 16px and feels friendly. Without a defined scale, every component picks its own corner style.
Without
Buttons are 4px. Cards are 8px. Modals are 12px. Nothing matches. The product has three different personalities fighting each other.
With
The AI applies your radius scale consistently. Every element in the UI curves at the same angle. The product has a single shape language.
Example
--radius-sm: 4px; --radius-md: 8px; --radius-lg: 12px; --radius-xl: 16px; --radius-2xl: 24px; --radius-full: 9999px; /* Usage guidance */ /* --radius-sm: inputs, tags, badges */ /* --radius-md: buttons, cards */ /* --radius-lg: modals, panels */ /* --radius-full: pills, avatars */
Shadow Tokens
Shadow tokens define depth levels. Not one shadow for everything, but named levels that correspond to different Z-axis positions in your interface.
Shadows communicate hierarchy. A card sits at one depth. A dropdown floats above it. A modal floats above that. Without defined levels, the AI uses the same shadow everywhere and nothing feels layered.
Without
Every component has box-shadow: 0 2px 4px rgba(0,0,0,0.1). The interface is flat. The modal does not feel above the page. The card does not feel raised from the background.
With
The AI knows --shadow-sm is for cards at rest, --shadow-lg is for modals and dialogs, --shadow-xl is for floating menus. The interface has a real Z-axis.
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);
/* Usage guidance */
/* --shadow-sm: cards at rest */
/* --shadow-md: dropdowns, popovers */
/* --shadow-lg: modals, drawers */
/* --shadow-xl: command palettes */Motion Tokens
Motion tokens define the duration and easing curves for transitions and animations. They are what make interactions feel snappy vs sluggish, considered vs default.
transition: all 0.3s ease is the spacing: 20px of motion. It is the fallback. Every animation at the same speed, the same curve. Real motion systems use different easings for entering vs exiting, different durations for micro-interactions vs page transitions.
Without
Every animation takes the same 300ms with the same ease curve. Tooltips feel as heavy as modals. Nothing feels calibrated.
With
Micro-interactions are 100ms. Panels slide in at 300ms with an ease-out curve. Modals enter at 250ms with a spring. Each interaction type has its own timing signature.
Example
--duration-instant: 50ms; --duration-fast: 100ms; --duration-base: 200ms; --duration-slow: 300ms; --duration-slower: 500ms; --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-inout: cubic-bezier(0.4, 0, 0.2, 1); --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1); /* Usage guidance */ /* --ease-out + --duration-base: elements entering */ /* --ease-in + --duration-fast: elements leaving */ /* --ease-spring: button press, toggle feedback */
The sections work together
Each token section is useful on its own. But the real power is when they reinforce each other. Your spacing scale uses the same base unit as your radius scale. Your motion durations match the complexity of your shadow transitions. The whole file feels like it came from one design brain.
That is what makes a great DESIGN.md different from a list of CSS variables. It is a coherent system, not a collection of parts.
Linear
Dev Tools · All six token sections included
Stripi Inspired
Fintech · All six token sections included
See a complete DESIGN.md
Every design in the catalog includes all six token sections. Browse 110 files and see how different products handle the same structure.
Browse designs