Chapter 2: Compatibility

Core Idea

Tailwind CSS v4 is itself a full CSS build tool (powered by Lightning CSS) targeting modern browsers only (Chrome 111+, Safari 16.4+, Firefox 128+, all released ~2023-2024) — it replaces the need for Sass/Less/Stylus, and is best used without CSS Modules or component <style> blocks.

Key Concepts

• Minimum browser versions: Chrome 111, Safari 16.4, Firefox 128. Some utilities/variants use bleeding-edge platform features (field-sizing: content, @starting-style, text-wrap: balance) with narrower support — using them is opt-in, just don't use those specific classes if targeting older browsers.
• "Tailwind is your preprocessor": don't layer Sass/Less/Stylus underneath it — Tailwind already bundles @imports, supports native CSS nesting (flattened via Lightning CSS), and relies on native CSS variables instead of preprocessor variables.
• No loop feature needed: utilities like col-span-2 are generated on demand from usage, not from a predefined loop — you rarely write enough raw CSS in a Tailwind project to need preprocessor loops.
• Color/math functions: prefer the built-in default color palette (light/dark shade pairs, e.g. bg-indigo-500 hover:bg-indigo-600) over Sass darken()/lighten(); use native color-mix() for runtime color adjustment (works even with CSS variables/currentcolor) and native min()/max()/round() instead of preprocessor math.
• CSS Modules — discouraged pairing: works but not recommended. Each module is processed separately by the build tool, so N modules means Tailwind runs N times (slower builds), and each module has no @theme unless explicitly imported.
• @reference: import your global stylesheet as reference (@reference "../app.css";) inside a scoped/module CSS file so @apply can resolve theme variables there; alternatively skip @apply and use var(--color-blue-500) directly, which lets Tailwind skip processing that file entirely (faster build).
• Vue/Svelte/Astro <style> blocks: behave like CSS Modules (separately processed) — same drawbacks and same @reference fix apply; recommended approach is styling in markup with utility classes instead of component-scoped <style>.

Reference Tables

Tool/pattern	Tailwind v4 stance
Sass / Less / Stylus	Not designed to be combined with Tailwind — use Tailwind's own nesting/variables/imports instead
CSS Modules	Compatible but discouraged (per-module processing cost, no shared @theme)
Vue/Svelte/Astro <style>	Same drawbacks as CSS Modules; prefer utility classes in markup
@apply in a scoped file	Needs @reference "<global-css>" to see theme tokens
var(--token) in a scoped file	Works without @reference, and skips Tailwind processing for that file

Key Takeaways

1. Don't stack a CSS preprocessor under Tailwind v4 — its build pipeline (Lightning CSS) already covers nesting, imports, and variables natively.
2. If you must use CSS Modules or framework <style> blocks, add @reference to the global stylesheet wherever you use @apply, or switch to var(--token) to avoid the per-file processing cost altogether.
3. Bleeding-edge utilities are opt-in per class — the framework doesn't block you from using them, and doesn't polyfill them either.

Connects To

• Adding Custom Styles: @theme, @layer, and @apply are documented in depth there; this chapter covers where those mechanisms interact with external tooling.
• Theme: the CSS-variable-based theme system is why Tailwind doesn't need Sass variables or color functions.