Tailwind v4

Rule

Configuration

  • MUSTUse config-free setup only; do not add tailwind.config.* files.
  • MUSTUse PostCSS with @tailwindcss/postcss plugin.
  • MUSTConfigure source paths with @source directives in CSS.
  • MUSTApp imports Tailwind CSS once (e.g., in globals.css).

Source Paths

  • MUST@source globs cover every directory where class names appear.
  • NEVERSafelist classes — fix @source or token mapping instead.
@import "tailwindcss";
@source "../**/*.{ts,tsx}";

For monorepos, add @source entries for shared UI packages and app sources.

Theme Tokens

  • MUSTMap CSS variables to Tailwind tokens via @theme so utilities like bg-primary work.
  • MUSTToken mappings cover the utilities your components use.
@theme {
  --color-primary: hsl(var(--primary));
  --color-primary-foreground: hsl(var(--primary-foreground));
}

Gray Palette

  • MUSTPick one neutral palette (e.g., gray, zinc, slate) and use it consistently.
  • NEVERMix multiple neutral palettes in the same project.

Utilities

  • MUSTUse cn utility (clsx + tailwind-merge) for conditional class logic.
  • MUSTUse cva (class-variance-authority) for component variants.
  • SHOULDUse size-* for square elements instead of w-* h-*.
  • NEVERRely on important hacks.