Building on our understanding of Tailwind CSS v4's new architecture, this lesson dives into the practical adaptations required for its core syntax and features. v4 introduces significant changes that streamline development, focusing on a designer-token-first approach.
One of the most impactful shifts is the departure from tailwind.config.js for theme configuration. In v4, your theme is now defined directly within your CSS file using the new @theme directive. This change empowers developers to integrate design tokens seamlessly, as utilities are now generated from your own defined theme tokens, rather than merely overriding Tailwind's defaults. For instance, to define a custom color brand-blue, you'd place it within the @theme block in your CSS. Additionally, arbitrary values now utilize a new bracket syntax. Where you might have used w-[100px] in v3, v4 retains a similar look for consistency but with underlying engine changes, making it more robust. An example: bg-[var(--primary-bg-color)] is now the standard for dynamic CSS variables.
v4 redefines several core utility behaviors. The dark: variant, for example, now defaults to respecting the user's system preference via @media (prefers-color-scheme). If you need to revert to a class-based dark mode (e.g., toggling a dark class on the html element), you can explicitly opt-in using the @custom-variant dark directive within your CSS. Another notable enhancement is the default color palette shift to OKLCH, a modern color space that offers wider gamut and better perceptual uniformity on modern displays. Performance is also dramatically improved; cold-build times for large projects (e.g., 50k lines of code) have reportedly dropped from around 960ms to approximately 100ms. Furthermore, container queries are now a first-class feature, deeply integrated into the framework, enabling truly responsive components.
Mastering these syntactic and functional changes is crucial for a smooth migration. Our next lesson will explore "Strategic Migration and Advanced Plugin Development in Tailwind CSS v4", focusing on migrating complex projects and understanding the new plugin API.