Tailwindcss Fundamentals V4

Tailwind CSS v4 Fundamentals (2025/2026)

Overview

Tailwind CSS v4.0 was released January 22, 2025, featuring a complete rewrite with a Rust-based engine, CSS-first configuration, and significant performance improvements.

Key Changes from v3

Installation

Vite Projects (Recommended)

npm install -D tailwindcss @tailwindcss/vite

// vite.config.js
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [tailwindcss()]
})

PostCSS Projects

npm install -D tailwindcss @tailwindcss/postcss

// postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}

CSS Entry Point

/* app.css - The only required CSS file */
@import "tailwindcss";

CSS-First Configuration

The @theme Directive

Replace tailwind.config.js with CSS-based configuration:

@import "tailwindcss";

@theme {
  /* Colors using modern oklch */
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.7 0.15 180);
  --color-accent: oklch(0.8 0.2 30);

  /* Typography */
  --font-display: "Satoshi", sans-serif;
  --font-body: "Inter", sans-serif;

  /* Custom spacing */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 2rem;
  --spacing-xl: 4rem;

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

Theme Variables Reference

Disabling Defaults

@theme {
  /* Start fresh - disable all default theme values */
  --*: initial;

  /* Define only what you need */
  --spacing: 4px;
  --font-body: Inter, sans-serif;
  --color-primary: oklch(0.72 0.11 221.19);
  --color-secondary: oklch(0.74 0.17 40.24);
}

Custom Utilities

Static Utilities

/* Define custom utility in CSS */
@utility content-auto {
  content-visibility: auto;
}

@utility text-balance {
  text-wrap: balance;
}

@utility scrollbar-hide {
  -ms-overflow-style: none;
  scrollbar-width: none;
}

@utility scrollbar-hide::-webkit-scrollbar {
  display: none;
}

Usage:

<div class="content-auto scrollbar-hide">
  <h1 class="text-balance">Long headline that should balance nicely</h1>
</div>

Functional Utilities

/* Utility that accepts values */
@utility tab-* {
  tab-size: --value(integer);
}

@utility text-shadow-* {
  text-shadow: 0 0 --value([length]) currentColor;
}

/* With theme reference */
@utility gap-safe-* {
  gap: max(--value(--spacing-*), env(safe-area-inset-bottom));
}

Usage:

<pre class="tab-4">Code with 4-space tabs</pre>
<h1 class="text-shadow-[2px]">Glowing text</h1>
<div class="gap-safe-4">Safe area aware gap</div>

Custom Variants

The @custom-variant Directive

/* Dark mode with selector */
@custom-variant dark (&:where(.dark, .dark *));

/* Custom state variants */
@custom-variant hocus (&:hover, &:focus);
@custom-variant group-hocus (:merge(.group):hover &, :merge(.group):focus &);

/* Data attribute variants */
@custom-variant data-loading (&[data-loading="true"]);
@custom-variant data-active (&[data-state="active"]);

/* Child selectors */
@custom-variant children (& > *);
@custom-variant not-first (& > *:not(:first-child));

Usage:

<button class="hocus:bg-blue-600">Hover or focus</button>
<div class="data-loading:opacity-50" data-loading="true">Loading...</div>
<ul class="children:border-b not-first:pt-2">
  <li>Item 1</li>
  <li>Item 2</li>
</ul>

Loading Plugins

The @plugin Directive

@import "tailwindcss";

/* Load official plugins */
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
@plugin "@tailwindcss/container-queries";

/* Load local plugin */
@plugin "./my-plugin.js";

Plugin with Options

@plugin "@tailwindcss/typography" {
  className: wysiwyg;
}

@plugin "@tailwindcss/forms" {
  strategy: class;
}

Using Prefixes

@import "tailwindcss" prefix(tw);

@theme {
  /* Define without prefix */
  --font-display: "Satoshi", sans-serif;
}

<!-- Use with prefix -->
<div class="tw:flex tw:bg-red-500 tw:hover:bg-red-600">
  Content
</div>

Generated CSS variables include prefix:

:root {
  --tw-font-display: "Satoshi", sans-serif;
}

CSS Variables in Code

Replace theme() with var()

/* v3 approach (deprecated) */
.old-way {
  background-color: theme(colors.red.500);
}

/* v4 approach */
.new-way {
  background-color: var(--color-red-500);
}

/* In media queries, use CSS variable names */
@media (width >= theme(--breakpoint-xl)) {
  /* styles */
}

Core Utility Categories

Layout

<!-- Flexbox -->
<div class="flex flex-col md:flex-row items-center justify-between gap-4">

<!-- Grid -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">

<!-- Container -->
<div class="container mx-auto px-4">

Spacing

<!-- Padding -->
<div class="p-4 px-6 py-2">

<!-- Margin -->
<div class="m-4 mx-auto my-8">

<!-- Gap -->
<div class="gap-4 gap-x-6 gap-y-2">

Typography

<!-- Font size -->
<p class="text-sm md:text-base lg:text-lg">

<!-- Font weight -->
<h1 class="font-bold">

<!-- Text color -->
<p class="text-gray-600 dark:text-gray-300">

<!-- Line height -->
<p class="leading-relaxed">

Colors

<!-- Background -->
<div class="bg-white dark:bg-gray-900">

<!-- Text -->
<p class="text-blue-600">

<!-- Border -->
<div class="border border-gray-200">

<!-- Ring -->
<button class="focus:ring-2 focus:ring-blue-500">

Sizing

<!-- Width -->
<div class="w-full md:w-1/2 lg:w-1/3">

<!-- Height -->
<div class="h-screen min-h-[500px]">

<!-- Max width -->
<div class="max-w-xl mx-auto">

Arbitrary Values

<!-- Use any CSS value -->
<div class="top-[117px] left-[calc(50%-4rem)]">

<!-- With CSS variables -->
<div class="bg-[var(--my-color)]">

<!-- Complex values -->
<div class="grid-cols-[1fr_500px_2fr]">

Important Modifier

<!-- Force important -->
<div class="!mt-0">

<!-- With variants -->
<div class="hover:!bg-red-500">

Built-in Features (No Config Needed)

Layers

/* Use native CSS layers */
@layer base {
  h1 {
    @apply text-2xl font-bold;
  }
}

@layer components {
  .btn {
    @apply px-4 py-2 rounded font-medium;
  }
}

@layer utilities {
  /* Custom utilities via @utility directive instead */
}

Best Practices (2025/2026)

1. Use OKLCH Colors for Design Systems

OKLCH provides perceptually uniform colors, better gradients, and wide gamut support:

@theme {
  /* OKLCH format: oklch(lightness chroma hue) */
  /* Lightness: 0-1, Chroma: 0-0.4, Hue: 0-360 */

  /* Primary palette - adjust L for shades */
  --color-primary-50: oklch(0.97 0.02 250);
  --color-primary-100: oklch(0.93 0.04 250);
  --color-primary-500: oklch(0.55 0.2 250);  /* Base */
  --color-primary-600: oklch(0.48 0.2 250);
  --color-primary-900: oklch(0.27 0.12 250);

  /* Semantic colors */
  --color-success: oklch(0.6 0.15 145);
  --color-warning: oklch(0.75 0.15 65);
  --color-error: oklch(0.55 0.2 25);
}

2. Implement Fluid Typography

Smooth scaling without breakpoint jumps:

@theme {
  /* Fluid type scale using clamp() */
  /* clamp(min, preferred, max) */
  --text-fluid-xs: clamp(0.75rem, 0.7rem + 0.25vw, 0.875rem);
  --text-fluid-sm: clamp(0.875rem, 0.8rem + 0.375vw, 1rem);
  --text-fluid-base: clamp(1rem, 0.9rem + 0.5vw, 1.125rem);
  --text-fluid-lg: clamp(1.125rem, 1rem + 0.625vw, 1.25rem);
  --text-fluid-xl: clamp(1.25rem, 1rem + 1.25vw, 1.5rem);
  --text-fluid-2xl: clamp(1.5rem, 1.1rem + 2vw, 2rem);
  --text-fluid-3xl: clamp(1.875rem, 1.2rem + 3.375vw, 2.5rem);
  --text-fluid-4xl: clamp(2.25rem, 1rem + 6.25vw, 3.5rem);
}

Important: Always combine vw with rem for accessibility (respects zoom).

3. Fluid Spacing System

@theme {
  /* Fluid spacing that scales with viewport */
  --spacing-fluid-sm: clamp(0.5rem, 0.4rem + 0.5vw, 1rem);
  --spacing-fluid-md: clamp(1rem, 0.75rem + 1.25vw, 2rem);
  --spacing-fluid-lg: clamp(2rem, 1rem + 3vw, 4rem);
  --spacing-fluid-section: clamp(4rem, 2rem + 8vw, 8rem);
}

4. Organize Theme by Category

@theme {
  /* === Colors === */
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.7 0.15 180);
  --color-success: oklch(0.6 0.15 145);
  --color-error: oklch(0.55 0.2 25);

  /* === Typography === */
  --font-sans: 'Inter Variable', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', ui-monospace, monospace;

  /* === Fluid Typography === */
  --text-fluid-base: clamp(1rem, 0.9rem + 0.5vw, 1.25rem);
  --text-fluid-lg: clamp(1.25rem, 1rem + 1.25vw, 2rem);

  /* === Spacing === */
  --spacing-page: 2rem;
  --spacing-fluid-section: clamp(4rem, 2rem + 8vw, 8rem);

  /* === Border Radius === */
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;

  /* === Shadows === */
  --shadow-sm: 0 1px 2px oklch(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px oklch(0 0 0 / 0.07);

  /* === Easing === */
  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
  --ease-snappy: cubic-bezier(0.2, 0, 0, 1);
}

5. Keep @utility Definitions Simple

/* Good - single purpose utilities */
@utility truncate-2 {
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

@utility text-balance {
  text-wrap: balance;
}

@utility content-auto {
  content-visibility: auto;
  contain-intrinsic-size: auto 500px;
}

/* Safe area utilities for notched devices */
@utility safe-area-pb {
  padding-bottom: env(safe-area-inset-bottom);
}

@utility safe-area-pt {
  padding-top: env(safe-area-inset-top);
}

/* Avoid - too complex, use components instead */
@utility card-fancy {
  /* Too many properties - use @layer components */
}

6. Mobile-First Class Ordering

Always structure responsive classes progressively:

<!-- Base (mobile) -> sm -> md -> lg -> xl -> 2xl -->
<div class="
  text-sm md:text-base lg:text-lg
  p-4 md:p-6 lg:p-8
  grid-cols-1 md:grid-cols-2 lg:grid-cols-3
">
  Content
</div>

7. Accessible Interactive Elements

<!-- Touch-friendly button (44px minimum - WCAG 2.2) -->
<button class="
  min-h-11 min-w-11 px-4 py-2.5
  bg-primary-600 hover:bg-primary-700 text-white
  rounded-lg font-medium
  focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:ring-offset-2
  transition-colors motion-reduce:transition-none
">
  Button Text
</button>

Common Migration Issues

Border Color Default

/* v3: border used gray-200 by default */
/* v4: border uses currentColor */

/* Fix: explicitly set color */
@theme {
  --default-border-color: var(--color-gray-200);
}

Ring Default

/* v3: ring was 3px blue-500 */
/* v4: ring is 1px currentColor */

/* Fix: restore v3 behavior */
@theme {
  --default-ring-width: 3px;
  --default-ring-color: var(--color-blue-500);
}

Button Cursor

/* v4: buttons use cursor: default */
/* Fix: add pointer globally if needed */
button {
  cursor: pointer;
}

Advanced @theme Patterns

Semantic Color Tokens

Create a layered token system for maintainable themes:

@theme {
  /* Base palette (raw values) */
  --color-blue-500: oklch(0.55 0.2 250);
  --color-blue-600: oklch(0.48 0.2 250);
  --color-slate-100: oklch(0.95 0.01 260);
  --color-slate-900: oklch(0.15 0.01 260);

  /* Semantic tokens (reference base palette) */
  --color-primary: var(--color-blue-500);
  --color-primary-hover: var(--color-blue-600);
  --color-background: var(--color-slate-100);
  --color-foreground: var(--color-slate-900);

  /* Component tokens (reference semantic tokens) */
  --color-button-primary-bg: var(--color-primary);
  --color-button-primary-bg-hover: var(--color-primary-hover);
  --color-card-bg: var(--color-background);
  --color-card-text: var(--color-foreground);
}

Dynamic Theme Switching

@theme {
  /* Light mode defaults */
  --color-surface: oklch(0.99 0 0);
  --color-on-surface: oklch(0.15 0 0);
  --color-border: oklch(0.9 0 0);
}

@custom-variant dark (&:where(.dark, .dark *));

/* Override in dark mode using CSS variables */
.dark {
  --color-surface: oklch(0.15 0.01 260);
  --color-on-surface: oklch(0.95 0 0);
  --color-border: oklch(0.25 0.01 260);
}

Responsive Theme Values

Use CSS custom properties with media queries for responsive themes:

@theme {
  --spacing-container: 1rem;
  --text-hero: 2rem;
}

@media (min-width: 768px) {
  :root {
    --spacing-container: 2rem;
    --text-hero: 3rem;
  }
}

@media (min-width: 1024px) {
  :root {
    --spacing-container: 4rem;
    --text-hero: 4rem;
  }
}

Composite Tokens

Define complex values as theme tokens:

@theme {
  /* Shadows with consistent opacity */
  --shadow-sm: 0 1px 2px oklch(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px oklch(0 0 0 / 0.07), 0 2px 4px oklch(0 0 0 / 0.05);
  --shadow-lg: 0 10px 15px oklch(0 0 0 / 0.1), 0 4px 6px oklch(0 0 0 / 0.05);
  --shadow-xl: 0 20px 25px oklch(0 0 0 / 0.1), 0 8px 10px oklch(0 0 0 / 0.04);

  /* Elevation shadows that include color */
  --shadow-elevation-1: 0 1px 3px oklch(0.25 0.02 260 / 0.12);
  --shadow-elevation-2: 0 4px 6px oklch(0.25 0.02 260 / 0.15);
  --shadow-elevation-3: 0 10px 20px oklch(0.25 0.02 260 / 0.2);

  /* Gradients */
  --gradient-primary: linear-gradient(135deg, var(--color-primary-400), var(--color-primary-600));
  --gradient-surface: linear-gradient(180deg, var(--color-surface), var(--color-surface-alt));
}

Typography Scale

Define a complete type scale with matching line heights:

@theme {
  /* Modular scale (1.25 ratio) */
  --text-xs: 0.64rem;      /* 10.24px */
  --text-xs--line-height: 1rem;

  --text-sm: 0.8rem;       /* 12.8px */
  --text-sm--line-height: 1.25rem;

  --text-base: 1rem;       /* 16px */
  --text-base--line-height: 1.5rem;

  --text-lg: 1.25rem;      /* 20px */
  --text-lg--line-height: 1.75rem;

  --text-xl: 1.563rem;     /* 25px */
  --text-xl--line-height: 2rem;

  --text-2xl: 1.953rem;    /* 31.25px */
  --text-2xl--line-height: 2.25rem;

  --text-3xl: 2.441rem;    /* 39px */
  --text-3xl--line-height: 2.5rem;

  --text-4xl: 3.052rem;    /* 48.8px */
  --text-4xl--line-height: 1;
}

Namespace Isolation

Use prefixes to avoid conflicts in multi-tenant systems:

@import "tailwindcss" prefix(app);

@theme {
  --color-brand: oklch(0.6 0.2 250);
}

<!-- All utilities prefixed -->
<div class="app:flex app:bg-brand app:p-4">
  Content
</div>

Theme Inheritance Patterns

Create theme variants that extend a base:

/* Base theme */
@theme {
  --color-primary-50: oklch(0.97 0.02 250);
  --color-primary-500: oklch(0.55 0.2 250);
  --color-primary-900: oklch(0.2 0.1 250);
}

/* Brand variant - override in a separate file */
/* brand-theme.css */
@layer theme {
  :root[data-brand="acme"] {
    --color-primary-50: oklch(0.97 0.03 150);
    --color-primary-500: oklch(0.55 0.2 150);
    --color-primary-900: oklch(0.2 0.12 150);
  }

  :root[data-brand="beta"] {
    --color-primary-50: oklch(0.97 0.02 30);
    --color-primary-500: oklch(0.6 0.18 30);
    --color-primary-900: oklch(0.25 0.1 30);
  }
}

Motion & Animation Tokens

@theme {
  /* Durations */
  --duration-instant: 50ms;
  --duration-fast: 150ms;
  --duration-normal: 300ms;
  --duration-slow: 500ms;

  /* Easings */
  --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
  --ease-in: cubic-bezier(0.4, 0, 1, 1);
  --ease-out: cubic-bezier(0, 0, 0.2, 1);
  --ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
  --ease-elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6);

  /* Animations */
  --animate-fade-in: fade-in var(--duration-normal) var(--ease-out);
  --animate-slide-up: slide-up var(--duration-normal) var(--ease-out);
  --animate-scale: scale var(--duration-fast) var(--ease-bounce);
}

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes slide-up {
  from { transform: translateY(10px); opacity: 0; }
  to { transform: translateY(0); opacity: 1; }
}

@keyframes scale {
  from { transform: scale(0.95); }
  to { transform: scale(1); }
}

Custom Utilities Deep Dive

Static Utilities

Basic Definition

@utility scrollbar-hide {
  -ms-overflow-style: none;
  scrollbar-width: none;
}

@utility scrollbar-hide::-webkit-scrollbar {
  display: none;
}

Multi-Property Utilities

@utility skeleton {
  background: linear-gradient(
    90deg,
    var(--color-gray-200) 25%,
    var(--color-gray-300) 50%,
    var(--color-gray-200) 75%
  );
  background-size: 200% 100%;
  animation: skeleton-shimmer 1.5s infinite;
}

@keyframes skeleton-shimmer {
  0% { background-position: 200% 0; }
  100% { background-position: -200% 0; }
}

State-Aware Utilities

@utility glass {
  background: oklch(1 0 0 / 0.1);
  backdrop-filter: blur(12px);
  border: 1px solid oklch(1 0 0 / 0.2);
}

/* Dark mode variant applied automatically */
.dark .glass {
  background: oklch(0 0 0 / 0.2);
  border-color: oklch(1 0 0 / 0.1);
}

Functional Utilities

With Integer Values

@utility tab-* {
  tab-size: --value(integer);
}

@utility columns-* {
  columns: --value(integer);
}

@utility z-* {
  z-index: --value(integer);
}

Usage:

<pre class="tab-4">Code</pre>
<div class="columns-3">Multi-column text</div>
<div class="z-50">High z-index</div>

With Length Values

@utility inset-* {
  inset: --value([length]);
}

@utility blur-* {
  filter: blur(--value([length]));
}

@utility tracking-* {
  letter-spacing: --value([length]);
}

Usage:

<div class="inset-[10px]">Absolute positioning</div>
<div class="blur-[4px]">Blurred element</div>
<span class="tracking-[0.05em]">Tracked text</span>

With Theme References

@utility gap-safe-* {
  gap: max(--value(--spacing-*), env(safe-area-inset-bottom));
}

@utility text-color-* {
  color: --value(--color-*);
}

@utility bg-gradient-* {
  background: linear-gradient(to right, --value(--color-*), transparent);
}

Usage:

<div class="gap-safe-4">Safe-area aware gap</div>
<p class="text-color-primary-500">Themed text</p>
<div class="bg-gradient-blue-500">Gradient fade</div>

With Multiple Value Types

@utility shadow-text-* {
  text-shadow: 0 0 --value([length]) --value(--color-*, currentColor);
}

/* Alternative: Parse specific formats */
@utility clamp-* {
  font-size: clamp(--value([length]), --value([percentage]), --value([length]));
}

Responsive & Variant-Aware Utilities

Custom utilities automatically work with all variants:

<!-- Responsive -->
<div class="scrollbar-hide md:scrollbar-visible">

<!-- State variants -->
<div class="hover:glass focus:glass">

<!-- Dark mode -->
<div class="glass dark:glass-dark">

Complex Utility Patterns

Container Query Utilities

@utility @container-* {
  container-type: --value(size, inline-size, normal);
  container-name: --value(identifier, none);
}

Aspect Ratio Utilities

@utility aspect-* {
  aspect-ratio: --value(ratio);
}

/* Named aspects */
@utility aspect-video {
  aspect-ratio: 16 / 9;
}

@utility aspect-square {
  aspect-ratio: 1 / 1;
}

@utility aspect-portrait {
  aspect-ratio: 3 / 4;
}

Line Clamp Utilities

@utility line-clamp-* {
  display: -webkit-box;
  -webkit-line-clamp: --value(integer);
  -webkit-box-orient: vertical;
  overflow: hidden;
}

@utility line-clamp-none {
  display: block;
  -webkit-line-clamp: unset;
  -webkit-box-orient: unset;
  overflow: visible;
}

Scroll Snap Utilities

@utility snap-x {
  scroll-snap-type: x mandatory;
}

@utility snap-y {
  scroll-snap-type: y mandatory;
}

@utility snap-start {
  scroll-snap-align: start;
}

@utility snap-center {
  scroll-snap-align: center;
}

@utility snap-proximity {
  scroll-snap-type: both proximity;
}

Performance Considerations

Avoid Overly Complex Utilities

/* BAD - Too many properties */
@utility card {
  display: flex;
  flex-direction: column;
  padding: 1rem;
  background: white;
  border-radius: 0.5rem;
  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
}

/* GOOD - Use component or @apply in CSS */
@layer components {
  .card {
    @apply flex flex-col p-4 bg-white rounded-lg shadow-sm;
  }
}

Keep Functional Utilities Focused

/* GOOD - Single purpose */
@utility opacity-* {
  opacity: --value(percentage);
}

/* AVOID - Multiple unrelated properties */
@utility fancy-* {
  opacity: --value(percentage);
  transform: scale(1.1);
  filter: saturate(1.2);
}

Debugging Custom Utilities

Check if utility is generated:

# Search compiled CSS
grep "scrollbar-hide" dist/output.css

# Use browser DevTools
# Elements > Styles > Search for class name

If not working: 1. Verify @utility syntax is correct 2. Check CSS file is imported after @import "tailwindcss" 3. Ensure class name is used in template (content detection)