Tailwind CSS v4 & Modern Features

Tailwind CSS v4 & Modern Features

Tailwind CSS v4 represents a major evolution of the framework, introducing a new CSS-first configuration system, improved performance, and support for cutting-edge CSS features. This lesson explores what's new in v4 and how to leverage these modern capabilities.

Major Changes in Tailwind v4

Tailwind v4 brings fundamental architectural changes that improve performance and developer experience.

CSS-First Configuration

The biggest change in v4 is the shift from JavaScript configuration files to CSS-based configuration using CSS variables and the new @theme directive.

// tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#eff6ff',
          100: '#dbeafe',
          500: '#3b82f6',
          900: '#1e3a8a',
        }
      },
      spacing: {
        '128': '32rem',
        '144': '36rem',
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      }
    }
  },
  plugins: [
    require('@tailwindcss/forms'),
  ]
}

/* styles.css (v4) */
@import "tailwindcss";

@theme {
  /* Define custom colors */
  --color-brand-50: #eff6ff;
  --color-brand-100: #dbeafe;
  --color-brand-500: #3b82f6;
  --color-brand-900: #1e3a8a;

  /* Define custom spacing */
  --spacing-128: 32rem;
  --spacing-144: 36rem;

  /* Define font families */
  --font-family-sans: Inter, system-ui, sans-serif;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;

  /* Custom animations */
  --animate-slide-in: slide-in 0.3s ease-out;
}

/* Define custom keyframes */
@keyframes slide-in {
  from {
    transform: translateX(-100%);
    opacity: 0;
  }
  to {
    transform: translateX(0);
    opacity: 1;
  }
}

/* Use the custom values */
.hero {
  background-color: theme(--color-brand-500);
  padding: theme(--spacing-128);
  font-family: theme(--font-family-sans);
}

The @theme Directive

The @theme directive is the heart of v4 configuration. It allows you to define custom design tokens using CSS variable syntax.

@import "tailwindcss";

@theme {
  /* Colors - automatically generate full palettes */
  --color-primary-*: initial; /* Generates primary-50 through primary-950 */
  --color-primary-500: #8b5cf6;

  /* Or define specific shades */
  --color-accent-light: #fbbf24;
  --color-accent-DEFAULT: #f59e0b;
  --color-accent-dark: #d97706;

  /* Spacing scale */
  --spacing-xs: 0.5rem;
  --spacing-sm: 0.75rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;

  /* Typography */
  --font-size-xs: 0.75rem;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;
  --font-size-2xl: 1.5rem;

  --font-family-display: "Playfair Display", serif;
  --font-family-body: "Inter", sans-serif;

  /* Border radius */
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-xl: 0.75rem;
  --radius-full: 9999px;

  /* Shadows */
  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);

  /* Breakpoints */
  --breakpoint-tablet: 768px;
  --breakpoint-desktop: 1024px;
  --breakpoint-wide: 1280px;

  /* Z-index layers */
  --z-dropdown: 1000;
  --z-modal: 2000;
  --z-tooltip: 3000;
}

/* Now use them in utilities */
.btn-primary {
  background-color: theme(--color-primary-500);
  padding: theme(--spacing-md) theme(--spacing-lg);
  border-radius: theme(--radius-md);
  font-family: theme(--font-family-body);
}

New Color System

Tailwind v4 introduces an enhanced color system with better automatic palette generation and improved color manipulation.

@theme {
  /* Define just one shade, get the whole palette */
  --color-brand-*: initial;
  --color-brand-500: #3b82f6;
}

/* This automatically generates: */
/* brand-50, brand-100, brand-200, ..., brand-950 */

<!-- Use the generated palette -->
<div class="bg-brand-50 text-brand-900">
  Light background with dark text
</div>

<button class="bg-brand-500 hover:bg-brand-600">
  Primary button
</button>

<!-- v3 syntax (still works) -->
<div class="bg-blue-500/50">50% opacity</div>

<!-- v4 enhanced syntax with CSS color-mix -->
<div class="bg-blue-500 bg-opacity-50">50% opacity</div>

<!-- Dynamic opacity with CSS variables -->
<div style="--opacity: 0.75" class="bg-blue-500 bg-opacity-[--opacity]">
  Dynamic opacity
</div>

Improved Performance

Tailwind v4 is rebuilt in Rust (via the Lightning CSS engine), resulting in dramatically faster build times.

/* Typical large project build times */

// Tailwind v3
Initial build: 3.2s
Rebuild (HMR): 180ms
Production build: 8.5s

// Tailwind v4
Initial build: 320ms  (10x faster)
Rebuild (HMR): 18ms   (10x faster)
Production build: 850ms  (10x faster)

/* File size comparison */

// v3 development CSS
Uncompressed: 3.8 MB

// v4 development CSS
Uncompressed: 3.2 MB  (16% smaller)

// Both compress to ~30KB in production after PurgeCSS

Container Queries Support

Tailwind v4 has first-class support for CSS Container Queries, allowing responsive design based on parent container size instead of viewport size.

<!-- Define a container -->
<div class="@container">
  <!-- Child elements can query the container size -->
  <div class="
    grid grid-cols-1
    @md:grid-cols-2
    @lg:grid-cols-3
    @xl:grid-cols-4
  ">
    <div class="p-4 bg-white rounded">Card 1</div>
    <div class="p-4 bg-white rounded">Card 2</div>
    <div class="p-4 bg-white rounded">Card 3</div>
  </div>
</div>

<!-- Named containers -->
<div class="@container/sidebar">
  <div class="
    text-sm
    @md/sidebar:text-base
    @lg/sidebar:text-lg
  ">
    Responsive text based on sidebar container
  </div>
</div>

<!-- Container query for card -->
<article class="@container">
  <div class="flex flex-col @md:flex-row gap-4">
    <img
      src="image.jpg"
      alt="Product"
      class="
        w-full @md:w-48
        h-48 object-cover
        rounded
      "
    >
    <div class="flex-1">
      <h3 class="text-lg @md:text-xl font-bold">
        Product Title
      </h3>
      <p class="text-sm @md:text-base text-gray-600">
        Description that adapts to container width
      </p>
    </div>
  </div>
</article>

@starting-style for Entry Animations

CSS @starting-style is now supported in v4, making entry animations easier without JavaScript.

/* Define starting styles for elements when they enter the DOM */
@starting-style {
  .modal {
    opacity: 0;
    transform: scale(0.95);
  }
}

.modal {
  opacity: 1;
  transform: scale(1);
  transition: opacity 0.3s, transform 0.3s;
}

<!-- Modal automatically animates in when added to DOM -->
<div class="modal fixed inset-0 z-50 flex items-center justify-center">
  <div class="bg-white rounded-lg shadow-xl p-6 max-w-md">
    <h2>Modal Content</h2>
    <p>This modal animates in automatically!</p>
  </div>
</div>

Anchor Positioning

Tailwind v4 supports CSS anchor positioning for tooltips, dropdowns, and popovers without JavaScript.

<!-- Define an anchor element -->
<button
  id="menu-button"
  class="px-4 py-2 bg-blue-600 text-white rounded"
  style="anchor-name: --menu-anchor"
>
  Open Menu
</button>

<!-- Position menu relative to anchor -->
<div
  class="
    absolute
    bg-white
    rounded-lg
    shadow-lg
    p-2
  "
  style="
    position-anchor: --menu-anchor;
    inset-area: bottom;
    margin-block-start: 0.5rem;
  "
>
  <a href="#" class="block px-4 py-2 hover:bg-gray-100 rounded">Item 1</a>
  <a href="#" class="block px-4 py-2 hover:bg-gray-100 rounded">Item 2</a>
  <a href="#" class="block px-4 py-2 hover:bg-gray-100 rounded">Item 3</a>
</div>

Migration from v3 to v4

Migrating from Tailwind v3 to v4 requires some adjustments, but the core utility classes remain largely compatible.

/* 1. Update package.json */
{
  "dependencies": {
    "tailwindcss": "^4.0.0"
  }
}

/* 2. Convert tailwind.config.js to CSS */
// Before (v3): tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6'
      }
    }
  }
}

// After (v4): styles.css
@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
}

/* 3. Update import statements */
// Before (v3)
@tailwind base;
@tailwind components;
@tailwind utilities;

// After (v4)
@import "tailwindcss";

/* 4. Update plugins (most are now built-in) */
// Before (v3)
plugins: [
  require('@tailwindcss/forms'),
  require('@tailwindcss/typography'),
]

// After (v4) - Many plugins are now built-in
// No plugins needed for forms, typography, etc.

v4 Compatibility Mode

Tailwind v4 includes a compatibility mode for gradual migration from v3.

// package.json
{
  "dependencies": {
    "tailwindcss": "^4.0.0"
  }
}

// Keep your v3 config file
// tailwind.config.js (works in v4 compatibility mode)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6'
      }
    }
  }
}

// styles.css - use both old and new syntax
@import "tailwindcss";

/* v3-style imports still work */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Mix with v4 @theme */
@theme {
  --color-accent: #f59e0b;
}

Future-Proofing Your Tailwind Code

// tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#eff6ff',
          500: '#3b82f6',
          900: '#1e3a8a',
        }
      },
      spacing: {
        '128': '32rem',
      },
      fontFamily: {
        display: ['Playfair Display', 'serif'],
      }
    }
  }
}

Summary

Tailwind CSS v4 brings significant improvements and modern CSS features:

• CSS-first configuration: Use @theme directive instead of JavaScript config
• 10x faster builds: Rebuilt in Rust for dramatic performance gains
• New color system: Automatic palette generation from single shades
• Container queries: First-class support with @ prefix (@md:, @lg:)
• Modern CSS features: @starting-style, anchor positioning, and more
• Better developer experience: Faster HMR, better errors, smaller bundles
• Migration path: Compatibility mode for gradual transition from v3

In the next lesson, we'll build a complete landing page from scratch, applying all the Tailwind concepts we've learned throughout the course.