TW4 @property breaks TW3 gradients used in the same page

[sentience]

What version of Tailwind CSS are you using?

v4.1.5 (app) + v3.4.17 (shared UI library)

What build tool (or framework if it abstracts the build tool) are you using?

n/a

What version of Node.js are you using?

v22.14.0

What browser are you using?

Chrome

What operating system are you using?

macOS

Reproduction URL

https://github.com/sentience/tw4-gradient-property-issue

Describe your issue

Tailwind 4 gradient styles present in a page break Tailwind 3 gradient styles present in the same page (such as styles from a component library that has not yet upgraded to Tailwind 4), even when the TW3 styles have their own prefix and are loaded into the components layer.

Tailwind 4 changed the format of background gradient variables such as --tw-gradient-from. In Tailwind 3, these variables contained both a color and a percentage (e.g. #6b7280 var(--tw-gradient-from-position)), whereas in Tailwind 4, the variable with the same name now only contains a color value (e.g. #6b7280). Tailwind 4 also generates @property declarations that restrict these variables so that they are only allowed to contain a color value.

As a result, when a TW3-generated gradient is present in the same page as a TW4-generated gradient, the TW3-generated value for --tw-gradient-from will be discarded by the browser, because the TW4-generated @property declaration says that it's invalid.

A fix for this could be to change the name of the variable in TW4 output (e.g. to --tw-gradient-from-color), so that the @property declarations from TW4 do not interfere with TW3 properties.

[sentience]

I'm currently working around this issue by adding this before Tailwind in my app's stylesheet:

/* Work around https://github.com/tailwindlabs/tailwindcss/issues/17845 */
@property --tw-gradient-from {
  syntax: "*";
  inherits: true;
}
@property --tw-gradient-to {
  syntax: "*";
  inherits: true;
}

This prevents gradient colors from being animated, which is a new ability in TW4.

[philipp-spiess]

Hey! Thanks for the info and the detailed reproduction. I agree this is annoying but changing the variable names because of this or making the colors animatable does seem like a breaking change so we'll be cautious here. We haven't seen a lot of folks that run Tailwind 3 and 4 on the same client page so this hasn't come up before.

If the workaround works for you, I'd suggest to leave this in for now until you migrate everything to v3.

Is there anything that's holding you back from migrating the rest of the site to v3?

[sentience]

Thanks for your review, @philipp-spiess.

I understand that technically renaming those variables would be a breaking change, I wonder if the number of people depending on those variable names might be smaller than the number of people getting bitten by TW3/TW4 interop. I guess we can just wait and see if more people chime in on this issue over time. If not, I agree the work-around is not too bad.

Is there anything that's holding you back from migrating the rest of the site to v3?

The company I work for maintains ~25 related apps, each of which uses some combination of ~10 shared UI packages, most of which are styled with Tailwind (the shared packages using unique prefixes), so getting everything upgraded to Tailwind v4 is going to take some time.

The main friction we're encountering with upgrading everything is unwanted visual changes in our apps. Thank goodness we have good visual regression test coverage; otherwise, TW4 would be impossible for us to adopt.

The visual diffs we're seeing, mostly come down to two causes:

• Subtle implementation changes in TW4 (e.g. divide-y-* using margin-bottom instead of margin-top) behaving differently in edge cases (e.g. when a component affected by divide-y-* was already using margin-bottom).
• Interactions with non-Tailwind styles not in a CSS layer, which now override Tailwind utility styles regardless of their selector specificity or source order. Loading these styles into CSS layers would be the ideal fix, here, but Next.js's lack of support for this is currently making this tricky, and we're exploring several work-arounds such as PostCSS plug-ins like postcss-assign-layer and postcss-wrap-up-layer.