Build a Minimal Design System

Color, spacing, type, and radius—four groups of variables keep the whole project in check.

Color, spacing, type, and radius. Four groups of variables can hold an entire project together—twenty-odd lines of code that make all your styles converge. It's the single highest-return one-time move you can make.

What you'll run into:

• You want to change the theme color globally, and find a dozen files with the hex baked in
• Corner radii, shadows, and grays vary from page to page
• Every new page the AI builds uses colors that don't match the previous ones

When people say "design system," they picture a hundreds-page spec document—that's what large teams need for coordination. A solo builder needs only one layer: collect the scattered values into a set of named variables. Every component and page references those names from then on, and the styles line up automatically. ds-wiki

The four variable groups

Keep them in one file, using CSS variables or your framework's token mechanism. The technology doesn't matter; what matters is that everywhere after this references the variable name, never a bare value.

Radius and shadow are the easiest to overlook, yet they drive most of the "does this feel like a real product" impression. When one screen shows 4px, 6px, 8px, and 12px radii, nobody can say why it looks off—but it looks unpolished.

How to start. Don't design from a blank file. Tally up the values already living in your current pages: which colors appear, what spacings and radii you've used. Take the most frequent steps as your initial set, then drop anything that strays far from the crowd. That way your existing pages can consume the variables on day one instead of being rewritten. This is a great task to hand the AI: have it scan all your page files and list the colors, spacings, type sizes, and radii with their counts, then you just pick the steps.

When to let it grow

Don't expand it eagerly. A design system's value is constraint; the more you add, the weaker the constraint. Touch it only when one of these signals appears:

• You need dark mode. The color group moves from concrete values to semantic names: not "gray-500" but "text-secondary." Then switching themes is just swapping one mapping.
• A second person joins. Now you need usage notes for components; variables alone aren't enough.
• You pass twenty components. You need a gallery page that shows every component, or you won't remember what exists.
• Otherwise, stop. Your goal is for new pages to require no style decisions, not to build a complete design language.

Semantic naming deserves a word. Once a color goes from "gray-500" to "text-secondary," it stops describing a hex value and starts describing a purpose. From then on, switching themes or adjusting contrast is just changing the mapping, never the components. It's also a signal for when to grow: the moment you find yourself agonizing over what to call a specific color value is usually the moment semantic naming is due.

Note for the AI

Put this in the project's CLAUDE.md, and every interface the AI generates will start by reading the token file:

## Design tokens

All style variables live in src/styles/tokens.css, in four groups:
color, spacing, type, radius and shadow.

Hard requirements:
- No component or page may contain raw color values, spacing
  numbers, font sizes, or radius values. Always reference variables.
- If you need a value that isn't in the tokens, explain the use case
  and a suggested value, then wait for my confirmation before adding
  it to tokens.css. Never hard-code it inline.
- New tokens must match the existing naming style and explain how
  they relate to existing tokens.

Before generating any UI code, read tokens.css.
After generating, check for hard-coded values and report them.

That last line blocks most style drift. The AI habitually drops in a #3b82f6 while writing code; asking it to check costs almost nothing.