Tailwind CSS development

Documentation

Use search-docs for detailed Tailwind CSS v4 patterns and documentation.

Basic usage

Use Tailwind CSS classes to style HTML. Before introducing new patterns, check and follow the project's existing Tailwind conventions.
Offer to extract repeated patterns into components that match the project's conventions, such as Blade, JSX, or Vue components.
Consider class placement, order, priority, and defaults. Remove redundant classes, add classes to parent or child elements carefully to reduce repetition, and group elements logically.

Tailwind CSS v4 specifics

Always use Tailwind CSS v4 and avoid deprecated utilities.
corePlugins is not supported in Tailwind v4.

CSS-first configuration

In Tailwind v4, you configure Tailwind in CSS with the @theme directive. You don't need a separate tailwind.config.js file:

@theme {
  --color-brand: oklch(0.72 0.11 178);
}

Import syntax

In Tailwind v4, import Tailwind with a regular CSS @import statement instead of the @tailwind directives used in v3:

- @tailwind base;
- @tailwind components;
- @tailwind utilities;
+ @import "tailwindcss";

Replaced utilities

Tailwind v4 removed deprecated utilities. Use the replacements shown below. For opacity, drop the *-opacity-* class and append the value as a modifier on the existing color: bg-blue-500 bg-opacity-50 becomes bg-blue-500/50, text-white text-opacity-75 becomes text-white/75.

Deprecated	Replacement
bg-opacity-*	bg-{color}/*
text-opacity-*	text-{color}/*
border-opacity-*	border-{color}/*
divide-opacity-*	divide-{color}/*
ring-opacity-*	ring-{color}/*
placeholder-opacity-*	placeholder-{color}/*
flex-shrink-*	shrink-*
flex-grow-*	grow-*
overflow-ellipsis	text-ellipsis
decoration-slice	box-decoration-slice
decoration-clone	box-decoration-clone

Spacing

Use gap utilities instead of margins for spacing between siblings:

<div class="flex gap-8">
    <div>Item 1</div>
    <div>Item 2</div>
</div>

Dark mode

If existing pages and components support dark mode, new pages and components must support it the same way, typically using the dark: variant:

<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
    Content adapts to color scheme
</div>

Common pitfalls

Using deprecated v3 utilities, such as bg-opacity-* and flex-shrink-*
Using @tailwind directives instead of @import "tailwindcss"
Using tailwind.config.js instead of the CSS @theme directive
Using margins for spacing between siblings instead of gap utilities
Forgetting to add dark mode variants when the project uses dark mode