Tailwind CSS Academy · Lesson

Building the Token and Config Layer

Implement your design tokens as CSS variables, wire them into the Tailwind config, and test them across light and dark mode.

Token Layer Overview

The token layer is the bridge between your design decisions and Tailwind's utility generation. It consists of CSS custom properties (design tokens at the CSS level) and the Tailwind config that references those properties. When implemented correctly, swapping a theme requires only changing the CSS variable values — no Tailwind class names change, no component code changes.

Defining Primitive Tokens

Start by defining all raw color, spacing, and typography values in a tokens/primitives.css file using CSS custom properties. These primitives are not used directly by components — they exist only to feed the semantic token layer. Use a structured naming convention like --color-blue-500 for colors and --space-4 for spacing values.

/* tokens/primitives.css */
:root {
  /* Color primitives */
  --color-blue-50: #eff6ff;
  --color-blue-100: #dbeafe;
  --color-blue-500: #3b82f6;
  --color-blue-600: #2563eb;
  --color-blue-700: #1d4ed8;
  --color-blue-900: #1e3a8a;

  --color-gray-50: #f9fafb;
  --color-gray-100: #f3f4f6;
  --color-gray-500: #6b7280;
  --color-gray-900: #111827;

  --color-white: #ffffff;
  --color-black: #000000;

  /* Spacing primitives */
  --space-1: 0.25rem;
  --space-4: 1rem;
  --space-8: 2rem;
}

All lessons in this course

← Back to Tailwind CSS Academy