Tailwind patterns

Default assumption: Tailwind v4 with CSS-first config. If the project has a tailwind.config.js it is v3 and the v3 section applies; otherwise v4.

v4 vs v3 at a glance

• v4 setup: a single @import "tailwindcss" in the main CSS file. No @tailwind base / components / utilities directives.
• v4 config: lives in CSS via the @theme directive. No tailwind.config.js. Theme tokens become CSS custom properties automatically.
• v4 content detection: automatic. The compiler scans the project for class names; you do not configure content paths.
• v4 plugins: still work. Container queries are built in; typography and forms remain separate @tailwindcss/* plugins. Check before installing.
• v4 build: full builds ~3.8x and incremental rebuilds 8.8x faster than v3.4; @import bundling and vendor prefixing are built in (Lightning CSS under the hood).

Setting up v4 correctly

/* app/globals.css or equivalent */
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.7 0.15 250);
  --font-display: "Inter", sans-serif;
  --spacing-page: 4rem;
  --breakpoint-3xl: 1920px;
}

• Theme keys follow the pattern --<namespace>-<name>. Namespaces: color, font, text, spacing, breakpoint, radius, shadow, animate, etc.
• Defining a key generates the corresponding utility (text-brand, font-display, p-page, 3xl:).
• Use oklch() for new colors; v4's default palette is OKLCH-based for better wide-gamut support.

v3 patterns to avoid in v4

• tailwind.config.js: do not create one in a v4 project. Move config into @theme blocks. If the file exists in a v4 project, it is dead code.
• @tailwind base; @tailwind components; @tailwind utilities;: v3 directive triple. v4 replaces these with a single @import "tailwindcss".
• theme.extend: v3 JS shape. In v4, all CSS-defined --<namespace>-<name> tokens extend the default theme automatically.
• content: [...]: v3 path config. v4 auto-detects.
• @layer utilities { ... } for arbitrary utility classes: still works, but prefer defining custom utilities with the @utility directive in v4 for better tree-shaking.

Using theme values from CSS

• var(--color-brand): read a theme value in plain CSS. Every @theme key is a CSS custom property; there is no separate read function in the v4 docs.
• --alpha(var(--color-brand) / 50%): compute an alpha-modified color in v4. v3 used the theme() helper, kept in v4 only for compatibility.

Variants and modifiers

• v4 variant order: hover:focus:bg-blue-500 applies hover AND focus, just like v3. No change.
• New in v4:
  • not- variant prefix (not-hover:opacity-50)
  • nth-* variants (nth-3:, nth-[3n+1]:); the *: direct-children variant predates v4 (3.4)
  • starting-style variants (starting:opacity-0 for entry animations)
• Container queries are built in: @container on the parent, @sm:flex etc. on children. No plugin install.

Anti-patterns to flag in review

warning: hardcoded hex colors when a theme token would work text-[#ff0000] bypasses the design system. Use the existing token; if missing, add it to @theme.

warning: @apply chains longer than three utilities They obscure the cascade and inhibit tree-shaking. Use a CSS class with raw properties instead, or compose at the markup level.

info: conditional @apply inside @media or selector blocks Works, but readability falls off fast. Inline utilities or extract a component.

warning: dark: everywhere instead of a [data-theme="dark"] strategy Inconsistent when the project already has a theme toggle. v4 supports both; pick one.

info: animate-[...] arbitrary values when a named animation exists Define --animate-<name> in @theme and reuse it instead of repeating the arbitrary value.

warning: missing text- size on body copy Relying on the browser default (16px) instead of setting the base size explicitly leaves typography undocumented and inconsistent across components.

Verifying which version is in use

# v4: postcss config has @tailwindcss/postcss, OR vite plugin @tailwindcss/vite
rg '@tailwindcss/(postcss|vite)' package.json

# v4 config in CSS
rg '@import "tailwindcss"' --type css

# v3 sentinel: a tailwind.config.js or .ts
fd -t f 'tailwind.config'

If both tailwind.config.js and @import "tailwindcss" are present, the project is mid-migration. Treat as v4 but expect leftover v3 patterns.

References

• v4 release post: https://tailwindcss.com/blog/tailwindcss-v4
• v3-to-v4 upgrade guide: https://tailwindcss.com/docs/upgrade-guide
• v4 docs: https://tailwindcss.com/docs

Version notes

Checked: 2026-09-26 against https://tailwindcss.com/blog, https://tailwindcss.com/blog/tailwindcss-v4, https://tailwindcss.com/blog/tailwindcss-v3-4 and https://tailwindcss.com/docs/theme

• 4.3 (2026-05-08): no directive or function syntax change; no v5 exists.
• 4.0: CSS-first config (@import "tailwindcss", @theme, @utility, --alpha()), automatic content detection, not-, nth-*, and starting: variants (*: is 3.4; build-speed figures and the *: example corrected 2026-09-26). Theme values are read with var(--*), not a --theme() function (corrected 2026-09-12).
• 3.x: tailwind.config.js, @tailwind base/components/utilities, theme() helper. See "v3 patterns to avoid in v4".