@layer Is Native CSS, Not a Tailwind Directive
MUST: Use @layer (base/components/utilities) for custom CSS to integrate with Tailwind specificity
Use @layer base for element defaults, but never define a utility inside @layer utilities — that no longer produces a real utility
Bad
Good
Why it matters
The three-layer habit from v3 — `@layer base`, `@layer components`, `@layer utilities` — reads identically in v4 but means something else. Tailwind no longer intercepts these blocks; they are the browser's own cascade layers (`@layer` is real CSS now, and Tailwind registers `theme`, `base`, `components`, and `utilities` as native layers). One of the three still works exactly as you expect: `@layer base { h1 { ... } }` for element defaults and resets is correct v4.
The other two changed. A class you write inside `@layer utilities` is no longer registered as a Tailwind utility — it is just a rule that happens to sit in a low-priority layer. So `hover:` and `md:` cannot be applied to it (the compiler has never heard of the name and will not generate the variant), and it has no place in Tailwind's property-count sort order, so its precedence against real utilities is whatever the layer position gives it.
It looks like a utility, it is styled like a utility, and it fails the moment anyone tries to use it like a utility. The v4 answer is `@utility`, which registers the name with the compiler. See layout-custom-utilities.