Tailwind CSS Mastery: v3 & v4 Complete Guide

#1. Introduction to Tailwind CSS

Tailwind CSS is a utility-first CSS framework that provides low-level, single-purpose classes to build any UI directly in your markup. Unlike traditional frameworks like Bootstrap that provide pre-built components, Tailwind gives you building blocks to create completely custom designs.

Key Features:

• Utility-First: Each class targets a single CSS property (p-4 → padding: 1rem;)
• Composable: Build complex interfaces by combining simple classes
• Highly customizable: Configure colors, spacing, breakpoints, and more
• Optimized for production: Automatically removes unused CSS (purge/JIT)
• Responsive built-in: Mobile-first design with intuitive breakpoint prefixes
• Consistent design system: Predefined scales for colors, sizes, and spacing

Why Use Tailwind?

• Rapid development: Write styles without leaving your HTML
• Quick prototyping: Implement designs without custom CSS
• Simplified maintenance: Avoid growing, hard-to-maintain CSS files
• Easy inspection: See all styles directly in the HTML
• No naming conventions: No more BEM headaches
• Extremely lightweight: Only include the CSS you actually use

Evolution of Tailwind CSS

• v0.1.0 (2017): Initial release
• v1.0 (2019): First stable version with configuration system
• v2.0 (2020): Custom colors, automated purge, dark mode
• v3.0 (2021): JIT compiler by default, extended colors, animations, arbitrary properties
• v4.0 (2024): Zero-config setup, CSS variables, smaller bundles, Rust-powered engine

#2. CSS Methodologies: Utility-First vs BEM, ITCSS, 7-1

Before Tailwind, developers used various methodologies to organize CSS. Understanding these helps appreciate Tailwind’s approach.

#BEM (Block Element Modifier)

BEM is a naming convention that makes CSS more structured and self-documenting.

/_ Block _/
.card { ... }

/_ Element (dependent on block) _/
.card**title { ... }
.card**button { ... }

/_ Modifier (variation) _/
.card--featured { ... }
.card\_\_button--large { ... }

Pros: Clear relationships, avoids conflicts, reusable. Cons: Verbose HTML, rigid structure, still requires writing custom CSS.

#ITCSS (Inverted Triangle CSS)

ITCSS is an architecture for organizing CSS files in layers of increasing specificity:

1. Settings – Variables, config
2. Tools – Mixins, functions
3. Generic – Reset, normalize
4. Elements – Bare HTML elements (h1, p)
5. Objects – Layout patterns (grid, wrappers)
6. Components – UI components (buttons, cards)
7. Utilities – Overrides, helper classes (text-center, hidden)

Pros: Scalable, predictable specificity, easy to maintain. Cons: Requires disciplined file structure, still relies on custom CSS.

#7-1 Pattern (Sass)

A popular Sass architecture with 7 folders and 1 main file:

sass/
abstracts/ # variables, mixins
vendors/ # third-party
base/ # resets, typography
layout/ # header, footer, grid
components/ # buttons, cards
pages/ # page-specific
themes/ # theme variations
main.scss # imports all

Pros: Highly modular, great for large projects. Cons: Overhead, many files, requires compilation.

#Utility-First (Tailwind’s Approach)

Instead of writing custom CSS, you apply pre-existing utility classes directly in HTML:

<div class="p-4 bg-white shadow-lg rounded-lg">
  <h2 class="text-xl font-bold mb-2">Title</h2>
  <p class="text-gray-600">Content</p>
</div>

Benefits of Utility-First:

• Faster development – No context switching between HTML and CSS files.
• No naming collisions – Classes are atomic and reusable.
• Smaller CSS bundles – Only utilities you use are generated.
• Consistent design system – All values come from a predefined scale.
• Responsive and state variants – Built-in sm:, md:, hover:, etc.
• Easy maintenance – Change a utility in one place, updates everywhere.

Tailwind doesn’t replace methodologies like ITCSS; it provides the “Utilities” layer (the top of the triangle) in an extremely comprehensive way. You still need to organize components (with @apply or framework components) for reusability.

#3. Installation and Setup

#Tailwind CSS v3 Setup

#With React + Vite

npm create vite@latest my-react-app -- --template react-ts
cd my-react-app
npm install -D tailwindcss@3 postcss autoprefixer
npx tailwindcss init -p

Configure tailwind.config.js:

/** @type {import('tailwindcss').Config} \*/
export default {
  content: ['./index.html', './src/**/\*.{js,ts,jsx,tsx}'],
  theme: { extend: {} },
  plugins: [],
};

Add to src/index.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

#With Next.js

npx create-next-app@latest my-next-app --typescript --app
cd my-next-app
npm install -D tailwindcss@3 postcss autoprefixer
npx tailwindcss init -p

Configure tailwind.config.js:

/** @type {import('tailwindcss').Config} \*/
module.exports = {
  content: [
    './app/**/_.{js,ts,jsx,tsx,mdx}',
    './pages/\*\*/_.{js,ts,jsx,tsx,mdx}',
    './components/\*_/_.{js,ts,jsx,tsx,mdx}',
  ],
  theme: { extend: {} },
  plugins: [],
};

Add to app/globals.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

#Tailwind CSS v4 Setup

What’s New in v4:

• No PostCSS dependency for most use cases
• Built-in Rust-powered engine
• CSS-based configuration (no tailwind.config.js needed)
• Automatic content detection
• CSS variables for colors (better theming)
• Smaller bundle size

#With React + Vite

npm create vite@latest my-react-app -- --template react-ts
cd my-react-app
npm install tailwindcss @tailwindcss/vite

Update vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';

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

Update src/index.css:

@import 'tailwindcss';

#With Next.js

npx create-next-app@latest my-next-app --typescript --app
cd my-next-app
npm install tailwindcss @tailwindcss/postcss

Create postcss.config.mjs:

/\*_ @type {import('postcss-load-config').Config} _/;
const config = {
  plugins: { '@tailwindcss/postcss': {} },
};
export default config;

Update app/globals.css:

@import 'tailwindcss';

#4. Core Concepts

#Utility-First Architecture

Each Tailwind class maps directly to a CSS property. Instead of inventing class names like .card-header, you compose utilities.

<div class="p-4 text-center bg-blue-500 text-white rounded-lg">Centered blue box</div>

#Build Pipeline

src/styles.css (with @tailwind directives or @import)
↓
Tailwind engine (scans files, extracts used classes)
↓
Generates optimized CSS with only those classes
↓
public/styles.css (tiny bundle)

#5. Utility Classes Deep Dive

Tailwind provides hundreds of utilities, organized into categories. Here’s a comprehensive overview of each category with examples.

#5.1 Layout

#5.2 Flexbox & Grid

#5.3 Spacing

Tailwind uses a default spacing scale (0.25rem increments) but can be customized.

#5.4 Sizing

#5.5 Typography

#5.6 Backgrounds

#5.7 Borders

#5.8 Effects

#5.9 Filters

#5.10 Transitions & Animation

#5.11 Transforms

#5.12 Interactivity

#5.13 SVG

#5.14 Accessibility

#5.15 Pseudo-Class Variants

Tailwind prefixes any utility with a variant to apply styles on specific states:

• hover: – on mouse hover
• focus: – when element has focus
• active: – when element is active
• disabled: – for disabled elements
• group-hover: – when parent has group class is hovered
• peer: – sibling state handling
• dark: – when dark mode is active
• motion-reduce: – respects reduced motion preferences

#5.16 Arbitrary Values

When the predefined scale doesn’t fit, use square brackets:

<div class="w-[317px] top-[calc(100%-4rem)] bg-[#1da1f1]">Custom sizes and colors</div>

#6. Responsive Design

Tailwind uses a mobile-first breakpoint system. Styles without a prefix apply to all screen sizes; prefixed classes override at larger breakpoints.

#Breakpoints (default)

#Responsive Patterns

<div class="text-sm sm:text-base md:text-lg lg:text-xl">Text grows with screen size.</div>

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <!-- columns adjust -->
</div>

#7. Customization and Configuration

#Tailwind v3 Configuration

tailwind.config.js is where you define your design system.

module.exports = {
  content: ['./src/**/*.{html,js}'],
  theme: {
    extend: {
      colors: {
        brand: {
          light: '#5c67f2',
          DEFAULT: '#4f46e5',
          dark: '#3b5b9d',
        },
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
      spacing: {
        72: '18rem',
        84: '21rem',
      },
    },
  },
  plugins: [],
};

#Tailwind v4 Configuration (Deep Dive)

v4 moves configuration into CSS using the @theme directive. This enables theming with CSS custom properties (variables), making dynamic theming much easier.

#Basic v4 Theme

@import "tailwindcss";

@theme {
/_ Colors as CSS variables _/
--color-primary: #3b82f6;
--color-secondary: #6b7280;
--color-background: #ffffff;
--color-foreground: #0f172a;

/_ Fonts _/
--font-family-sans: Inter, system-ui, sans-serif;
--font-family-serif: Georgia, serif;

/_ Spacing scale (override default) _/
--spacing: 0.25rem; /_ base unit _/
--spacing-72: 18rem; /_ custom named spacing _/

/_ Breakpoints _/
--breakpoint-sm: 640px;
--breakpoint-md: 768px;
--breakpoint-lg: 1024px;
--breakpoint-xl: 1280px;
--breakpoint-2xl: 1536px;

/_ Animation keyframes _/
--keyframes-spin: spin 1s linear infinite;
--keyframes-pulse: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
}

#Why CSS Variables?

• Runtime theming: Change theme dynamically without rebuild.
• Component scoping: Override variables in a container for a sub-theme.
• Better dark mode: Define dark values as variable overrides.

#v4 Configuration Options

v4 provides many CSS variables you can set:

#Using Plugins in v4

Plugins are added with @plugin:

@import 'tailwindcss';
@plugin "@tailwindcss/forms";
@plugin "@tailwindcss/typography";

#Custom Variants

Define custom variants with @custom-variant:

@custom-variant print (@media print);
@custom-variant portrait (@media (orientation: portrait));

/_ Usage: _/
/_ <div class="print:hidden">Hide when printing</div> _/

#What Changed from v3 to v4

Benefits of v4 changes:

• Zero configuration for most projects – just @import "tailwindcss" and go.
• Faster builds – Rust engine is 10x faster than PostCSS.
• True CSS theming – Variables enable dynamic themes at runtime.
• Smaller bundles – More aggressive optimizations.

#8. Component Creation

Even with utility-first, you’ll often extract reusable components.

#Using @apply

@layer components {
  .btn-primary {
    @apply px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-700 focus:ring-2 focus:ring-blue-300;
  }
}

<button class="btn-primary">Click me</button>

#Framework Components (React)

export const Button = ({ variant = 'primary', children }) => {
  const variants = {
    primary: 'bg-blue-500 hover:bg-blue-700 text-white',
    secondary: 'bg-gray-500 hover:bg-gray-700 text-white',
  };
  return <button className={`px-4 py-2 rounded ${variants[variant]}`}>{children}</button>;
};

#9. Dark Mode Implementation

#Dark Mode in v3

Enable darkMode: 'class' in config, then toggle .dark class on html:

// tailwind.config.js
module.exports = {
  darkMode: 'class',
  // ...
};

<div class="bg-white dark:bg-gray-800 text-black dark:text-white">Theme aware content</div>

#Dark Mode in v4

Use @custom-variant and CSS variables:

@import 'tailwindcss';

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

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

.dark {
  --color-background: #0f172a;
  --color-foreground: #ffffff;
}

/_ Usage _/ body {
  background-color: var(--color-background);
  color: var(--color-foreground);
}

#10. Best Practices

• Use Prettier plugin (prettier-plugin-tailwindcss) to sort classes consistently.
• Group related utilities with comments if needed.
• Extract components with your framework (React, Vue) rather than @apply too much.
• Leverage group and peer for parent/child interactions without JS.
• Use @layer to organize custom CSS.
• Always run Purge/JIT (automatic in v3/v4) for small bundles.
• Customize sparingly – stay within default scale when possible.
• Use semantic colors (e.g., --color-primary) for easy theme switching.

#11. Migration from v3 to v4

1. Run the upgrade tool:

   npx @tailwindcss/upgrade@next

2. Update CSS entry file:

   /_ Replace _/
   @tailwind base;
   @tailwind components;
   @tailwind utilities;
   
   /_ With _/
   @import "tailwindcss";

3. Move configuration to CSS:

   • Copy theme extensions from tailwind.config.js to @theme in CSS.
   • Convert color values to CSS variables.

4. Update build setup:

   • For Vite: remove PostCSS config, add @tailwindcss/vite plugin.
   • For Next.js: keep PostCSS but use @tailwindcss/postcss package.

5. Remove autoprefixer – v4 includes it automatically.

6. Update plugins syntax: replace require() in config with @plugin in CSS.

#12. Advanced Topics

#Custom Animations

@keyframes gradient {
  0%,
  100% {
    background-position: 0% 50%;
  }
  50% {
    background-position: 100% 50%;
  }
}

@theme {
  --animate-gradient: gradient 3s ease infinite;
}

<div class="animate-gradient bg-gradient-to-r from-blue-400 to-purple-500"></div>

#Container Queries (via Plugin)

npm install @tailwindcss/container-queries

@plugin "@tailwindcss/container-queries";

@container (min-width: 400px) {
/_ styles _/
}

#Using with CSS Modules

/_ Component.module.css _/ .title {
  @apply text-xl font-bold mb-4;
}

#IDE Integration

• VS Code: Install “Tailwind CSS IntelliSense” for autocomplete.
• WebStorm: Built-in support.

#13. Integration with Frameworks

#React + Tailwind

export function Navbar() {
  return (
    <nav className="flex items-center justify-between p-4 bg-white shadow">
      <Logo className="w-8 h-8" />
      <ul className="flex space-x-6">
        <li>
          <a href="/" className="text-gray-700 hover:text-blue-600">
            Home
          </a>
        </li>
        <li>
          <a href="/about" className="text-gray-700 hover:text-blue-600">
            About
          </a>
        </li>
      </ul>
    </nav>
  );
}

#Next.js with App Router

// app/layout.tsx
import './globals.css';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body className="min-h-screen bg-gray-50">{children}</body>
    </html>
  );
}

#Vue + Tailwind

<template>
  <div class="max-w-md mx-auto p-6 bg-white rounded-lg shadow">
    <h2 class="text-xl font-bold mb-4">{{ title }}</h2>
    <slot></slot>
  </div>
</template>

#Summary: v3 vs v4 Quick Comparison

In short:

• v3 = Power Boost (JIT, animations, arbitrary properties)
• v4 = Power + Simplicity + Scalability (zero config, CSS variables, faster)

This guide covers the essential aspects of Tailwind CSS from beginner to advanced, with both v3 and v4 approaches. Practice by building small projects, and refer to the official documentation for deeper dives. Happy styling!