Basics

What Tailwind Is

Tailwind CSS is a utility-first CSS framework. Instead of writing custom CSS, you compose styles directly in your HTML using small, single-purpose utility classes.

<!-- Traditional approach -->
<button class="btn-primary">Save</button>

<!-- Tailwind approach -->
<button class="bg-blue-600 text-white font-semibold px-4 py-2 rounded-lg hover:bg-blue-700">
  Save
</button>

Tailwind v4 (released 2025) ships as a CSS-first config. The tailwind.config.js file is optional — configuration moves into your CSS file via @theme.

Installation

Via npm (recommended)

npm install tailwindcss @tailwindcss/vite

Then add Tailwind to your CSS entry point — no config file needed for v4, it works out of the box:

@import "tailwindcss";

Play CDN (prototyping only)

<script src="https://cdn.tailwindcss.com"></script>

Do not use the CDN in production. It ships the entire framework un-purged.

Vite plugin (v4)

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

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

Class Naming Convention

Tailwind classes follow a consistent pattern: property-value or property-scale-step.

Utility Categories at a Glance

Arbitrary Values

When the design system doesn't have what you need, use bracket notation:

<!-- Arbitrary size -->
<div class="w-[347px] h-[200px]"></div>

<!-- Arbitrary color -->
<p class="text-[#ff6b35] bg-[#1a1a2e]"></p>

<!-- Arbitrary CSS property (v3.3+) -->
<div class="[mask-type:luminance]"></div>

<!-- Arbitrary with CSS variable -->
<div class="bg-[var(--brand-color)]"></div>

<!-- Arbitrary with calc() -->
<div class="w-[calc(100%-4rem)]"></div>

Important Modifier

In v4, append ! to a utility to force !important:

<p class="text-red-500! font-bold!">Forced styles</p>

In v3 the marker was a leading ! instead (!text-red-500) — that form does not work in v4.

The @apply Directive

Extract repeated utility patterns into reusable CSS classes:

/* In your CSS file */
@layer components {
  .btn {
    @apply inline-flex items-center px-4 py-2 rounded-md font-medium;
  }
  .btn-primary {
    @apply btn bg-blue-600 text-white hover:bg-blue-700;
  }
}

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

Prefer component abstractions (React/Vue components) over @apply when possible — it defeats the purpose of utility-first composition.

Layers

Tailwind uses three CSS layers in order of specificity:

@layer base {
  /* Raw element defaults — h1, a, body resets */
  h1 { @apply text-2xl font-bold; }
}

@layer components {
  /* Reusable component classes */
  .card { @apply rounded-xl border bg-white p-6 shadow; }
}

@layer utilities {
  /* One-off utilities not in Tailwind */
  .content-auto { content-visibility: auto; }
}

Layers ensure the cascade works predictably — utilities always win over components, components over base.

Preflight (CSS Reset)

Tailwind injects Preflight by default: an opinionated reset based on modern-normalize.

Key effects: - All margins/padding removed from headings, p, ul, ol, etc. - box-sizing: border-box on everything - Headings unstyled (no bold, no size) - Lists unstyled (no bullets/numbers) - Images are display: block

To disable in v4, import the framework's pieces individually and leave out preflight.css:

@layer theme, base, components, utilities;

@import "tailwindcss/theme.css" layer(theme);
/* @import "tailwindcss/preflight.css" layer(base); — omitted */
@import "tailwindcss/utilities.css" layer(utilities);

Hover, Focus, and Other State Variants

Prefix any utility with a state to apply it conditionally:

<button class="bg-blue-600 hover:bg-blue-700 focus:ring-2 active:scale-95">
  Button
</button>

Full variant reference is in the States and Variants page.

Responsive Prefixes

All utilities can be scoped to breakpoints with prefixes:

<div class="text-sm md:text-base lg:text-lg xl:text-xl">
  Scales with viewport
</div>

Full breakpoint reference is in the Responsive Design page.

IntelliSense

Install the Tailwind CSS IntelliSense VS Code extension for autocomplete, hover previews, and linting. It reads your config/theme automatically.

Common Gotchas

• Dynamic class names are purged. Never build class names with string concatenation ("text-" + color). Use full class names in source or safelist them.
• v4 no longer needs content paths in config — it detects files automatically via CSS source detection.
• Specificity: a utility class beats a tag selector but loses to an ID. Append ! (v4) or restructure if you have conflicts.
• Dark mode classes require the correct strategy set up — see the Dark Mode page.
• container is not centered by default. Add mx-auto alongside it, or in v4 extend it in CSS: @utility container { margin-inline: auto; } (the v3 center: true theme option is gone).