Building a Design System with Tailwind CSS 4

Introduction

Tailwind CSS 4 introduces several game-changing features for building design systems. In this tutorial, we’ll explore how to leverage these new capabilities.

What’s New in Tailwind 4

CSS-First Configuration

Gone is the tailwind.config.js file. Now, all configuration happens in CSS using the @theme directive.

@theme {
  --color-primary: oklch(0.52 0.20 255);
  --font-sans: "Inter", sans-serif;
}

The @theme Directive

This new directive allows you to define design tokens directly in your CSS file. Benefits include:

• No JavaScript build step for configuration
• Better IDE support with native CSS
• Easier to share tokens between projects

Building Your Token System

Let’s create a complete design token system for a modern portfolio.

Colors with OKLCH

OKLCH provides perceptually uniform color palettes:

@theme {
  /* Background colors */
  --color-bg-base: oklch(0.99 0.003 80);
  --color-bg-subtle: oklch(0.96 0.004 80);

  /* Text colors */
  --color-fg-default: oklch(0.15 0.010 30);
  --color-fg-muted: oklch(0.45 0.015 30);
}

Typography Scale

Create a fluid type scale that works across all screen sizes:

@theme {
  --text-sm: clamp(0.8125rem, 0.78rem + 0.15vw, 0.875rem);
  --text-base: clamp(0.9375rem, 0.9rem + 0.2vw, 1rem);
  --text-lg: clamp(1.0625rem, 1rem + 0.25vw, 1.125rem);
}

Conclusion

Tailwind CSS 4’s CSS-first approach makes design systems more maintainable and easier to reason about. Start small, iterate often, and document your decisions.