Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Getting Started

How Tailwind CSS Works

See how Tailwind v4 finds class names, generates only the CSS you use, orders utilities with cascade layers and exposes design tokens as CSS variables.

Tailwind can feel like magic: you type bg-sky-500 and a color appears. Understanding the mechanism removes most surprises. Why does a class built from string pieces not work? Why does the order of classes in class="" not matter? Where do the colors come from? This lesson opens the box.

It is a compiler for class names

Tailwind v4 is a build step that does three things:

  1. Scans your source files as plain text and collects every string that looks like a utility class.
  2. Reads your CSS entry file (the one with @import "tailwindcss") including your @theme, @utility and other customizations.
  3. Generates a stylesheet containing only the utilities it found, with the theme values they need.
flowchart LR
  S["Source files<br/>.html .js .php .vue ..."] -->|"scan for tokens"| E["Tailwind engine"]
  C["Your CSS<br/>@import, @theme"] --> E
  E --> O["Generated CSS<br/>(only what you used)"]

Tailwind never executes your code. It only reads it as text.

Because it reads text, a class name must appear complete somewhere in your files. These are all found:

HTML
<div class="bg-sky-500"></div>
JavaScript
const tone = isError ? "text-rose-600" : "text-emerald-600";

But this is not, because the full string bg-red-500 never occurs:

JavaScript
const color = "red";
el.className = `bg-${color}-500`;   // Tailwind sees "bg-" and "-500" only

Fix it by writing the complete names, for example in a lookup object:

JavaScript
const tones = {
  red: "bg-red-500",
  green: "bg-green-500",
};
el.className = tones[color];

The browser build used in this track watches the live DOM instead of your source files, so a dynamically built class does work in the examples here. A real build step (Vite, the CLI, PostCSS) does not, so always write full class names in your code.

Automatic content detection

In v3 you listed template paths in a content array. v4 detects sources automatically. It starts at your project root and:

  • ignores everything listed in .gitignore (so node_modules and build output are skipped),
  • ignores binary files, CSS files and lock files,
  • scans everything else.

If a class lives in a place Tailwind does not look, such as a package inside node_modules or a path you ignored in git, add it explicitly in your CSS with @source:

CSS
@import "tailwindcss";
@source "../node_modules/my-ui-kit/dist";
@source not "../src/legacy";

For classes that never appear in any file (for example ones coming from a database), force them with an inline source. This generates them regardless of whether they are found:

CSS
@source inline("bg-red-500 bg-green-500 bg-blue-500");

What @import "tailwindcss" contains

That single line is shorthand for three layered files. In order, they are:

CSS
@layer theme, base, components, utilities;

@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);
  • theme defines the design tokens: colors, spacing, fonts, breakpoints.
  • base holds Preflight, the reset that normalizes browsers (you met it in Your First Page).
  • utilities is where the generated classes go.

Using cascade layers (@layer) has a useful effect: all utilities sit in the last layer, so they beat your own base styles regardless of selector specificity, and the order of classes within the class attribute never matters. See CSS cascade layers for the underlying feature.

The next TryIt shows two things: the layer order Tailwind emits, and that the two paragraphs end up the same color even though their class order differs.

Layers and class order

Both paragraphs get the same color, because the order in the HTML attribute is irrelevant: the stylesheet decides. The lesson: never rely on two conflicting utilities on one element (text-red-500 text-blue-500). Remove one, or use a variant, for example text-blue-500 hover:text-red-500.

Theme variables

Every design token is a CSS custom property declared in the theme layer. The spacing scale is one base number, --spacing: 0.25rem, and p-4 is simply padding: calc(var(--spacing) * 4). Colors are variables such as --color-sky-500. Tailwind only includes the variables your classes actually use, which keeps the output small.

You can read them in your own CSS or JavaScript, which is handy for animations and charts:

Reading theme variables

The output shows --spacing: 0.25rem and the oklch(...) value for sky. In your own stylesheet you can use them directly: border: 1px solid var(--color-sky-500);. In chapter 6 you will add your own tokens with @theme.

Why v4 is faster

The v4 engine was rewritten (parts are in Rust) and no longer depends on PostCSS for most work. Full builds are several times faster, and incremental rebuilds after an edit finish in microseconds. The practical effect is that you hardly notice Tailwind in your dev loop.

Common mistakes

  • Building class names with string concatenation. Use complete names or a lookup object.
  • Expecting class attribute order to matter. It does not; use variants or conditional logic to avoid conflicts.
  • Missing a source. If a class from a library does not apply, add an @source line for it.
  • Putting generated CSS into git. Treat the output as a build artifact.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does Tailwind find the classes you use?

    Tailwind reads files as text and extracts strings that look like class names, which is why class names must be written out in full.
  2. 2. Why does the code "bg-" + color + "-500" fail in a build?

    The complete token must exist in a scanned file. Use a lookup object with full names, or @source inline() to force classes.
  3. 3. Which directive adds an extra folder to scan, such as a UI kit in node_modules?

    @source points Tailwind at extra paths. It can also exclude paths with @source not.
  4. 4. Why does the order of utilities inside class="" not matter?

    Specificity between utilities is equal; the order in the generated CSS wins. Avoid conflicting utilities on one element.

Summary

  • Tailwind scans your files as text and generates CSS only for the classes it finds.
  • Always write complete class names; use lookup objects for conditional styles.
  • v4 detects sources automatically; @source adds or excludes paths, and @source inline() forces classes.
  • @import "tailwindcss" brings in theme, Preflight and utilities in cascade layers.
  • Design tokens are CSS variables (--spacing, --color-sky-500), emitted only when used.

Next: Spacing: Padding, Margin and Gap