In what layer I should put regular CSS variables?

[subproject22]

Docs says

Why @theme instead of :root?
Theme variables aren't just CSS variables — they also instruct Tailwind to create new utility classes that you can use in your HTML.

Since they do more than regular CSS variables, Tailwind uses special syntax so that defining theme variables is always explicit. Theme variables are also required to be defined top-level and not nested under other selectors or media queries, and using a special syntax makes it possible to enforce that.

Defining regular CSS variables with :root can still be useful in Tailwind projects when you want to define a variable that isn't meant to be connected to a utility class. Use @theme when you want a design token to map directly to a utility class, and use :root for defining regular CSS variables that shouldn't have corresponding utility classes.

Cool, but it doesn't mention where it's better to put :root variables now in Tw 4? Should I put it in @layer theme? OR @layer base? What's the difference between them, beside order? Or maybe no layer at all? Hell, it even works if I put custom variables in @theme directly. Any guides please?

[adamwathan]

I would put them in @layer theme { ... } but you're right there's unlikely to ever be a functional difference in a real project. But that's my recommendation just to have one less thing to think about 👍

[spacecat]

I would put them in @layer theme { ... } but you're right there's unlikely to ever be a functional difference in a real project. But that's my recommendation just to have one less thing to think about 👍

I'm not sure I'm following.

There's a @theme directive but you're mentioning @layer theme in your answer.

I haven't seen any examples with @layer theme in the v4 docs. I've only seen @layer base.

So was @layer theme a typo?

And is theme both a directive and a layer?

I'm so confused.

[wongjn]

@theme registers theme tokens into the Tailwind engine, for utilities to use. @layer theme is for placing rules in the CSS cascade layer named theme. Tailwind internally uses the theme layer for its output of theme token CSS variables, thus it makes sense for other CSS variables to go in there too.