Tailwind CSS v4.1 Core

Documentation

• CSS theme variables, design tokens, customization -> tailwindcss-core
• Directives (@utility, @variant, @theme, @apply) -> tailwindcss-core
• Custom utilities and variants -> tailwindcss-custom-styles
• Content detection (@source scanning) -> tailwindcss-core
• Migration from v3 to v4 -> see "v3 → v4 Breaking Changes" section below

Quick Reference - @theme Namespaces

Namespace	Generated Utilities
--color-*	bg-, text-, border-, fill-
--font-*	font-*
--text-*	text-xs, text-sm, text-base, etc.
--spacing-*	p-, m-, gap-, w-, h-*
--radius-*	rounded-*
--shadow-*	shadow-*
--breakpoint-*	sm:, md:, lg:, xl:
--animate-*	animate-spin, animate-bounce, etc.
--ease-*	ease-in, ease-out, ease-in-out

v3 → v4 Breaking Changes

Removed @tailwind directives

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

Renamed utilities

v3	v4
shadow-sm	shadow-xs
shadow	shadow-sm
rounded-sm	rounded-xs
rounded	rounded-sm
outline-none	outline-hidden
ring	ring-3

Removed deprecated utilities

• bg-opacity-* → use bg-black/50
• text-opacity-* → use text-black/50
• flex-shrink-* → use shrink-*
• flex-grow-* → use grow-*

Custom utilities syntax

/* v3 */
@layer utilities {
  .tab-4 {
    tab-size: 4;
  }
}

/* v4 */
@utility tab-4 {
  tab-size: 4;
}

Variables in arbitrary values

<!-- v3 -->
<div class="bg-[--brand-color]"></div>

<!-- v4 -->
<div class="bg-(--brand-color)"></div>

Important modifier position

<!-- v3 -->
<div class="!bg-red-500">

<!-- v4 -->
<div class="bg-red-500!">

Upgrade Tool

npx @tailwindcss/upgrade

Requires Node.js 20+

Detailed References

• configuration.md - Load when writing CSS-first @theme config or using @utility/@variant/@custom-variant directives
• api-functions.md - Load when using the --alpha()/--spacing() CSS functions or @apply
• installation-support.md - Load when installing Tailwind v4 (npm/Vite/CLI) or checking browser support