feat: revert project to Tailwind 3 for improved browser support

[hunterbecton]

What/Why?

• reverts project to Tailwind 3 for improved browser support
• adds polyfills using postcss-preset-env and postcss-aspect-ratio-polyfill PostCSS plugins
• adds container-query polyfill that conditionally renders on unsupported browsers

Testing

The tests below were on Safari 14.1.

Catalyst on Tailwind 4:

Screen.Recording.Apr.6.2025.2.PM.mp4

Catalyst on Tailwind 3 (no polyfills):

Screen.Recording.Apr.6.2025.14-25.mp4

Catalyst on Tailwind 3 (with polyfills):

Screen.Recording.Apr.6.2025.4.41.PM.mp4

[changeset-bot]

⚠️ No Changeset found

Latest commit: bc86be4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
catalyst-canary	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 5, 2025 6:10pm

3 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
catalyst	⬜️ Ignored (Inspect)			Jun 5, 2025 6:10pm
catalyst-au	⬜️ Ignored (Inspect)	Visit Preview		Jun 5, 2025 6:10pm
catalyst-uk	⬜️ Ignored (Inspect)	Visit Preview		Jun 5, 2025 6:10pm

[chanceaclark]

Looks good besides some rng changes.

[slimboyfats]

Why did you do this PR? Seems like a quick fix variant instead of fixing the actual issues?
We are going to have to update to Tailwind 4 sooner than later, (as the original PR) so this is just a quick fix and results into doing the exact same thing again in a couple of weeks?

[migueloller]

Why did you do this PR? Seems like a quick fix variant instead of fixing the actual issues? We are going to have to update to Tailwind 4 sooner than later, (as the original PR) so this is just a quick fix and results into doing the exact same thing again in a couple of weeks?

@slimboyfats, we tried very hard to get Tailwind 4 working with Catalyst in such a way that it wouldn't negatively impact browser support and were unsuccessful. We looked at polyfills, PostCSS plugins, and more and given that Tailwind 4 has made the decision to compile down to CSS that is only supported by modern browsers, it was not possible to get something workable without an impact to the site's performance.

While we want to use the best tools that are available when possible, we can't just adopt the latest and the greatest without considering the impact it will have to Catalyst and its users. Specifically, less than 2% of browsers used is not acceptable as that is a meaningful amount of revenue when it comes to ecommerce traffic. We had customers using Catalyst that reported the Tailwind 4 upgrade would have a meaningful impact on their top-line if they pulled in those changes.

After evaluating all of our options, we decided that this would be the best way to move forward. If you want to move your Catalyst fork to Tailwind 4, you're welcome to do so. Also, if you have any thoughts or alternatives as to how we could approach this, we're all ears!

[slimboyfats]

Thanks for the answer, so in that case i guess the decision is made to not update to tailwind 4 until Safari 14.1 falls below the threshold if I understand you correct?

What was the biggest things that Safari didn't support in Tailwind 3 vs 4? Would be a good thing to read up for me and see the biggest issues with the upgrade.

[hunterbecton]

Thanks for the answer, so in that case i guess the decision is made to not update to tailwind 4 until Safari 14.1 falls below the threshold if I understand you correct?

Yes, we won't support Tailwind until Safari falls below the threshold, or when Tailwind better supports older browsers. Tailwind moved to Lightning CSS in Tailwind 4, which has options for improving browser support compatibility, but Tailwind doesn't expose any of those options in its configuration.

What was the biggest things that Safari didn't support in Tailwind 3 vs 4? Would be a good thing to read up for me and see the biggest issues with the upgrade.

Tailwind covers some of the new features supported by Tailwind 4 in its upgrade guide. I'd suggest you read through this to get an idea of what's changed, and you'll want to follow along if you're upgrading your project to Tailwind 4.

There are still features in Tailwind 3 that might not be supported in the browsers you want to support. I don't know of a comprehensive list that lays out Tailwind classes to browser support, but a resource I like to use is the Can I use Browser Comparison tool. In this link, you can see all the supported CSS features in any specific browser. Another option is to use the same website for a specific feature and check browser compatibility across multiple browsers. For example, here's browser support for container queries.

It's also worth noting that Tailwind generates and optimizes the CSS; we have little control over that outside of what version we're using. In the PR video, you can see the drastic difference between what Tailwind 3 vs Tailwind 4 browser support looks like with zero polyfills. So even though we're still using polyfills to support features like container queries, color-mix, and more, Tailwind 3 gives us a way better starting point to support those features than Tailwind 4.

One last thing is that there's not an easy way to downgrade from Tailwind 4 to Tailwind 3, but upgrading is much easier with the Tailwind 4 upgrade guide and upgrade tool. This is a better customer experience because customers who want to move to Tailwind 4 have the resources to do so much more easily than customers needing to downgrade to Tailwind 3.