Prefix does not work with custom layer

[radubrehar]

What version of Tailwind CSS are you using?

4.1.16

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

@tailwindcss/vite - 4.1.16
vite 7.1.7

What version of Node.js are you using?

v22.21.0

What browser are you using?

N/A

What operating system are you using?

N/A

Reproduction URL

radubrehar/tailwind-test#1

Describe your issue

Simply adding a custom CSS layer to a tailwind import with prefix makes the prefix not work.

I need a custom CSS tailwind build, without the prefix. Therefore, I use only the theme and utilities from tailwind, without the prefix. So my tailwind imports look like this

@import "tailwindcss/theme.css" prefix(twa);
@import "tailwindcss/utilities.css" prefix(twa);

As soon as I add the layer directive to the import, it fails:

@import "tailwindcss/theme.css" prefix(twa) layer(custom);
@import "tailwindcss/utilities.css" prefix(twa)  layer(custom);

In fact, it proves that even with a default tailwind, the prefix and layer combination doesn't work

@import "tailwindcss" prefix(twa) layer(custom);

[wongjn]

As per the documentation, the prefix() should come after layer():

--- a/src/style.css
+++ b/src/style.css
@@ -1,4 +1,4 @@
-@import "tailwindcss/theme.css" prefix(twa) source(none) layer(custom);
-@import "tailwindcss/utilities.css" prefix(twa) source(none) layer(custom);
+@import "tailwindcss/theme.css" layer(custom) prefix(twa) source(none);
+@import "tailwindcss/utilities.css" layer(custom) prefix(twa) source(none);
 
 @source './';

You'd also need a @layer rule before as well, like:

+@layer foo, bar, custom, baz;
+
 @import "tailwindcss/theme.css" layer(custom) prefix(twa) source(none);
 @import "tailwindcss/utilities.css" layer(custom) prefix(twa) source(none);

[radubrehar]

sure, the @layer at the top needs to be there, I just wanted a minimal repro, with everything else away from sight.

Your suggestion of order seems to make it work, thank you!

But I don't clearly see it stated in docs that layer should come before prefix.

The most natural assumption is that the order of all those modifiers (layer, prefix, source) used on an @import should not matter.

[wongjn]

You can submit a PR at https://github.com/tailwindlabs/tailwindcss.com to improve the docs in this area if you so wish.

[radubrehar]

Sure, I can do that, but I think the correct approach approach is to make the order not important.

[RobinMalfait]

While we could make that work, it would be invalid CSS because the layer(…) has to come first from a CSS spec perspective and that's something we don't want to do. https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@import#formal_syntax

[radubrehar]

Thank you @RobinMalfait, I wasn't aware of this. In this case I'll send a PR to update the docs to clearly state that layer should come before prefix.