Documentation issue - deprecated class missing in upgrade guide

[matt17r]

This is minor (and I'm a bit of an edge case upgrading manually) but hopefully it's quick and easy to add another class or two to the upgrade guide to save others some time.

What component (if applicable)

• URL for category: https://tailwindcss.com/docs/upgrade-guide
• Component name: Docs

Describe the bug
The list of deprecated classes in the v4 upgrade guide doesn't mention a class that was previously used in Tailwind UI Plus themes. Specifically:

-         <div class="absolute -right-60 -top-44 h-60 w-[36rem] transform-gpu md:right-0 bg-[linear-gradient(115deg,var(--tw-gradient-stops))] from-[#9DA39A] from-[28%] via-[#B98389] via-[40%] to-[#DB2955] rotate-[-10deg] rounded-full blur-3xl"></div>
+         <div class="absolute -right-60 -top-44 h-60 w-[36rem] transform-gpu md:right-0 bg-linear-115 from-[#9DA39A] from-28% via-[#B98389] via-40% to-[#DB2955] rotate-[-10deg] rounded-full blur-3xl"></div>

To Reproduce

1. Use Radiant theme for Tailwind v3 (using tailwindcss-rails gem and importmaps... no JS tooling such as npm or yarn)
2. Upgrade to Tailwind 4 (without upgrade tooling)
3. Search and replace codebase for deprecated class changes
4. Theme remains broken

It's possible this would have been avoided by using the upgrade tooling but I wanted to see if I could upgrade to v4 without installing npm or yarn.

Expected behavior
Docs should mention that bg-[linear-gradient(115deg,var(--tw-gradient-stops))] has been deprecated (especially since it was used in an "official" theme)

Screenshots
N/A

Browser/Device (if applicable)
N/A

Additional context
N/A

[reinink]

Hey @matt17r, sorry you bumped into this.

I actually remember writing that class (bg-[linear-gradient(115deg,var(--tw-gradient-stops))]) when originally building Radiant. Fun fact, we originally built Radiant using the Tailwind CSS v4-beta, but downgraded it to v3 before releasing it, because v4 wasn't quite ready yet, and we wanted to get that template launched.

While doing that downgrade, I realized I didn't have a nice way to express the gradient using the utilities available in v3, so I did something we generally discourage and reached for an internal Tailwind CSS variable (--tw-gradient-stops) to make it work. In hindsight, that wasn’t the best move, and I should have just implemented the whole gradient as an arbitrary value.

Given that these Tailwind CSS variables are sort of considered internal/private APIs—as in they are not variables end users are intended to interact with—and since we've never encouraged doing this kind of thing (other than inadvertently suggesting it's okay to do so by doing it in one of our templates—guilty! 🙋‍♂️), I'n not sure it makes sense to include this in the v4 upgrade guide.

Thanks either way for sharing this feedback, and my apologies again that you bumped into this.

[matt17r]

Thanks for the background! Like I said, I’m likely an edge case and, while I had no idea why it wasn’t working, I just looked at the v4 Radiant theme to find the updated classes.

If anyone else bumps into, it they’ve now got the updated theme and your response here to help guide them 👍