skip to content

Tailwind CSS

Utility classes generated on demand from theme variables declared in CSS with @theme, extended by variants and custom utilities. Interviewers ask where styles now live and what the build scans.

on this pageshow

explore

questions

23

In Tailwind CSS v4, what is a theme variable, and how does declaring one in `@theme` differ from declaring a plain `:root` variable?

level: juniorimportance: must knowfreq 26%

answer

  1. configuration lives in the stylesheet
  2. the name's prefix picks a utility family
  3. which declarations create classes
  4. compiled output: :root in the theme layer
  5. only used variables emitted; @theme static

basics

~20 s

A theme variable is a custom property declared inside @theme in Tailwind CSS v4; its namespace, such as --color-* or --font-*, makes Tailwind generate matching utilities. A variable on :root is plain CSS and generates no utility class.

solid answer

~40 s

In Tailwind CSS v4 the theme lives in the stylesheet. Declaring `--color-lotus-500: oklch(0.68 0.14 350)` inside `@theme` does two things: Tailwind emits it as an ordinary custom property in the compiled CSS (on `:root`, inside the `theme` cascade layer), and, because the name sits in the `--color-*` namespace, it makes `bg-lotus-500`, `text-lotus-500`, `border-lotus-500` and the other colour utilities available. The namespace decides the family: `--font-*` drives `font-*`, `--breakpoint-*` drives responsive variants such as `3xl:`. A variable declared on `:root` is just CSS: usable through `var()`, but no class is generated for it, which is the right choice for values that should not become utilities. `@theme` must sit at the top level, not inside a selector or media query.

code

css · 16 lines
css
@import "tailwindcss";

@theme {
  --color-lotus-500: oklch(0.68 0.14 350);
  --font-display: "Fraunces", serif;
  --breakpoint-3xl: 120rem;
}

:root {
  --booking-panel-max: 42rem;
}

.booking-panel {
  max-width: var(--booking-panel-max);
  border-color: var(--color-lotus-500);
}

go deeper

for a junior

Recall that a theme variable is a custom property inside @theme, that its prefix such as --color- or --font- decides which utilities appear, and that a :root variable gets no class.

for a middle

Explain the namespace table, that theme variables compile to custom properties on :root in the theme layer, and that utilities reference them with var() instead of copying values.

for a senior

Show you know the output is pruned to used variables, when @theme static is needed, and why @theme must be top-level, including what to do instead for dark-mode values.

for a principal

Weigh which values deserve to be tokens with utilities and which stay plain custom properties, since every theme variable widens the class vocabulary a whole codebase can use.

## What a theme variable is In Tailwind CSS v4 you configure the framework in CSS, not in a JavaScript file. A **theme variable** is a CSS custom property declared inside the `@theme` directive: ```css @import "tailwindcss"; @theme { --color-lotus-500: oklch(0.68 0.14 350); } ``` Tailwind's documentation calls these the project's design tokens. A theme variable is a custom property and also an instruction to the compiler: "a utility class should exist for this value". After the block above, `bg-lotus-500`, `text-lotus-500` and `fill-lotus-500` exist, and once something uses the token the compiled CSS also contains `--color-lotus-500` as a normal custom property you can reference with `var()`. ## Namespaces decide which utilities exist The part of the name before your own suffix is the **namespace**, and each namespace feeds one or more utility or variant families. A few of the defaults: | Namespace | What it generates | Example | |---|---|---| | `--color-*` | colour utilities | `bg-lotus-500`, `text-lotus-500` | | `--font-*` | font-family utilities | `font-display` | | `--text-*` | font-size utilities | `text-xl` | | `--spacing` | the base unit numeric spacing and sizing utilities multiply | `p-4`, `mt-7` | | `--breakpoint-*` | responsive variants | `3xl:grid-cols-6` | | `--container-*` | container-query variants and size utilities | `@sm:`, `max-w-md` | | `--radius-*` | border-radius utilities | `rounded-sm` | Two consequences follow: - A variable inside `@theme` whose name does not match a namespace is still a custom property that `var()` can read, but no utility appears for it. - Utilities such as `flex` or `pointer-events-none` are static and exist in every project; `bg-red-200` or `shadow-sm` exist only because the default `theme.css` that `@import "tailwindcss"` pulls in declares the matching variables. ## `@theme` versus `:root` Both blocks hold custom properties, and both end up as custom properties in the browser. The difference is what the compiler does with them: - **`@theme`** — the variable becomes a token: utilities (or variants) are generated from it, and it is written to the output. - **`:root`** — the variable is ordinary CSS: Tailwind leaves it alone, and only `var()` can use it. Tailwind's documentation recommends exactly this split: `@theme` for a token that should map to a utility, `:root` for a variable that should not have one, such as a layout measurement used in a single component rule. The special syntax also lets Tailwind enforce a rule: theme variables must be declared at the **top level**, never nested under a selector or a media query. ## What the compiled CSS contains When the stylesheet compiles, the theme variables are written as custom properties on `:root` (the source also adds `:host`, so they reach shadow roots) inside the `theme` cascade layer — the first of the four layers `theme, base, components, utilities` that Tailwind's `index.css` declares. A utility then references the variable rather than copying its value, for example `background-color: var(--color-lotus-500)`. By default **only the variables that are used** are emitted: those a generated utility or your own CSS references, or whose full name appears in a scanned source file. The `static` option (`@theme static { … }`, added in 4.0.5) emits every variable in that block regardless, which matters when code reads a token whose name the scanner cannot see, such as a name assembled at runtime. ## Using theme values outside utilities Because tokens compile to custom properties, the same value is available everywhere: 1. In your own CSS: `border-color: var(--color-lotus-500);` 2. In an inline style or an arbitrary value: `rounded-[calc(var(--radius-xl)-1px)]` 3. From JavaScript: `getComputedStyle(document.documentElement).getPropertyValue("--color-lotus-500")` This replaces v3's `resolveConfig` helper, which v4 removed. ## A worked example A yoga-studio booking app moves its brand into the theme. The stylesheet declares `--color-lotus-500`, `--font-display` and `--breakpoint-3xl` inside `@theme`, and keeps `--booking-panel-max` on `:root` because only one component rule uses it. In the markup, a class card uses: ```html <article class="bg-lotus-500 font-display 3xl:grid-cols-6">…</article> ``` What the build produces: - a `.bg-lotus-500` rule whose value is `var(--color-lotus-500)`; - a `.font-display` rule pointing at `var(--font-display)`; - a `3xl:` rule wrapped in a media query at `120rem`; - `--color-lotus-500` and `--font-display` declared on `:root` in the theme layer, because utilities use them; - `--booking-panel-max` exactly where you wrote it, untouched. If someone writes `bg-booking-panel-max`, nothing is generated, because that name was never a theme variable. That is the practical test of the difference: a theme variable is an entry in the utility vocabulary, while a `:root` variable is a value only `var()` can reach. ## Common mistakes 1. Declaring brand colours on `:root` and then wondering why `bg-lotus-500` produces nothing. 2. Naming a token outside a namespace (`--lotus-500`) and expecting colour utilities. 3. Nesting `@theme` inside `.dark` or a media query to make a dark palette; to change a value in dark mode, redefine the emitted custom property under the dark selector instead. 4. Assuming every default variable ships in the CSS; unused ones are pruned unless `@theme static` is used.

  • A class-booking widget reads `--color-lotus-500` with `getComputedStyle` and gets an empty string. No utility uses the colour. Why?
    Tailwind CSS v4 emits only the theme variables that are used: referenced by a generated utility or your CSS, or whose full name appears in a scanned source file. If the widget assembles the name at runtime, or lives outside the scanned files, the variable is pruned. Declaring the tokens in `@theme static { … }` emits every variable in that block regardless of use.
  • Can you put `@theme` inside a `.dark` selector to give dark mode its own palette?
    No. Theme variables must be declared at the top level, not under a selector or media query. Utilities reference the variable, for example `var(--color-surface)`, so you change the value for dark mode by redefining the emitted custom property under the dark selector, such as `.dark { --color-surface: … }` in your base styles.
  • Why does Tailwind CSS v4 not simply turn every `:root` variable into a utility?
    Because not every variable is a token. Layout measurements, component-local values and values set from JavaScript would flood the utility list. `@theme` makes the intent explicit, lets Tailwind enforce top-level declaration, and keeps plain custom properties as plain CSS.

  • Any CSS variable declared on :root automatically becomes a Tailwind utility.
  • Theme variables exist only at build time and cannot be read with var().
  • Every default theme variable is always written to the compiled CSS.
  • Adding a colour in v4 still requires editing tailwind.config.js.
  • @theme can be nested inside a media query or a .dark selector.
  • A token named --lotus-500 inside @theme produces bg-lotus-500.

Assumes Tailwind CSS v4 (4.3.3 checked); v4 replaced the v3 JavaScript theme config with CSS-first @theme variables.

open as a page

In Tailwind CSS, why does a badge class built as `bg-${status}-600` from an API value render with no background, and how do you fix it?

level: juniorimportance: must knowfreq 30%

basics

~20 s

Tailwind scans source files as plain text and generates CSS only for complete class names it finds. The fragment bg-${status}-600 never appears whole, so no rule is generated; map each status to a full class string such as bg-emerald-600.

open as a page

In Tailwind CSS v4, what does the `@apply` directive do to your CSS rule, and when does reaching for it backfire?

level: juniorimportance: must knowfreq 22%

basics

~20 s

In Tailwind CSS v4, @apply copies the declarations of existing utilities into your own rule at build time. It backfires when it rebuilds semantic classes, hides states from the markup, or lands outside a layer where utilities can no longer override it.

open as a page

In Tailwind CSS, what does a responsive variant such as `md:` mean, and how do you limit a utility to a range of widths?

level: juniorimportance: must knowfreq 30%

basics

~20 s

A breakpoint variant such as md: applies its utility from that breakpoint upward through a min-width media query, so unprefixed classes are the phone styles. Stacking md: with a max-* variant, as in md:max-xl:, limits it to a range.

open as a page

In Tailwind CSS v4, how do you extend, override or completely replace a default theme namespace such as the colour palette or the breakpoints?

level: middleimportance: must knowfreq 19%

basics

~20 s

In Tailwind CSS v4, add a variable to extend a namespace, redeclare a default to override it, set one to initial to remove it, and write --color-: initial (or --: initial for everything) before your values to replace it.

open as a page

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%

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.

open as a page

In Tailwind CSS, how do `group` and `peer` let you style an element from a parent's hover state or a sibling checkbox's checked state?

level: middleimportance: must knowfreq 22%

basics

~20 s

Put the group class on an ancestor and use group-hover: on its descendants; put the peer class on an earlier sibling and use peer-checked: on elements after it. Name them, as group/card or peer/notify, when markers nest or repeat.

open as a page

In Tailwind CSS v4, how do you apply a one-off value the theme lacks: a hex colour, a CSS variable, or an unsupported property?

level: middleimportance: should knowfreq 18%

basics

~10 s

Tailwind CSS v4 accepts arbitrary values in square brackets, such as bg-[#316ff6] or top-[117px]; a CSS variable uses parentheses, bg-(--promo); a property with no utility is written as [mask-type:luminance]. Spaces become underscores.

open as a page

In Tailwind CSS v4, `dark:` utilities follow the OS setting although `<html>` has `class="dark"`; why, and how do you make them follow the class?

level: middleimportance: should knowfreq 15%

basics

~20 s

Tailwind CSS v4's dark variant uses the prefers-color-scheme media query by default, so a dark class does nothing. Override it in CSS with @custom-variant dark (&:where(.dark, .dark *)); a data attribute works the same way.

open as a page

In Tailwind CSS v4, why does a PostCSS config shrink to just @tailwindcss/postcss, and when would you pick another integration instead?

level: middleimportance: should knowfreq 11%

basics

~10 s

Tailwind CSS v4 bundles @import files, adds vendor prefixes and flattens nesting itself, so postcss-import and Autoprefixer are redundant. Use @tailwindcss/vite with Vite, @tailwindcss/webpack (since 4.2) with webpack, and @tailwindcss/cli without a bundler.

open as a page

In Tailwind CSS v4, why do components from a shared UI package installed in node_modules render unstyled, and what fixes it?

level: middleimportance: should knowfreq 14%

basics

~20 s

Tailwind CSS v4's automatic source detection skips node_modules, so classes used only inside an installed package are never generated. Register it with @source "../node_modules/@clinic/ui" in the stylesheet that imports Tailwind; the path is relative to that stylesheet.

open as a page

In Tailwind CSS v4, why does `@apply` fail inside a Vue or Svelte `<style>` block or a CSS Module, and what does `@reference` fix?

level: middleimportance: should knowfreq 12%

basics

~20 s

In Tailwind CSS v4, each component style block and CSS Module is compiled separately, without your main stylesheet's theme, custom utilities or custom variants. @reference loads those definitions for lookup without emitting any CSS; plain var(--color-…) references sidestep it for single values.

open as a page

In Tailwind CSS v4, how do `@container`, `@sm:` and named containers like `@container/main` make a sidebar reflow by its own width instead of the viewport's?

level: middleimportance: should knowfreq 13%

basics

~20 s

In Tailwind CSS v4, the @container class makes an element an inline-size query container, and @sm: on its descendants compiles to @container (width >= 24rem). Naming it @container/main and using @sm/main: targets that container rather than the nearest one.

open as a page

In Tailwind CSS v4, how do the `data-*` and `aria-*` variants style a save button by its `data-state` and an accordion by `aria-expanded`?

level: middleimportance: should knowfreq 14%

basics

~10 s

In Tailwind CSS v4, data-[state=saved]: compiles to a [data-state="saved"] attribute selector and a bare data-saving: checks the attribute is present; aria-expanded: compiles to [aria-expanded="true"]. The script sets the attribute and the styles follow.

open as a page

In Tailwind CSS v4, `@theme { --font-display: var(--font-lora), serif; }` makes `font-display` headings render in the default font, though `<body>` sets `--font-lora`; why, and what fixes it?

level: seniorimportance: should knowfreq 9%

basics

~20 s

Without the inline option, font-display compiles to var(--font-display), and that variable is computed on :root, where --font-lora does not exist yet. @theme inline puts var(--font-lora) into the utility itself, so it resolves on the heading.

open as a page

In Tailwind CSS v4, editors add utility classes to marketing content fetched from a CMS at run time; how do you guarantee those utilities are generated?

level: seniorimportance: should knowfreq 9%

basics

~20 s

Safelist them in the stylesheet with @source inline(), added in Tailwind CSS 4.1, which forces the listed utilities to be generated and brace-expands patterns such as {hover:,}bg-rose-{100,600}. v3's safelist option is not supported in v4.

open as a page

After upgrading a project to Tailwind CSS v4, `md:btn` in markup generates nothing and `@apply btn` fails, though `.btn` still sits in `@layer components` — why, and what are your options?

level: seniorimportance: should knowfreq 6%

basics

~20 s

Tailwind CSS v3 turned classes inside @layer components into utilities, so variants and @apply worked on them. v4 emits native cascade layers and leaves that CSS as ordinary rules, so either register the class with @utility or move its states inside the rule.

open as a page

In Tailwind CSS v4, in which order are stacked variants such as `*:first:font-semibold` applied, and what CSS does a stacked class compile to?

level: seniorimportance: should knowfreq 8%

basics

~20 s

Tailwind CSS v4 applies stacked variants left to right, like nested CSS: the leftmost variant is the outermost condition. v3 read them right to left, so order-sensitive classes such as first:*: had to be reversed to *:first: in v4.

open as a page

In Tailwind CSS v4, what do the `--spacing()` and `--alpha()` functions compile to in your own CSS, and why use them over hard-coded values?

level: middleimportance: nice to knowfreq 4%

basics

~20 s

In Tailwind CSS v4, --spacing(4) compiles to calc(var(--spacing) * 4) and --alpha(var(--color-x) / 50%) to color-mix(in oklab, var(--color-x) 50%, transparent). Both keep hand-written CSS on the theme's scale and palette, so changing a theme variable updates them too.

open as a page

In Tailwind CSS v4, how do you apply a variant such as `dark` or `hover` inside your own CSS rule, and what does it compile to?

level: middleimportance: nice to knowfreq 7%

basics

~20 s

In Tailwind CSS v4, @variant dark { … } inside a rule wraps that block in the variant's condition: by default dark becomes a prefers-color-scheme media query and hover becomes &:hover inside @media (hover: hover). Stacked and comma-separated lists arrived in 4.3.0.

open as a page

In Tailwind CSS v4, why does a card's `hover:` lift never show when tapped on a phone, and what should touch and keyboard users get?

level: middleimportance: nice to knowfreq 10%

basics

~20 s

Tailwind CSS v4 wraps every hover: rule in @media (hover: hover), so it applies only when the primary input device can hover; a phone's touchscreen cannot. Give keyboard users focus-visible: styles and touch users active: feedback.

open as a page

When upgrading a Tailwind CSS v3 project with a `tailwind.config.js` to v4, what happens to the config's theme, and when do you keep the file through `@config`?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

Tailwind CSS v4 no longer detects tailwind.config.js. The upgrade tool converts a simple config to @theme variables; a config with presets, unknown keys or plugins it cannot read is kept and loaded with @config, minus options like safelist and corePlugins.

open as a page

In a Tailwind CSS v4 monorepo built from the repository root, the dashboard's stylesheet carries other apps' utilities and misses a git-ignored CMS export folder; how do you control what it scans?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

Tailwind CSS v4 scans from the build's working directory, so a root build reads every app. Move the base with source("../src") or disable detection with source(none), then add the CMS folder with @source and drop dead folders with @source not.

open as a page