Tailwind 4 dropped in December 2024 and the tech discourse went nuclear. CSS-first, @theme at-rules, native container queries, oklch colour space, smaller bundles. Shiny. But Velocity X — a 175+ component template with 1400+ lines of Tailwind config — stayed on 3.3.3. Not out of fear. Out of math.
What Actually Changed in Tailwind 4
Tailwind 4 rewrote the config model. Instead of a JavaScript object with nested keys, you now define theme variables as CSS custom properties inside a @layer theme block. That means your entire colour space, typography scale, and spacing system lives in CSS, not JS. Container queries are built-in syntax, not a third-party plugin. The colour space upgraded from sRGB to oklch by default — perceptually uniform, 30K more usable hues, better dark mode.
On paper: cleaner, smaller, more CSS-native. On a 175-component library: 500–800 lines of refactoring per project.
The Migration Math
Velocity X has 175 components spread across 12 feature sections. Each section owns its Tailwind utilities: buttons, cards, modals, headers, form inputs, pricing grids, testimonial blocks, SEO sections. The stack also includes 3 custom plugins (text-roller, animated-gradient, smooth-scroll-hero).
Migrating to Tailwind 4 means: rewrite the 1400-line config into @theme syntax, rebuild the three custom plugins for the new config shape, audit 175 components for deprecated utilities (v3 prose plugin moved, some sizing tokens renamed), validate dark mode across every component (oklch shifts perception in dark), and regression-test the entire site on mobile + desktop + light + dark.
Estimated cost: 40–60 dev hours. Real cost with debug loops: 80–100 hours.
Estimated gain: ~15KB gzipped bundle reduction, native container queries instead of plugin, one fewer JS dependency. Actual user-facing wins: none. Velocity X already ships with @tailwindcss/container-queries and users don't notice the 15KB because the page is dominated by images and fonts.
The Honest Trigger Conditions
Velocity X will move to Tailwind 4 when one of these happens:
1. A major Velocity feature requires v4-only patterns. If you're building a component that's easier in native container queries than with plugins, migrate then (not before). Bet on the feature, not the framework.
2. Tailwind 4 becomes 2+ major versions old and the ecosystem is stable. v4.0 and v4.1 will see breaking quirks. Let it settle. By v4.3, any gotchas will be documented.
3. A component library you depend on is Tailwind-4-only. If shadcn ships a v4-only variant or a key plugin drops v3 support, the decision makes itself.
4. You're onboarding a new contributor who's never touched Tailwind 3. Teaching v3 config syntax to someone who only knows v4 is friction. Once most collaborators are v4-native, staying on v3 costs more than moving.
Six FAQs
Isn't FOMO migration a real risk?
Not for Velocity X. Framework deprecation happens over 18+ months. Tailwind 3 won't become unmaintained until mid-2026 at earliest. You've got runway.
What if I'm starting a new project today?
Start on Tailwind 4. The one-time cost is paid upfront when the codebase is small. Velocity X is an established template — the incremental cost is what matters.
Can I run Tailwind 3 and 4 in the same monorepo?
Yes, but it's a support nightmare. One project upgrades, breaks in a subtle dark-mode way, and you're debugging two config paradigms. Avoid.
Does Tailwind 4 bundle size really matter for SPAs?
Only if your Tailwind CSS is >60KB gzipped. For Velocity X it's 35KB, so shaving 15KB is a 43% reduction. Sounds big; users don't feel 20KB. Invest the hours elsewhere.
Will my Tailwind 3 codebase become unmaintainable?
No. Tailwind 3 gets security patches and bug fixes until mid-2026. After that, it's stable. The syntax doesn't rot.
What's the long-term play?
In Q1 2027, when Tailwind 4 is v4.2+, Velocity X will tag a v3→v4 migration branch as a companion template. Existing users can backport selectively; new forks start on v4. That's the low-pain moment.
The Bottom Line
Tailwind 4 is legitimately better for new projects and smaller codebases. For established component libraries with 175+ utilities and stable production traffic, the migration ROI doesn't exist yet. Stay on 3, keep the momentum, and move when one of the trigger conditions fires. Pragmatism beats resume-driven upgrades — that's how you ship at scale.
Want to see this pattern in action? Check the Velocity X pricing page — it's built entirely on Tailwind 3, and it still beats v4 sites on Core Web Vitals. And if you're curious about the broader architecture decisions that enable fast iteration, read our AI-Ready Website Architecture guide.