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
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
