Tutorial: Design tokens with CSS variables

Set up color, spacing, and typography tokens in plain CSS, then use them across components without a heavy design system.

Design tokens are the smallest named decisions in your UI, colors, spacing, fonts. This tutorial sets up a token file you can grow into a full design system.

What you will build

A `tokens.css` file with semantic color and spacing variables
Light-theme defaults with optional dark overrides
Example button and card components consuming tokens only

Prerequisites

Any HTML/CSS project (Next.js, Vite, or static site)
Basic CSS custom properties knowledge

Step-by-step

Create `styles/tokens.css` and define primitive tokens: `--color-jade-500`, `--color-gold-400`, `--space-4`, etc.
Map semantic tokens that components actually use: `--brand-text-primary`, `--brand-surface-panel`, `--brand-form-surface`.
Import tokens first in your global stylesheet before component CSS.
Replace hard-coded hex values in one component (e.g. a card) with semantic variables.
Add `:root[data-theme="dark"]` overrides for a handful of semantic tokens, not every primitive.
Document token names in a short README so designers and developers share vocabulary.

Token file starter

:root {
  --color-jade-500: #3cb371;
  --color-gold-400: #d4af37;
  --space-2: 0.5rem;
  --space-4: 1rem;
  --font-display: "Rajdhani", sans-serif;
  --font-body: "DM Sans", sans-serif;

  --brand-text-primary: #0f1a14;
  --brand-text-highlight: #4a5c52;
  --brand-surface-panel: #ffffff;
  --brand-form-surface: #f7f9f8;
  --brand-bright-jade: var(--color-jade-500);
}

[data-theme="dark"] {
  --brand-text-primary: #eef5f0;
  --brand-surface-panel: #121916;
  --brand-form-surface: #0d1210;
}

Component usage

.card {
  padding: var(--space-4);
  background: var(--brand-surface-panel);
  color: var(--brand-text-primary);
  border: 1px solid color-mix(in srgb, var(--brand-bright-jade) 20%, transparent);
  border-radius: 12px;
}

Verify

Search the repo for `#` hex in component CSS, tokens should cover most cases
Toggle `data-theme` on `<html>` and confirm readable contrast

Next steps

Generate Figma variables from the same names, or sync tokens to Tailwind `@theme` if you adopt utility classes later.