Add support for important in v4

[thecrypticace]

This PR allows modifying utility output by wrapping all utility declarations in a custom selector or marking all utility declarations as !important. This is the v4 equivalent to the important option in the tailwind.config.js file.

Mark all utility declarations as !important

To add !important to all utility declarations, you add an important flag after the @import statement for tailwindcss or tailwindcss/utilities:

/** Importing `tailwindcss` */
@import "tailwindcss" important;

/** Importing the utilities directly */
@import "tailwindcss/utilities" important;

Example utility output:

.mx-auto {
  margin-left: auto !important;
  margin-right: auto !important;
}

.text-center {
  text-align: center !important;
}

This is equivalent to adding important: true to the tailwind.config.js file — which is still supported for backwards compatibility.

Wrap all utility declarations in a custom selector

For backwards compatibility, if you need to nest all utilities in an #app selector you add important: "#app" to your config file:

export default {
  important: "#app",
  // …
}

This does not bring back support for the respectImportant flag in addUtilities / matchUtilities.

[philipp-spiess]

This all seems easy enough, just one question inline. Happy to stamp it but I feel like this could benefit from someone else's 👀 too!

[thecrypticace]

Recording decisions from our call:

• Eliminate the selector(#app) feature from the utilities import because we can't quite decide on the best naming or implementation for that API. A native CSS version will eventually be available called scope(…) anyway which would be a far better solution for end users.
• We'll require users to wrap manually @tailwind utilities with a selector
• We don't care of intellisense does not show the wrapping selector
• Backwards compat will look for the @tailwind utilities node in the AST and
  wrap it with #app selector

[benface]

@thecrypticace & @RobinMalfait – I'm surprised you decided to keep supporting this "selector prefix" API in v4, given that no amount of specificity can make a rule in a cascade layer "escape" its layer, i.e. no utility in @layer utilities could ever beat a conflicting rule that is unlayered or in a latter layer (except with !important). So is the use case for this simply to "scope" Tailwind to a particular node?

[thecrypticace]

@benface Yeah so we ended up doing it only for backwards compatibility purposes to hopefully be less breaking for the projects that are still using this feature. Ideally though users would switch entirely to relying on cascade layers and remove this from their projects.

[benface]

Ideally though users would switch entirely to relying on cascade layers and remove this from their projects.

Well, they have to, as there's no way in Tailwind 4 to render utilities outside the utilities layer, right? Nor do I think there should be... but I would love more control over sub-layers, to make some utilities more (or less) "important" than others.

[thecrypticace]

You definitely can. You just have to inline the imports. We rely on CSS's native layer features including layer(…) on @import so to drop the layers entirely you can write this:

@import "tailwindcss/theme";
@import "tailwindcss/preflight";
@import "tailwindcss/utiltiies";

To keep the layers you do this (this is almost exactly what is in index.css):

@layer theme, base, components, utilities;

@import 'tailwindcss/theme' layer(theme);
@import 'tailwindcss/preflight' layer(base);
@import 'tailwindcss/utilities' layer(utilities);