Tailwind CSS v4: Theme and Configuration

Understand CSS-first theme customization, custom design tokens, source discovery, and how v3 differs from v4.

CSS-first theme customization

Tailwind CSS v4 emphasizes CSS-first configuration for many common theme customizations. The @theme directive lets you define design tokens that participate in Tailwind's utility and variant system. This is different from many v3 tutorials that put most theme customization in tailwind.config.js.

Use the current official documentation for exact syntax and supported namespaces. Theme tokens should express stable design decisions such as brand colors, font families, spacing, and breakpoints—not every individual component's one-off state.

Illustrative v4 theme tokens

Playground

@import "tailwindcss";

@theme {
  --color-brand-500: #0ea5e9;
  --color-brand-700: #0369a1;
  --font-display: "Inter", ui-sans-serif, system-ui, sans-serif;
  --radius-panel: 1.25rem;
}

💡 This demonstrates the CSS-first token style used in Tailwind v4. Verify token namespaces and generated utility names against the current documentation for your exact version. The font still needs to be loaded or available locally.

Key Takeaways

Tailwind v4 supports CSS-first theme customization.
Define tokens for repeated design decisions.
Confirm token syntax and generated utility names for the installed version.

Tailwind v3 vs. v4 and migration awareness

Tailwind v3 and v4 differ in setup, configuration conventions, CSS entry points, browser requirements, and some migration details. A code sample containing utility classes may look familiar across versions, while installation or theme instructions may not be portable.

When upgrading, read the official upgrade guide, confirm framework and browser support, review custom plugins and configuration, and compare generated CSS. Avoid making several unrelated changes during the migration; isolate setup changes from visual refactoring so regressions are easier to locate.

Upgrade checklist

Setup: Use the matching integration

Update the build plugin and CSS entry point.

Theme: Review tokens and config

Translate custom theme settings deliberately.

Sources: Check file discovery

Ensure application and component files are scanned.

Regression: Test key screens

Compare responsive and interaction states.

Do not mix version instructions

A v3 configuration example may not be the right starting point for a v4 project. Identify the installed version before changing setup.

Source paths and third-party components

Tailwind must discover class candidates in the source files where they appear. Monorepos, shared component packages, generated files, and third-party UI libraries can complicate source detection. If a class is missing only in production or only in a package, inspect the source configuration and build pipeline before adding arbitrary CSS overrides.

For a shared component package, document which source files the consuming app must scan or use the supported source registration mechanism for the installed version. Prefer a reproducible build fix over manually copying generated CSS.

Key Takeaways

Inspect source discovery when utilities are missing from production.
Monorepos and shared packages need deliberate source configuration.
Use the official migration guide for major-version changes.

CSS-first theme customization

Tailwind v3 vs. v4 and migration awareness

Source paths and third-party components

STAY UPDATED WITH BYTES!