skip to content

In Tailwind CSS v4, which cascade layers does `@import "tailwindcss"` set up, and where should your own base styles and component classes go?

level: middleimportance: must knowfreq 16%

answer

  1. four layers, fixed order
  2. the reset sits in one of them
  3. components below utilities
  4. element defaults beside Preflight
  5. unlayered rules outrank all four

basics

~20 s

Tailwind CSS v4 declares four native cascade layers in the order theme, base, components, utilities. Element defaults go in @layer base, on top of Preflight; reusable classes such as .btn go in @layer components, so a utility on the same element still overrides them.

solid answer

~40 s

`@import "tailwindcss"` starts with `@layer theme, base, components, utilities;` and imports the theme variables into `theme`, Preflight into `base` and the generated utilities into `utilities`. Because these are native cascade layers, a rule in a later layer beats one in an earlier layer whatever their specificity. So element defaults — heading sizes and link colours for CMS-rendered articles — go in `@layer base`, after Preflight, and a component class like `.btn` goes in `@layer components`, where `class="btn bg-red-700"` still lets the utility win. CSS left outside any layer beats all four, which is how a stray rule ends up silently overriding utilities. And unlike v3, v4 no longer treats classes in `@layer components` as utilities, so they do not take variants such as `md:`.

code

css · 14 lines
css
@import "tailwindcss";

@layer base {
  h2 { font-size: var(--text-xl); }
  a { color: var(--color-civic-700); }
}

@layer components {
  .btn {
    border-radius: var(--radius-md);
    background-color: var(--color-civic-600);
    padding-inline: --spacing(4);
  }
}

go deeper

for a junior

Recall the four layer names in order and that @import "tailwindcss" declares them. Know that a .btn class goes in @layer components and element defaults go in @layer base.

for a middle

Explain why a utility beats a component class regardless of specificity, where your base rules land relative to Preflight, and why CSS outside any layer wins over all four layers.

for a senior

Diagnose a utility that silently does nothing by finding the unlayered or wrongly layered rule, and explain why classes in @layer components stopped taking variants after a v3 upgrade.

for a principal

Set the convention for where hand-written CSS may live in a utility-first codebase, so no stray unlayered rule overrides utilities, and decide when a shared class belongs in components rather than registered as a utility.

## What `@import "tailwindcss"` sets up In **Tailwind CSS v4** the single line `@import "tailwindcss";` pulls in the framework's own entry stylesheet, and its first statement declares four **native cascade layers** in a fixed order: ```css @layer theme, base, components, utilities; @import './theme.css' layer(theme); @import './preflight.css' layer(base); @import './utilities.css' layer(utilities); ``` These are real CSS `@layer` blocks, not a Tailwind-only convention. The browser ranks them in the declared order, so for normal declarations a rule in a later layer beats a rule in an earlier one whatever the selectors' specificity. How the cascade orders layers in general is a CSS topic of its own; here only the consequence matters. | Layer | What Tailwind puts there | What you add there | |---|---|---| | `theme` | the theme variables, as custom properties on `:root, :host` | nothing by hand — theme variables are defined with `@theme` | | `base` | **Preflight**, Tailwind's element reset | element defaults: headings, links, form controls | | `components` | nothing from the framework's own stylesheet | reusable classes such as `.btn`, overrides for third-party widgets | | `utilities` | every utility generated from your markup | custom utilities, which are registered with `@utility` | ## Base styles: `@layer base` The documentation's first suggestion for page-wide defaults is to put utilities on `<html>` or `<body>`. When you need element defaults — say, headings and links inside CMS-rendered permit articles that arrive as raw HTML — write them in the base layer: ```css @layer base { h2 { font-size: var(--text-xl); } a { color: var(--color-civic-700); } } ``` - Your block joins the same `base` layer as Preflight and comes later in the stylesheet, so at equal specificity your rule wins over the reset. - It still sits **below** `components` and `utilities`, so `class="text-sm"` on one heading overrides the default. - Reading theme values with `var(--text-xl)` keeps the defaults on the same scale as the utilities. ## Component classes: `@layer components` The portal's CMS can only emit a class name, so the button style must exist as `.btn`. Put it in the components layer: ```css @layer components { .btn { border-radius: var(--radius-md); background-color: var(--color-civic-600); padding-inline: --spacing(4); } } ``` Because `utilities` comes after `components`, `<a class="btn bg-red-700">` renders red: the utility wins even though both selectors are a single class and `.btn` may be written later in your files. The documentation also names the components layer as the place for overriding a third-party widget's own classes, for the same reason — a utility can still adjust the widget afterwards. A few practical rules for that layer: - A component class may nest its own states, such as `&:hover` inside `@media (hover: hover)`, the same condition the `hover:` prefix uses in v4. - Keep each class to one element; anything with structure is better as a template partial or framework component, as the documentation advises. - Read every value from a theme variable or `--spacing()`, so a palette or scale change reaches the class too. - The documentation's own warning applies: in a utility-first codebase you usually need fewer of these classes than you expect. ## The unlayered trap CSS written below `@import "tailwindcss"` but outside any `@layer` is **unlayered**, and unlayered normal declarations outrank every layer. A `.btn` written that way silently defeats every utility placed beside it. When a utility "does nothing", work through it in this order: 1. Find the competing rule in the browser's style inspector and note which layer, if any, it belongs to. 2. If it is unlayered, wrap it in `@layer components` (or `@layer base` for element selectors). 3. If it is in `utilities`, compare the two utilities — conflicts there follow their order in the generated stylesheet, not their order in the class attribute. 4. Only then reach for the important modifier (`bg-red-700!`), and treat needing it as a smell. ## What changed from v3 - v3 used `@tailwind base; @tailwind components; @tailwind utilities;`. v4 removed those directives; `@import "tailwindcss"` replaces them. - v3 intercepted `@layer components` and `@layer utilities` and turned the classes inside into utilities that accepted variants and `@apply`. v4 emits native layers and no longer hijacks the at-rule, so `.btn` above is ordinary CSS: `md:btn` generates nothing and `@apply btn` fails. A class that must behave like a utility is registered with `@utility` instead. - Because the layers are native, the browser decides between layered rules by layer position, not by where a rule happens to sit in the file — only an unlayered rule escapes that ordering.

  • In a Tailwind CSS v4 project, why does a `.btn` rule written after `@import "tailwindcss"` but outside any `@layer` beat `bg-red-700` on the same element?
    Unlayered normal declarations outrank every cascade layer, and all of Tailwind's utilities live in the `utilities` layer, so specificity and class order are never consulted. Wrapping the rule in `@layer components` puts it below `utilities` and the utility wins again. The important modifier would also work, but it hides the real problem.
  • Where do Tailwind CSS v4's theme variables end up in the output, and can hand-written CSS use them?
    They are emitted in the `theme` layer as custom properties on `:root, :host`, so any rule on the page — layered or not — can read them with `var(--color-civic-600)` or `var(--text-xl)`. That is how base styles and component classes stay on the same scale as the utilities; which variables get emitted is a theme setting.
  • In a Tailwind CSS v4 project, where should overrides for a third-party autocomplete dropdown's own class names go, and why?
    In `@layer components`. The documentation names it as the place for third-party component styles: the overrides beat Preflight and anything in `base`, while a utility added to the widget's element can still adjust them. Left unlayered, they would also beat every utility, which is rarely what you want.

  • Tailwind v4 still needs @tailwind base, components and utilities at the top of the file
  • A component selector with higher specificity will beat a utility class on the same element
  • Custom CSS outside any layer is placed below Tailwind's utilities
  • A class inside @layer components works with hover: and md: prefixes in v4
  • Element defaults belong in @layer utilities so they reliably apply

Assumes Tailwind CSS v4 (checked against 4.3.3); v4 emits native cascade layers and replaced v3's @tailwind directives and its build-time handling of @layer.