tailwind-v4-config

Tailwind v4 Configuration

These rules apply when editing CSS files, PostCSS config, Vite config, or Tailwind config files. This rule also auto-attaches to tailwind.config.* files - if you see one in a v4 project, it may be a migration artifact that needs conversion to @theme.

The @theme Directive

@theme defines design tokens that generate both CSS variables and utility classes:

@import "tailwindcss";

@theme {
  /* Colors - generates bg-brand, text-brand, border-brand, etc. */
  --color-brand: #ff6a00;
  --color-surface: #0a0a0a;
  --color-surface-raised: #1a1a1a;
  --color-muted: #737373;

  /* Fonts - generates font-sans, font-mono, etc. */
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-mono: "JetBrains Mono", ui-monospace, monospace;

  /* Spacing - generates p-18, m-18, gap-18, etc. */
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;

  /* Border radius - generates rounded-card, etc. */
  --radius-card: 0.75rem;

  /* Shadows - generates shadow-card, etc. */
  --shadow-card: 0 2px 8px rgb(0 0 0 / 0.12);

  /* Breakpoints - generates sm:, md:, etc. */
  --breakpoint-sm: 40rem;
  --breakpoint-md: 48rem;
  --breakpoint-lg: 64rem;
  --breakpoint-xl: 80rem;
  --breakpoint-2xl: 96rem;

  /* Animations */
  --animate-fade-in: fade-in 0.3s ease-out;
}

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

Resetting Default Theme Namespaces

Use initial to clear a namespace before defining your own values:

@theme {
  /* Remove ALL default colors, define only yours */
  --color-*: initial;
  --color-white: #ffffff;
  --color-black: #000000;
  --color-brand: #ff6a00;
  --color-gray-50: #fafafa;
  --color-gray-100: #f5f5f5;
  --color-gray-900: #171717;
}

This is useful for strict brand compliance where default Tailwind colors should not be available.

The @source Directive

Control which files Tailwind scans for class names:

@import "tailwindcss";

/* Include a UI library from node_modules */
@source "../node_modules/@acmecorp/ui-lib";

/* Exclude legacy code from scanning */
@source not "../src/legacy";