The Upgrade That Changed Every Border

Scenario

Example team: a SaaS app upgrades from Tailwind v3.4 to v4 by bumping the package and replacing the @tailwind directives. The build passes and the team ships on a Friday.

What you see in production

Card borders are suddenly black instead of light grey, input focus rings are barely visible, small shadows look heavier, and a few buttons lose their translucent backgrounds.

The naive code

<div class="border rounded shadow-sm">…</div>         <!-- v3 meaning: gray-200 border, 4px radius, small shadow -->
<input class="focus:ring focus:outline-none">           <!-- v3: 3px ring -->
<div class="bg-black bg-opacity-50">…</div>             <!-- removed in v4 -->

Reproduce it

The same classes under v4 (left) next to the v4 equivalents of the v3 look (right):

<div class="grid gap-4 p-6 sm:grid-cols-2">
  <div class="rounded border p-4 shadow-sm">border (now currentColor), rounded, shadow-sm</div>
  <div class="rounded-sm border border-gray-200 p-4 shadow-xs">border-gray-200, rounded-sm, shadow-xs</div>
  <input placeholder="focus:ring (now 1px)" class="rounded border px-3 py-2 focus:ring focus:outline-hidden">
  <input placeholder="focus:ring-3" class="rounded border border-gray-300 px-3 py-2 focus:ring-3 focus:ring-sky-300 focus:outline-hidden">
</div>

Root cause

v4 changed defaults and renamed scales: border uses currentColor instead of gray-200, ring is 1px instead of 3px, shadow-sm is the old shadow, rounded is the old rounded-md scale shifted, and opacity utilities like bg-opacity-50 were removed. A version bump without the upgrade tool leaves old meanings in your markup.

The fix

• Run npx @tailwindcss/upgrade on a branch; it rewrites renamed classes and your config.
• Review the upgrade guide's list of changed defaults and add explicit colours (border-gray-200).
• Compare screenshots of key pages before and after (visual regression testing).
• If you need the old border colour everywhere, set it once in your base layer.

Trade-offs

• The upgrade tool handles most cases, but not class names built dynamically or stored in a database.
• v4 requires modern browsers; check your analytics before upgrading.

Detect it in production

• Visual regression tests on critical flows.
• A search for removed utilities (bg-opacity-, text-opacity-, flex-shrink-) after the upgrade.

Key points

• Upgrades change defaults, not just syntax: borders, rings and shadow scales.
• Use the upgrade tool, then compare screenshots.
• Make important colours explicit instead of relying on defaults.