Tailwind Core V3 Vs V4

Tailwind CSS v3 vs v4

This skill is the version-comparison reference for Tailwind CSS. Every section presents v3 and v4 side-by-side. Pair with companion skills:

• tailwind-impl-migration-v3-v4 : step-by-step upgrade execution
• tailwind-errors-v4-migration : trap catalog when an upgrade breaks builds

Quick Decision Tree

Do you control the browser baseline (Safari 16.4+, Chrome 111+, Firefox 128+)?
├── NO  → STAY on v3.4 (v4 requires @property and color-mix() support)
└── YES → Is the project new (greenfield)?
    ├── YES → USE v4 (CSS-first config, faster builds, native @import + autoprefix)
    └── NO  → Does the project use ANY of: corePlugins, safelist, separator,
              custom prefix with `tw-` pattern, JS resolveConfig at runtime,
              or Sass/Less/Stylus in the pipeline?
        ├── YES → STAY on v3.4 until alternatives are in place
        │        (corePlugins and separator have NO v4 replacement)
        └── NO  → UPGRADE with `npx @tailwindcss/upgrade` (requires Node 20+)
                  then expect visual diffs from border-color, ring-width, and
                  shadow/blur/radius scale renames.

Engine Model

Source : https://tailwindcss.com/blog/tailwindcss-v4

Browser Baseline (v4 only)

v4 ALWAYS requires Safari 16.4+, Chrome 111+, Firefox 128+ because Oxide emits @property and color-mix(). NEVER ship v4 to a project that must support older browsers. Stay on v3.4 instead.

Configuration

See references/examples.md for a complete v3 config rewritten as a v4 stylesheet.

CSS Entry-Point

/* v3 : three @tailwind directives required */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 : single @import replaces all three */
@import "tailwindcss";

The v3 @tailwind directives ALWAYS error in v4 with "Cannot apply unknown utility class". This is the most common upgrade failure. Always replace ALL three before first build.

Default Behaviour Shifts (visual breakage)

These v4 changes affect EVERY existing v3 project on upgrade. Verified against the official upgrade guide.

ALWAYS apply the shims OR refactor markup. NEVER ignore these on upgrade : unstyled borders and 1px rings on cards/inputs are the most reported visual regressions in v4 upgrade threads.

Source : https://tailwindcss.com/docs/upgrade-guide

Scale Renames (size-shift by one step)

EVERY size-suffixed scale shifted down by one in v4 because a new -xs step was inserted. Existing shadow-sm becomes visually smaller after upgrade.

ALWAYS run npx @tailwindcss/upgrade first ; it renames the call sites. NEVER rely on visual parity after upgrade without checking each shadowed card, input ring, and rounded badge.

Removed Without Replacement

If a v3 project depends on any of these, STAY on v3.4 until the dependency is removed. Migrating then failing to compile is the most common v4 upgrade trap.

Source : https://tailwindcss.com/docs/upgrade-guide

Variant Stacking Order (silent semantic change)

v3 reads variant chains right-to-left. v4 reads left-to-right.

<!-- v3 : "first child of any direct child", reading right-to-left -->
<ul class="first:*:pt-0">

<!-- v4 equivalent : "any direct child, first one", reading left-to-right -->
<ul class="*:first:pt-0">

The upgrade tool rewrites common cases. ALWAYS manually review bespoke arbitrary-variant stacks like [&>div]:hover:bg-red-500 combined with structural selectors. See tailwind-syntax-variants for the full rule set.

Source : https://tailwindcss.com/docs/upgrade-guide

Renamed Utilities (auto-fixed by upgrade tool)

Full table in references/methods.md.

New v4-Only APIs

The @reference Trap (Vue, Svelte, CSS modules)

v3 scoped stylesheets in Vue SFC <style>, Svelte component <style>, and CSS modules ALWAYS had implicit theme context. v4 compiles each scoped block in isolation, so @apply text-2xl fails with "Cannot apply unknown utility class".

<!-- v3 : works -->
<style scoped>
.btn { @apply px-4 py-2 bg-blue-500 text-white; }
</style>

<!-- v4 : requires @reference at the top of the scoped block -->
<style scoped>
@reference "../app.css";
.btn { @apply px-4 py-2 bg-blue-500 text-white; }
</style>

ALWAYS add @reference to every scoped <style> block in v4 projects. NEVER assume @apply works without it. See tailwind-errors-v4-migration for the full failure mode catalogue.

Source : https://tailwindcss.com/docs/functions-and-directives and https://github.com/tailwindlabs/tailwindcss/issues/16346

Decision Tree : Should I Upgrade Now?

START
  │
  ├── Browser support requires IE11, Safari <16.4, Chrome <111, or Firefox <128 ?
  │   └── YES → STAY v3.4 (hard blocker, v4 cannot work)
  │
  ├── Project uses corePlugins to disable utilities ?
  │   └── YES → STAY v3.4 until the disabled utilities are removed
  │       from source instead (no v4 replacement exists)
  │
  ├── Project uses Sass, Less, or Stylus preprocessor ?
  │   └── YES → STAY v3.4 until preprocessor is removed
  │
  ├── Project uses resolveConfig() in runtime JS (e.g. a charting lib that
  │   needs tailwind theme colours at runtime) ?
  │   └── YES → Refactor to read `getComputedStyle(...).getPropertyValue('--color-*')`,
  │             THEN upgrade
  │
  ├── Project uses safelist with regex patterns ?
  │   └── YES → Rewrite as `@source inline("...")` with brace expansion,
  │             THEN upgrade
  │
  ├── Project is Vue / Svelte / CSS-modules with scoped <style> blocks ?
  │   └── YES → UPGRADE possible, BUT add `@reference "../app.css";` to
  │             every scoped block first or post-upgrade
  │
  └── None of the above → UPGRADE
      ├── Run `npx @tailwindcss/upgrade` on a clean branch (Node 20+)
      ├── Apply the v3-default shims for border-color and ring (if visual
      │   parity matters more than clean v4 code)
      └── Verify shadow / blur / rounded / drop-shadow / backdrop-blur
          call sites visually (sizes shifted by one step)

Partial Upgrade Strategy

v4 ALWAYS supports the v3 JS config via @config "./tailwind.config.js", so a partial upgrade path is :

1. Move to the v4 engine (replace @tailwind with @import "tailwindcss").
2. Keep @config "./tailwind.config.js"; at the top of the stylesheet.
3. Migrate theme.extend keys to @theme block one category at a time.
4. Remove @config when nothing remains in the JS config.

NEVER mix @theme and theme.extend for the SAME token category : the v4 @theme wins but the duplication causes silent drift. Migrate per category and delete the JS-config entry in the same commit.

Cross-References

Reference Files

• references/methods.md : complete API breaking-changes table (removed, renamed, new)
• references/examples.md : side-by-side v3 vs v4 code for install, config, dark mode, plugins, scoped styles
• references/anti-patterns.md : upgrade traps with root cause and fix

Verified Sources

• https://tailwindcss.com/blog/tailwindcss-v4 (engine, performance numbers)
• https://tailwindcss.com/docs/upgrade-guide (breaking changes, shims)
• https://tailwindcss.com/docs/functions-and-directives (new v4 APIs)
• https://v3.tailwindcss.com/docs/configuration (v3 config surface)
• https://github.com/tailwindlabs/tailwindcss/issues/16346 (@apply + @reference trap)