English for Tailwind CSS v4

Tailwind v4 moved configuration out of a JavaScript file and into CSS itself, which changes not just how a project is set up but the vocabulary used to describe it — “theme variables” replace “config object,” and knowing the difference matters when discussing an upgrade or a design-token decision.

Key Vocabulary

CSS-first configuration — the v4 approach of defining theme values directly in a CSS file using @theme, replacing the tailwind.config.js JavaScript object that previous versions required. “We moved our color palette out of tailwind.config.js and into an @theme block in app.css — that’s the CSS-first configuration v4 expects.”

Theme variable — a custom property (like --color-brand-500) defined inside @theme that Tailwind turns into both a utility class and a usable CSS variable, unifying design tokens and utilities into one source. “Since --spacing-18 is a theme variable, p-18 works as a utility class, and we can also reference var(--spacing-18) directly in custom CSS.”

Oxide engine — the new Rust-based build engine in v4, replacing the old PostCSS-based pipeline, responsible for its significantly faster build and rebuild times. “Full rebuilds dropped from around three seconds to under 200ms after the Oxide engine upgrade — worth mentioning in the PR since CI times improved too.”

Container query utility — the built-in @container and @sm:, @md: style variants that let a component’s styling respond to its container’s size rather than only the viewport’s size, no plugin required. “Instead of a viewport-based breakpoint, we used a container query so the card’s layout adapts based on the width of its parent grid cell, not the whole page.”

Automatic content detection — v4’s default behavior of scanning the project for class names without requiring an explicit content array in the config, using .gitignore to skip irrelevant directories. “We removed the manually maintained content glob list entirely — automatic content detection just works now, and it was a common source of ‘missing styles’ bugs before.”

Common Phrases

• “Is this a theme variable defined in @theme, or a one-off arbitrary value?”
• “Are we seeing a build speed difference from the Oxide engine, or is it something else?”
• “Should this be a container query, or does it actually need to respond to the viewport?”
• “Is this class missing from the build because of the content scanning, or a typo in the class name?”
• “Is this config still using the old JS config file, or has it moved to CSS-first?”

Example Sentences

Explaining a migration in a PR: “Migrated the theme to CSS-first config: colors and spacing now live in @theme instead of tailwind.config.js, and we dropped the plugin we were using for container queries since v4 supports them natively.”

Debugging a missing-styles issue: “The class wasn’t being generated because the file lived in a directory excluded by .gitignore, and automatic content detection respects that — we added an explicit content path as an override.”

Discussing a performance win with the team: “Local dev rebuilds are near-instant now that we’re on the Oxide engine — that alone made the v4 upgrade worth scheduling this sprint.”

Professional Tips

• Say theme variable, not “config value,” when discussing v4 — it signals the value is both a CSS custom property and a utility class source, which matters for how it’s referenced elsewhere.
• Attribute build speed improvements to the Oxide engine specifically in reports — it’s a genuinely different engine, not just an incremental tuning change, and worth naming for anyone comparing versions.
• Reach for a container query utility when a component’s layout should depend on its container, not the page — conflating the two in a design discussion leads to responsive bugs.
• When something isn’t generating expected styles, check automatic content detection and .gitignore interaction before assuming a class name typo — it’s a common and non-obvious cause.

Practice Exercise

1. Write a sentence explaining what a theme variable is and how it’s defined.
2. Describe when you’d use a container query instead of a standard responsive breakpoint.
3. Explain automatic content detection in your own words.