Building a Design System with Tailwind CSS v4 and React

Why Design Systems Matter

A well-crafted design system is the backbone of any scalable frontend application. It ensures consistency, speeds up development, and makes your codebase maintainable as it grows.

With Tailwind CSS v4's revolutionary CSS-first configuration, building a token-based design system has never been more intuitive. Gone are the days of wrestling with JavaScript config files — now everything lives in your CSS.

Setting Up Your Token System

The key insight is using CSS custom properties as your single source of truth:

@theme inline {
  --color-primary: oklch(0.45 0.2 264);
  --color-secondary: oklch(0.78 0.14 75);
  --radius-lg: 0.625rem;
}

Building Your First Component

Start with the smallest building blocks and compose upward:

interface ButtonProps {
  variant: "primary" | "secondary" | "ghost"
  size: "sm" | "md" | "lg"
  children: React.ReactNode

export function Button({ variant, size, children }: ButtonProps) { return ( <button className={cn(baseStyles, variants[variant], sizes[size])}> {children} </button> ) } ```

Token Architecture

Structure your tokens in three layers:

1. Primitive tokens — raw color values, spacing units
2. Semantic tokens — purpose-driven aliases like --color-destructive
3. Component tokens — scoped to specific components

This layered approach means you can swap entire themes by changing just the primitive layer.

Dark Mode for Free

With oklch and CSS custom properties, dark mode becomes trivial:

.dark {
  --color-primary: oklch(0.7 0.18 264);
  --color-background: oklch(0.16 0.02 264);
}

No JavaScript toggling of individual colors — just swap the entire token set.