## When NOT to use
−- Projects locked to Tailwind CSS v3 without upgrade path — `@theme` is v4 only; follow the upgrade guide instead
+- Projects locked to Tailwind CSS v3 without upgrade path — `@theme` is v4 only; follow the official upgrade guide instead
- Quick prototypes where speed matters more than consistency — use default Tailwind utilities
−- Extremely old-browser targets (see v4 browser requirements below)
+- Extremely old-browser targets (see compatibility notes below)
- Design work in Figma without a code component — define tokens in Figma variables first, then mirror here
## Key platform notes (short)
+- Tailwind v4 requires a modern-browser baseline. v4.1 (released April 3, 2025) improved graceful degradation for older browsers while still using modern features where available (Tailwind v4.1 blog).
+- The v4 upgrade tool (`npx @tailwindcss/upgrade`) is the supported migration helper for v3→v4; verify Node and environment requirements in the official upgrade guide before running it in CI.
−- Tailwind v4 requires modern browsers. Official guidance for v4's engine targets modern browsers; v4.1 improves graceful degradation for older browsers (see v4.1 notes). If your project must support older browsers, remain on v3.4 until you can upgrade.
+- Tailwind v4 favors CSS-first configuration and `@theme`-driven tokens; see the Theme Variables docs for details on how `@theme` influences generated utilities.
−- The v4 upgrade tool requires Node.js 20+. Run `npx @tailwindcss/upgrade` in a feature branch and review changes.
−- Tailwind v4 favors CSS-first configuration and `@theme`-driven tokens (docs: https://tailwindcss.com/docs/theme).
## Core concepts
@@ −38 +38 @@
- Motion — `--duration-`, `--ease-`
- Z-index — `--z-`
- Blur — `--blur-`
−- Mask / Clip / Text-Shadow — `--mask-`, `--text-shadow-` (v4.1 adds utilities; expose tokens when you need consistent styles)
+- Mask / Clip / Text-Shadow — `--mask-`, `--text-shadow-` (Tailwind v4.1 added utilities; expose tokens when you need consistent styles)
### Concentric radii rule
@@ −60 +60 @@
### 1. Define the complete `@theme` block
−Use `@theme` at top-level CSS to declare every token that should produce utility classes. Tailwind uses the `@theme` block to both expose CSS variables and generate class names (see docs).
+Use `@theme` at top-level CSS to declare every token that should produce utility classes. Tailwind uses the `@theme` block to both expose CSS variables and generate class names (see the Theme Variables docs).
Example `@theme` (semantic tokens):
