[RFC] Opt-in support for @layer to fix Tailwind v4 integration

[siriwatknp]

Motivation

Tailwind integration

The current Material UI v6 is hard to use with CSS utilities like Tailwind CSS because some components have higher CSS specificity than (0,1,0) so Tailwind CSS could not be used without !important.

Also, Tailwind v4 (will be stable soon) is using native CSS layer so Material UI won't be able to override it without a configurable layer.

Here is the issue using Material UI v6 + Tailwind v4 (beta). The text-2xl cannot override the Typography base styles.

✅ Can be fixed by the first solution

Different override behavior when using CSS variables

Another issue is the behavior change when transition from dynamic CSS using theme.palette.mode to CSS variables paradigm (static CSS). The sx prop cannot override the :where() because Emotion always append :where() at the end of the styles.

✅ Can be fixed by combining first and second solution

Requirements

• Opt-in solution
• Least breaking changes
• Small change for the codebase

Options

1. A custom stylis plugin for single layer

Based on this solution, this will capture emotion styles into a single layer, likely named @layer mui.

I think this is a simplest solution that works really well. It will fix the Tailwind v4 integration but it won't fix the "Different override behavior when using CSS variables" because all Material UI styles are in the same layer.

2. Add flag to the theme for multiple layers

To solve "Different override behavior when using CSS variables", the sx styles must be in a different layer so that it overrides the styles of the component regardless of selector's specificity.

@layer mui, sx

@layer sx {
  .button {
    color: blue; // this wins
  }
}

@layer mui {
  .button {
    color: red;
  };
  :where(.dark) .button {
    color: white;
  }
}

A custom stylis plugin (option 1) is not possible to support multiple layers, so the layer has to be created from the styleFunctionSx.

diff --git a/packages/mui-system/src/styleFunctionSx/styleFunctionSx.js b/packages/mui-system/src/styleFunctionSx/styleFunctionSx.js
index a74b44b553..08362c997f 100644
--- a/packages/mui-system/src/styleFunctionSx/styleFunctionSx.js
+++ b/packages/mui-system/src/styleFunctionSx/styleFunctionSx.js
@@ -131,7 +131,11 @@ export function unstable_createStyleFunctionSx() {
       return sortContainerQueries(theme, removeUnusedBreakpoints(breakpointsKeys, css));
     }
 
-    return Array.isArray(sx) ? sx.map(traverse) : traverse(sx);
+    const array = Array.isArray(sx) ? sx : [sx];
+    return array.map((item) => {
+      const result = traverse(item);
+      return theme.cssLayer ? { [`@layer sx`]: result } : result;
+    });
   }
 
   return styleFunctionSx;

Feel free to share other possible options that we could do.

Search keywords:

[DiegoAndai]

I agree with this to fix the integration with Tailwind v4, keeping in mind the requirements:

• Opt-in solution
• Least breaking changes
• Small change for the codebase