Build interfaces without leaving your markup.
A practical, production-focused guide to Tailwind CSS v4 — the CSS-first architecture, every core concept, real component patterns, and an honest account of what changed since v3.
Start here#
Installation
Vite, PostCSS, the CLI and the Play CDN — with the v4 commands, not the v3 ones.
Utility-first CSS
Why composing small classes beats hand-written component CSS, and where it stops paying off.
Theme & design tokens
The @theme directive replaced tailwind.config.js. Here is how tokens work now.
Cheat sheet
The utilities you reach for daily, grouped so you can scan instead of read.
What changed in v4#
Tailwind v4 is a rewrite, not a point release. If you learned Tailwind on v3, these five changes account for most of the friction:
| Area | Tailwind v3 | Tailwind v4 |
|---|---|---|
| Configuration | tailwind.config.js | @theme in your CSS |
| Entry point | @tailwind base/components/utilities | @import "tailwindcss" |
| Content paths | content: [...] array | Automatic source detection |
| PostCSS plugin | tailwindcss | @tailwindcss/postcss |
| Colour format | rgb() / hex | oklch() |
Learning path#
Follow this order if you are new. Each step assumes only the ones above it.
- Install Tailwind — pick Vite, PostCSS or the CLI and get a build running.
- Write your first utilities — learn to read a class name.
- Lay things out — Flexbox and Grid cover almost every layout you will build.
- Go responsive — mobile-first breakpoints, then container queries.
- Add state — hover, focus, disabled,
group-*andpeer-*. - Support dark mode — the media strategy, then the class strategy.
- Own your design tokens —
@theme, colours, spacing, typography. - Extend Tailwind — custom utilities, variants and plugins.
- Ship it — production builds, bundle size and performance.
See the annotated version at Learning Path.
Browse by topic#
Layout
Display, position, Flexbox, Grid, containers, columns, overflow and stacking.
Styling
Colours, backgrounds, gradients, borders, shadows, filters and effects.
Typography
Font families, sizes, weights, line height, tracking and text decoration.
Motion
Transitions, 2D and 3D transforms, keyframe animation and reduced motion.
Components
Buttons, forms, cards, navigation, tables, modals and toasts.
Advanced
Custom utilities and variants, arbitrary values, plugins and production builds.
About this handbook#
Every code sample here targets Tailwind CSS v4.3. Where a technique only applies to older versions it is labelled explicitly:
Current works in v4.3 New in v4 introduced by the rewrite Legacy v3-era, still works Deprecated removed or scheduled for removal
The original v3-era example pages this handbook grew out of are preserved, unchanged, in legacy/v3-examples/. They are kept for reference only — see Legacy Projects before copying anything out of them.