Tailwind CSS v4
How to write idiomatic Tailwind v4 and spot v3-era syntax that still compiles but should not appear in new code.
Version and sources
Check the pinned version before using recent utilities: the playground packages pin tailwindcss in their package.json (4.3.3 at the time of writing, including v4.3 utilities like scrollbar-*, zoom-*, and tab-*). When unsure whether a utility, variant, or directive exists in the pinned version, verify against the docs instead of guessing:
CSS-first configuration
Tailwind v4 is configured in CSS, not JavaScript.
| Use |
Never use (v3-era) |
@import 'tailwindcss' |
@tailwind base/components/utilities |
@theme { --color-x: ...; } for tokens that should generate utilities |
tailwind.config.ts for new work |
@utility name { ... } for custom utilities (works with variants) |
@layer utilities { .name { ... } } |
@custom-variant dark (&:is(.dark *)) |
JS plugins / addVariant |
@source "path" / @source inline("...") for extra sources / safelisting |
content array / safelist config |
@variant dark { ... } to apply a Tailwind variant inside custom CSS |
duplicating media queries / selectors |
@reference "app.css" for @apply in scoped styles (Vue, CSS Modules) |
duplicating stylesheet imports |
var(--color-x) in CSS, getComputedStyle in JS |
theme() function, resolveConfig |
@config "…" / @plugin "…" only for existing JS-config integrations |
adding new JS configs or plugins |
@theme variables are API: each one emits a native CSS variable AND generates utilities (--color-* → bg-*/text-*/border-*/..., --text-* → text-*, --shadow-* → shadow-*, --animate-* → animate-*, --breakpoint-* → responsive variants). A plain :root { --x: ...; } variable generates nothing — use it for runtime-only values. When a token's value references another variable (--color-x: var(--y)), declare it in @theme inline so the utility resolves the reference at the declaration site. In custom CSS, --alpha(var(--color-x) / 50%) and --spacing(4) replace v3 theme() math.
v3 → v4 renames
Bare names shifted one step down the scale, so the v3 spelling silently renders smaller or lighter:
| v3 |
v4 |
shadow-sm / shadow |
shadow-xs / shadow-sm |
drop-shadow-sm / drop-shadow |
drop-shadow-xs / drop-shadow-sm |
blur-sm / blur |
blur-xs / blur-sm |
rounded-sm / rounded |
rounded-xs / rounded-sm |
outline-none |
outline-hidden (a11y-safe); outline-none now truly removes it |
ring (3px) |
ring-3; the default ring is now 1px currentColor |
bg-opacity-50, text-opacity-* |
opacity modifier: bg-black/50, text-white/50 |
bg-gradient-to-r |
bg-linear-to-r (plus new bg-conic-*, bg-radial-*) |
!bg-red-500 (prefix) |
bg-red-500! (suffix) |
flex-shrink-* / flex-grow-* |
shrink-* / grow-* |
bg-[--var] |
bg-(--var); brackets now require bg-[var(--var)] |
grid-cols-[a,b] (commas) |
underscores: grid-cols-[max-content_auto] |
Prefer generated utilities over arbitrary values
The spacing scale is infinite — every number compiles via calc(var(--spacing) * n) — so most v3-era arbitrary values have a named form:
| Don't |
Do |
min-w-[400px], w-[600px] |
min-w-100, w-150 |
h-[1.5rem] w-[1.5rem] |
size-6 |
mt-[68px] |
mt-17 |
grid-cols-[repeat(15,minmax(0,1fr))] |
grid-cols-15 |
h-[100dvh], w-[100dvw], h-[1lh] |
h-dvh, w-dvw, h-lh |
max-w-[80rem] |
max-w-7xl (container scale) |
data-[current]:opacity-100 |
data-current:opacity-100 (values keep brackets: data-[state=open]:) |
bg-[var(--row-bg)] |
bg-(--row-bg); type hints when ambiguous: text-(color:--fg), text-(length:--size) |
Square brackets remain correct for true one-offs: max-h-[calc(100dvh-3rem)], grid-cols-[200px_minmax(0,1fr)], and arbitrary properties like [mask-type:luminance].
Class strings must stay complete and statically detectable: map props to full strings ({ success: 'bg-positive1' }[tone]), never build fragments like `bg-${tone}-500`.
Don't hand-write CSS or JS for what a variant covers
Before writing a stylesheet rule, a style prop, or an event handler for styling, check for a variant:
| Hand-written |
Tailwind |
.btn:active { ... } in CSS |
active:bg-surface5 |
:focus-visible rules |
focus-visible:outline-accent1 |
[aria-expanded="true"] selectors |
aria-expanded:rotate-180 (any aria-* boolean or value) |
[data-state="open"] selectors |
data-[state=open]:opacity-100, boolean: data-current: |
| JS hover/focus state to style a sibling/child |
group/group-hover:, peer/peer-checked:, in-focus: |
| parent-state selectors / JS "has child" checks |
has-checked:bg-accent1, has-[>svg]:pl-8 |
mask-image / fade-out gradients in CSS |
mask-b-from-80%, mask-t-from-* |
@media (hover: none) blocks |
pointer-coarse:/pointer-fine: |
| first/last/nth rules in CSS |
first:, last:, odd:, nth-3:, not-first: |
| styling all children from CSS |
*:rounded-full (children), **:data-avatar:rounded-full (descendants) |
New capabilities — reach for these before hacks or JS
field-sizing-content — auto-growing textarea without a JS resize listener.
wrap-anywhere / wrap-break-word — long-word breaking inside flex without the min-w-0 hack.
items-center-safe, justify-center-safe — centering that falls back to start on overflow.
pointer-coarse: / pointer-fine: — adapt touch targets without user-agent sniffing.
user-valid: / user-invalid: — validation styling only after user interaction (unlike :valid).
starting: (+ transition-discrete for display/popover) — enter transitions without JS mount tricks.
text-shadow-*, mask-t-from-*/mask-b-to-* (fade-out edges), scheme-dark (native controls/scrollbars), 3D transforms (rotate-x-*, perspective-*).
Behavior changes to remember
- Transforms use individual CSS properties: custom transition lists need
transition-[opacity,scale], not transition-[opacity,transform]; reset with scale-none/rotate-none/translate-none.
hover: only applies on hover-capable devices (@media (hover: hover)) — never gate required touch functionality behind hover.
- Default
border-*, divide-*, ring, and outline colors are currentColor — set an explicit color when the color matters.
- Variant stacking applies left to right: v3
first:*:pt-0 is now *:first:pt-0.
space-x/y-* changed selectors (:not(:last-child)); prefer flex/grid with gap-*.
- Container queries are built in:
@container on the parent, @sm:/@max-md: on children.
- Useful v4 variants:
starting: (enter transitions), not-*, in-* (like group-* without the group class), nth-*, *: (direct children), **: (descendants), inert:.
Motion
- Gate decorative animation:
motion-safe:animate-spin motion-reduce:animate-none.
- Reusable animations are
--animate-* tokens with their @keyframes inside @theme; local one-offs use animate-(--local-animation) or animate-[...].
1---
2name: tailwind-v4
3description: Tailwind CSS v4 usage guide and v3-to-v4 differences. This skill should be used when writing, reviewing, or refactoring any Tailwind CSS code in this repo. Triggers on tasks involving Tailwind classes, @theme blocks, CSS-first configuration, or cleanup of v3-era syntax.
4metadata:
5 source: https://skillmd.com/skills/mastra-ai/tailwind-v4
6---
7
8# Tailwind CSS v4
9
10How to write idiomatic Tailwind v4 and spot v3-era syntax that still compiles but should not appear in new code.
11
12## Version and sources
13
14Check the pinned version before using recent utilities: the playground packages pin `tailwindcss` in their `package.json` (4.3.3 at the time of writing, including v4.3 utilities like `scrollbar-*`, `zoom-*`, and `tab-*`). When unsure whether a utility, variant, or directive exists in the pinned version, verify against the docs instead of guessing:
15
16- Utility/variant reference: https://tailwindcss.com/docs
17- v3 → v4 migration: https://tailwindcss.com/docs/upgrade-guide
18- What each minor added: https://tailwindcss.com/blog/tailwindcss-v4 (and `/tailwindcss-v4-1`, `/tailwindcss-v4-3`, ...)
19
20## CSS-first configuration
21
22Tailwind v4 is configured in CSS, not JavaScript.
23
24| Use | Never use (v3-era) |
25| -------------------------------------------------------------------------- | ------------------------------------- |
26| `@import 'tailwindcss'` | `@tailwind base/components/utilities` |
27| `@theme { --color-x: ...; }` for tokens that should generate utilities | `tailwind.config.ts` for new work |
28| `@utility name { ... }` for custom utilities (works with variants) | `@layer utilities { .name { ... } }` |
29| `@custom-variant dark (&:is(.dark *))` | JS `plugins` / `addVariant` |
30| `@source "path"` / `@source inline("...")` for extra sources / safelisting | `content` array / `safelist` config |
31| `@variant dark { ... }` to apply a Tailwind variant inside custom CSS | duplicating media queries / selectors |
32| `@reference "app.css"` for `@apply` in scoped styles (Vue, CSS Modules) | duplicating stylesheet imports |
33| `var(--color-x)` in CSS, `getComputedStyle` in JS | `theme()` function, `resolveConfig` |
34| `@config "…"` / `@plugin "…"` only for existing JS-config integrations | adding new JS configs or plugins |
35
36`@theme` variables are API: each one emits a native CSS variable AND generates utilities (`--color-*` → `bg-*`/`text-*`/`border-*`/..., `--text-*` → `text-*`, `--shadow-*` → `shadow-*`, `--animate-*` → `animate-*`, `--breakpoint-*` → responsive variants). A plain `:root { --x: ...; }` variable generates nothing — use it for runtime-only values. When a token's value references another variable (`--color-x: var(--y)`), declare it in `@theme inline` so the utility resolves the reference at the declaration site. In custom CSS, `--alpha(var(--color-x) / 50%)` and `--spacing(4)` replace v3 `theme()` math.
37
38## v3 → v4 renames
39
40Bare names shifted one step down the scale, so the v3 spelling silently renders smaller or lighter:
41
42| v3 | v4 |
43| --------------------------------- | ----------------------------------------------------------------- |
44| `shadow-sm` / `shadow` | `shadow-xs` / `shadow-sm` |
45| `drop-shadow-sm` / `drop-shadow` | `drop-shadow-xs` / `drop-shadow-sm` |
46| `blur-sm` / `blur` | `blur-xs` / `blur-sm` |
47| `rounded-sm` / `rounded` | `rounded-xs` / `rounded-sm` |
48| `outline-none` | `outline-hidden` (a11y-safe); `outline-none` now truly removes it |
49| `ring` (3px) | `ring-3`; the default ring is now 1px `currentColor` |
50| `bg-opacity-50`, `text-opacity-*` | opacity modifier: `bg-black/50`, `text-white/50` |
51| `bg-gradient-to-r` | `bg-linear-to-r` (plus new `bg-conic-*`, `bg-radial-*`) |
52| `!bg-red-500` (prefix) | `bg-red-500!` (suffix) |
53| `flex-shrink-*` / `flex-grow-*` | `shrink-*` / `grow-*` |
54| `bg-[--var]` | `bg-(--var)`; brackets now require `bg-[var(--var)]` |
55| `grid-cols-[a,b]` (commas) | underscores: `grid-cols-[max-content_auto]` |
56
57## Prefer generated utilities over arbitrary values
58
59The spacing scale is infinite — every number compiles via `calc(var(--spacing) * n)` — so most v3-era arbitrary values have a named form:
60
61| Don't | Do |
62| -------------------------------------- | --------------------------------------------------------------------------------------- |
63| `min-w-[400px]`, `w-[600px]` | `min-w-100`, `w-150` |
64| `h-[1.5rem] w-[1.5rem]` | `size-6` |
65| `mt-[68px]` | `mt-17` |
66| `grid-cols-[repeat(15,minmax(0,1fr))]` | `grid-cols-15` |
67| `h-[100dvh]`, `w-[100dvw]`, `h-[1lh]` | `h-dvh`, `w-dvw`, `h-lh` |
68| `max-w-[80rem]` | `max-w-7xl` (container scale) |
69| `data-[current]:opacity-100` | `data-current:opacity-100` (values keep brackets: `data-[state=open]:`) |
70| `bg-[var(--row-bg)]` | `bg-(--row-bg)`; type hints when ambiguous: `text-(color:--fg)`, `text-(length:--size)` |
71
72Square brackets remain correct for true one-offs: `max-h-[calc(100dvh-3rem)]`, `grid-cols-[200px_minmax(0,1fr)]`, and arbitrary properties like `[mask-type:luminance]`.
73
74Class strings must stay complete and statically detectable: map props to full strings (`{ success: 'bg-positive1' }[tone]`), never build fragments like `` `bg-${tone}-500` ``.
75
76## Don't hand-write CSS or JS for what a variant covers
77
78Before writing a stylesheet rule, a `style` prop, or an event handler for styling, check for a variant:
79
80| Hand-written | Tailwind |
81| ---------------------------------------------- | ------------------------------------------------------------------------ |
82| `.btn:active { ... }` in CSS | `active:bg-surface5` |
83| `:focus-visible` rules | `focus-visible:outline-accent1` |
84| `[aria-expanded="true"]` selectors | `aria-expanded:rotate-180` (any `aria-*` boolean or value) |
85| `[data-state="open"]` selectors | `data-[state=open]:opacity-100`, boolean: `data-current:` |
86| JS hover/focus state to style a sibling/child | `group`/`group-hover:`, `peer`/`peer-checked:`, `in-focus:` |
87| parent-state selectors / JS "has child" checks | `has-checked:bg-accent1`, `has-[>svg]:pl-8` |
88| `mask-image` / fade-out gradients in CSS | `mask-b-from-80%`, `mask-t-from-*` |
89| `@media (hover: none)` blocks | `pointer-coarse:`/`pointer-fine:` |
90| first/last/nth rules in CSS | `first:`, `last:`, `odd:`, `nth-3:`, `not-first:` |
91| styling all children from CSS | `*:rounded-full` (children), `**:data-avatar:rounded-full` (descendants) |
92
93## New capabilities — reach for these before hacks or JS
94
95- `field-sizing-content` — auto-growing textarea without a JS resize listener.
96- `wrap-anywhere` / `wrap-break-word` — long-word breaking inside flex without the `min-w-0` hack.
97- `items-center-safe`, `justify-center-safe` — centering that falls back to `start` on overflow.
98- `pointer-coarse:` / `pointer-fine:` — adapt touch targets without user-agent sniffing.
99- `user-valid:` / `user-invalid:` — validation styling only after user interaction (unlike `:valid`).
100- `starting:` (+ `transition-discrete` for `display`/popover) — enter transitions without JS mount tricks.
101- `text-shadow-*`, `mask-t-from-*`/`mask-b-to-*` (fade-out edges), `scheme-dark` (native controls/scrollbars), 3D transforms (`rotate-x-*`, `perspective-*`).
102
103## Behavior changes to remember
104
105- Transforms use individual CSS properties: custom transition lists need `transition-[opacity,scale]`, not `transition-[opacity,transform]`; reset with `scale-none`/`rotate-none`/`translate-none`.
106- `hover:` only applies on hover-capable devices (`@media (hover: hover)`) — never gate required touch functionality behind hover.
107- Default `border-*`, `divide-*`, ring, and outline colors are `currentColor` — set an explicit color when the color matters.
108- Variant stacking applies left to right: v3 `first:*:pt-0` is now `*:first:pt-0`.
109- `space-x/y-*` changed selectors (`:not(:last-child)`); prefer flex/grid with `gap-*`.
110- Container queries are built in: `@container` on the parent, `@sm:`/`@max-md:` on children.
111- Useful v4 variants: `starting:` (enter transitions), `not-*`, `in-*` (like `group-*` without the `group` class), `nth-*`, `*:` (direct children), `**:` (descendants), `inert:`.
112
113## Motion
114
115- Gate decorative animation: `motion-safe:animate-spin motion-reduce:animate-none`.
116- Reusable animations are `--animate-*` tokens with their `@keyframes` inside `@theme`; local one-offs use `animate-(--local-animation)` or `animate-[...]`.