Tailwind CSS v4+ Best Practices

Modern utility-first CSS with Tailwind v4.

What's New in v4

Feature	v3	v4
Config	`tailwind.config.js`	CSS-first (`@theme`)
Colors	JS object	CSS variables
Performance	JIT	Oxide engine (faster)
Import	`@tailwind base`	`@import "tailwindcss"`

Instructions

1. Installation (v4)

npm install tailwindcss@next @tailwindcss/vite

// vite.config.ts
import tailwindcss from '@tailwindcss/vite'

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

2. CSS-First Configuration

/* app.css */
@import "tailwindcss";

@theme {
  /* Colors */
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --color-accent: #f59e0b;
  
  /* Custom colors */
  --color-brand-50: #eff6ff;
  --color-brand-500: #3b82f6;
  --color-brand-900: #1e3a8a;
  
  /* Fonts */
  --font-sans: 'Inter', sans-serif;
  --font-mono: 'Fira Code', monospace;
  
  /* Spacing */
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;
  
  /* Border radius */
  --radius-4xl: 2rem;
  
  /* Shadows */
  --shadow-soft: 0 2px 15px -3px rgba(0, 0, 0, 0.07);
  
  /* Animations */
  --animate-fade-in: fade-in 0.3s ease-out;
}

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

3. Dark Mode

/* CSS-first dark mode */
@import "tailwindcss";

@theme {
  --color-background: #ffffff;
  --color-foreground: #0a0a0a;
}

@theme dark {
  --color-background: #0a0a0a;
  --color-foreground: #fafafa;
}

// Usage in components
<div className="bg-background text-foreground">
  <h1 className="text-foreground">Hello</h1>
</div>

// Toggle dark mode
<html className="dark">

4. Responsive Design (Mobile-First)

<div className="
  p-4          /* mobile: 16px */
  md:p-6       /* tablet: 24px */
  lg:p-8       /* desktop: 32px */
  xl:p-12      /* large: 48px */
">
  <h1 className="
    text-xl      /* mobile */
    md:text-2xl  /* tablet */
    lg:text-4xl  /* desktop */
  ">
    Responsive Title
  </h1>
</div>

5. Container Queries (v4)

<div className="@container">
  <div className="@md:flex @lg:grid @lg:grid-cols-3">
    {/* Responds to container, not viewport */}
  </div>
</div>

6. Component Patterns

// Button variants
const buttonVariants = {
  primary: "bg-primary text-white hover:bg-primary/90",
  secondary: "bg-secondary text-white hover:bg-secondary/90",
  outline: "border border-primary text-primary hover:bg-primary/10",
  ghost: "hover:bg-accent/10 text-foreground",
};

// Card pattern
<div className="
  rounded-xl 
  bg-white dark:bg-gray-900 
  shadow-soft 
  p-6 
  border border-gray-200 dark:border-gray-800
">
  {children}
</div>

// Input pattern
<input className="
  w-full 
  rounded-lg 
  border border-gray-300 dark:border-gray-700
  bg-white dark:bg-gray-900
  px-4 py-2
  text-foreground
  placeholder:text-gray-400
  focus:outline-none focus:ring-2 focus:ring-primary/50
  disabled:opacity-50 disabled:cursor-not-allowed
" />

7. Animation Utilities

// Hover effects
<button className="
  transition-all duration-200
  hover:scale-105 
  hover:shadow-lg
  active:scale-95
">
  Click me
</button>

// Entrance animation
<div className="animate-fade-in">
  Content appears with animation
</div>

// Skeleton loading
<div className="animate-pulse bg-gray-200 rounded h-4 w-full" />

8. Grid Layouts

// Auto-fit grid
<div className="grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))] gap-4">
  {items.map(item => <Card key={item.id} />)}
</div>

// Dashboard layout
<div className="grid grid-cols-12 gap-4">
  <aside className="col-span-12 md:col-span-3">Sidebar</aside>
  <main className="col-span-12 md:col-span-9">Content</main>
</div>

9. Custom Utilities (v4)

@utility glass {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}

@utility text-gradient {
  background: linear-gradient(to right, var(--color-primary), var(--color-accent));
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

<div className="glass rounded-xl p-6">
  <h1 className="text-gradient text-4xl font-bold">Gradient Text</h1>
</div>

10. Performance Tips

// ✅ Good - use cn() for conditional classes
import { cn } from '@/lib/utils';

<button className={cn(
  "px-4 py-2 rounded-lg",
  variant === 'primary' && "bg-primary text-white",
  disabled && "opacity-50 cursor-not-allowed"
)}>

// ❌ Bad - template literals with many conditions
<button className={`px-4 py-2 ${variant === 'primary' ? 'bg-primary' : ''}`}>

cn() Utility

// lib/utils.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

tailwind

Tailwind CSS v4+ Best Practices

What's New in v4

Instructions

1. Installation (v4)

2. CSS-First Configuration

3. Dark Mode

4. Responsive Design (Mobile-First)

5. Container Queries (v4)

6. Component Patterns

7. Animation Utilities

8. Grid Layouts

9. Custom Utilities (v4)

10. Performance Tips

cn() Utility

References