Tailwind CSS v4 Configuration

Goal

Use Tailwind v4's CSS-first configuration. Keep JavaScript config only when project tooling requires it.

Rules

• Import Tailwind with @import "tailwindcss";.
• Define theme tokens with @theme.
• Rely on automatic content detection by default.
• Use @source only for missed files or external packages.
• Use CSS custom properties for theme values.
• Check browser support before using v4 in legacy environments.
• Do not copy v3 content config unless needed.
• Do not use old @tailwind base/components/utilities in v4 setup.

Pattern

@import "tailwindcss";

@theme {
  --color-brand-primary: oklch(0.65 0.24 354.31);
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 1920px;
}

Key Changes

• CSS-first config.
• Single import.
• Automatic content detection.
• Native cascade layers.
• Theme values as CSS variables.
• Modern browser baseline.

Utility Changes

• shadow-sm (v3) → shadow-xs (v4)
• rounded-sm (v3) → rounded-xs (v4)
• bg-gradient-to-r (v3) → bg-linear-to-r (v4)

Flow

1. Identify project framework and build tool.
2. Check existing Tailwind version.
3. Add v4 package and integration.
4. Create or update main CSS entry.
5. Move tokens into @theme.
6. Add @source only when detection misses files.
7. Run build and visual check.

Browser Compatibility

• Chrome/Edge 111+
• Firefox 128+
• Safari 16.4+

References

• context/setup-examples.md: installation and CSS config.
• context/migration-guide.md: v3 to v4 migration.
• context/framework-examples.md: framework setup.
• context/advanced-config.md: advanced config.
• Tailwind CSS v4 Documentation
• Tailwind CSS v4 Upgrade Guide
• Automatic Upgrade Tool

Output

• Install or migration steps.
• Main CSS config.
• Build tool change.
• Verification command.