Tailwind CSS v4.x Best Practices

Covers Tailwind CSS v4.0 through v4.2.2 (latest stable as of March 2026). Always check the official docs at https://tailwindcss.com/docs for the latest.

Tailwind CSS is a utility-first CSS framework. Instead of writing custom CSS, you compose designs using utility classes directly in your markup. Tailwind v4 introduced CSS-first configuration with

@theme

variables,

@utility

for custom utilities, and

@custom-variant

for custom variants — replacing the old

tailwind.config.js

approach entirely.

Critical v4 Migration Gotchas

These are the most common mistakes when working with Tailwind v4. If you're migrating from v3 or using v4 for the first time, read the upgrade guide — but here are the top trip-ups:

v3 (old)	v4 (correct)	Why it changed
`!bg-red-500`	`bg-red-500!`	Important modifier moved from prefix to suffix
`bg-opacity-75`	`bg-red-500/75`	Opacity modifiers removed; use slash syntax on the color
`shadow`	`shadow-sm`	Shadow scale shifted down one step
`shadow-sm`	`shadow-xs`	Shadow scale shifted down one step
`rounded`	`rounded-sm`	Border radius scale shifted down one step
`rounded-sm`	`rounded-xs`	Border radius scale shifted down one step
`ring`	`ring-3`	Default ring width changed from 3px to 1px
`outline-none`	`outline-hidden`	Renamed for clarity
`flex-shrink-0`	`shrink-0`	Shorter alias is now the only form
`flex-grow`	`grow`	Shorter alias is now the only form
`overflow-ellipsis`	`text-ellipsis`	Renamed for consistency
`blur`	`blur-sm`	Blur scale shifted down one step
`@tailwind base/components/utilities`	`@import "tailwindcss"`	Single CSS import replaces three directives
`tailwind.config.js`	`@theme { }` in CSS	CSS-first configuration replaces JS config
`darkMode: 'class'`	`@custom-variant dark (&:where(.dark, .dark *));`	Dark mode config moves to CSS
`bg-[--var]`	`bg-(--var)`	CSS variable arbitrary values use parentheses
`theme(screens.xl)`	`theme(--breakpoint-xl)`	Theme function uses CSS variable names
`@layer utilities { }`	`@utility name { }`	Custom utilities use dedicated directive
`start-` / `end-`	`inset-s-` / `inset-e-`	Deprecated in v4.2

Core References

Topic	Description	Reference
Installation	Vite, PostCSS, Webpack, CLI, and CDN setup	core-installation
Utility Classes	Understanding Tailwind's utility-first approach	core-utility-classes
Theme Variables	Design tokens, `@theme` directive, theme variable namespaces	core-theme
Responsive Design	Mobile-first breakpoints, responsive variants, container queries	core-responsive
Variants	Conditional styling with state, pseudo-class, media query, and pointer variants	core-variants
Preflight	Tailwind's base styles and how to extend or disable them	core-preflight
Source Detection	How Tailwind detects classes, `@source` , `@source not` , `@source inline()`	core-source-detection

Layout

Display & Flexbox & Grid

Topic	Description	Reference
Display	flex, grid, block, inline, hidden, sr-only, flow-root, contents	layout-display
Flexbox	flex-direction, justify, items, gap, grow, shrink, wrap, order	layout-flexbox
Grid	grid-cols, grid-rows, gap, place-items, col-span, row-span, subgrid	layout-grid
Aspect Ratio	Controlling element aspect ratio for responsive media	layout-aspect-ratio
Columns	Multi-column layout for magazine-style or masonry layouts	layout-columns

Positioning

Topic	Description	Reference
Position	Controlling element positioning with static, relative, absolute, fixed, and sticky	layout-position
Inset	Placement of positioned elements with inset, logical inset ( `inset-s-` , `inset-bs-` ), and deprecated `start-` / `end-`	layout-inset

Sizing

Topic	Description	Reference
Width	Setting element width with spacing scale, fractions, container sizes, viewport units	layout-width
Height	Setting element height with spacing scale, fractions, viewport units	layout-height
Min & Max Sizing	min-width, max-width, min-height, max-height constraints	layout-min-max-sizing
Logical Sizing	Writing-mode-aware sizing: `inline-` , `block-` , `min-inline-` , `max-block-` (v4.2)	layout-logical-properties

Spacing

Topic	Description	Reference
Margin	Margins with spacing scale, negative values, logical properties ( `mbs-` , `mbe-` )	layout-margin
Padding	Padding with spacing scale, logical properties ( `pbs-` , `pbe-` )	layout-padding

Overflow

Topic	Description	Reference
Overflow	Controlling how elements handle content that overflows	layout-overflow

Images & Replaced Elements

Topic	Description	Reference
Object Fit & Position	Controlling how images and video are resized and positioned	layout-object-fit-position

Tables

Topic	Description	Reference
Table Layout	border-collapse, table-auto, table-fixed	layout-tables

Transforms

Topic	Description	Reference
Transform Base	Base transform utilities, hardware acceleration, custom transform values	transform-base
Translate	Translating elements on x, y, z axes with spacing scale and percentages	transform-translate
Rotate	Rotating elements in 2D and 3D space	transform-rotate
Scale	Scaling elements uniformly or on specific axes	transform-scale
Skew	Skewing elements on x and y axes	transform-skew

Typography

Topic	Description	Reference
Font & Text	Font size, weight, color, line-height, letter-spacing, decoration, truncate, `wrap-break-word` , `wrap-anywhere`	typography-font-text
Text Align	Controlling text alignment with left, center, right, justify	typography-text-align
List Style	list-style-type, list-style-position for bullets and markers	typography-list-style

Visual

Topic	Description	Reference
Background	Background color, gradient, image, size, position	visual-background
Border	Border width, color, radius, divide, ring, block border utilities ( `border-bs-` , `border-be-` )	visual-border
Effects	Box shadow, opacity, mix-blend, backdrop-blur, filter, colored drop shadows	visual-effects
SVG	fill, stroke, stroke-width for SVG and icon styling	visual-svg
Text Shadow	Text shadow sizes, colors, and opacity modifiers (v4.1)	effects-text-shadow
Mask	Composable mask utilities with gradient and radial masks (v4.1)	effects-mask

Effects & Interactivity

Topic	Description	Reference
Transition & Animation	CSS transitions, animation keyframes, reduced motion	effects-transition-animation
Visibility & Interactivity	Visibility, cursor, pointer-events, user-select, z-index	effects-visibility-interactivity
Form Controls	accent-color, appearance, caret-color, resize	effects-form-controls
Scroll Snap	scroll-snap-type, scroll-snap-align for carousels	effects-scroll-snap

Features

Dark Mode

Topic	Description	Reference
Dark Mode	Dark mode with `dark:` variant, `@custom-variant` , class and data-attribute strategies	features-dark-mode

Migration

Topic	Description	Reference
Upgrade Guide	Migrating from v3 to v4, all renamed/removed utilities, scale shifts, config migration	features-upgrade

Customization

Topic	Description	Reference
Custom Styles	Adding custom styles, utilities with `@utility` , variants with `@custom-variant` , arbitrary values	features-custom-styles
Functions & Directives	Tailwind's CSS directives ( `@theme` , `@utility` , `@custom-variant` , `@source` ) and functions	features-functions-directives
Content Detection	How Tailwind detects classes, `@source` configuration, safelisting with `@source inline()`	features-content-detection

Best Practices

Topic	Description	Reference
Utility Patterns	Managing duplication, conflicts, important modifier, when to use components	best-practices-utility-patterns

Key Recommendations

Use utility classes directly in markup — compose designs by combining utilities
Customize with
@theme
directive — define design tokens as CSS variables, not in JS config
Mobile-first responsive design — unprefixed utilities for mobile, prefixed for breakpoints
Use complete class names — never construct classes dynamically with string interpolation
Leverage variants — stack variants for complex conditional styling (
```
dark:md:hover:bg-blue-600
```
)
Prefer CSS-first configuration — use
```
@theme
```
,
```
@utility
```
, and
```
@custom-variant
```
over JavaScript configs
Use oklch for custom colors — Tailwind v4 defaults to oklch; prefer it for perceptual uniformity
Use rem for custom breakpoints — e.g.,
```
--breakpoint-3xl: 90rem
```
not
```
1440px
```
Know the scale shifts — shadow, rounded, and blur all shifted down one step in v4
Use
@custom-variant
(not
```
@variant
```
) — for defining custom variants like class-based dark mode

tailwindcss-best-practices

NPX Install

Tags

SKILL.md Content