Tailwind CSS v4 Best Practices

Team standard for styling with Tailwind CSS v4 — CSS-first config, design tokens via CSS variables, class-based dark mode.

No Hardcoded Colors (MANDATORY)

Never use raw color values in components. All colors must come from the design token system defined in globals.css.

// BAD: Hardcoded colors
<div className="bg-blue-500 text-white border-gray-200" />
<div className="bg-[#1a73e8] text-[#ffffff]" />

// GOOD: Semantic token colors
<div className="bg-primary text-primary-foreground border-border" />

Before writing any styles: Confirm the color theme with the user. Register all colors in globals.css as CSS variables, then use them everywhere.

No Arbitrary Brackets (MANDATORY)

Tailwind v4 dynamically generates values — stop using [brackets] for things Tailwind already supports natively.

// BAD: Arbitrary brackets
<div className="w-[400px] h-[200px] p-[32px] z-[999] bg-primary/[0.08]" />

// GOOD: Native Tailwind v4 values
<div className="w-100 h-50 p-8 z-999 bg-primary/8" />

How it works in v4:

Type	Formula	Example
Spacing (w, h, p, m, gap...)	`value × 4px`	`w-100` = 400px, `p-8` = 32px, `w-2500` = 10000px
Opacity	Integer = percent	`bg-primary/4` = 4% opacity, `bg-primary/80` = 80%
Z-index	Any integer	`z-999`, `z-6969` — no brackets needed

Rule: Only use [brackets] when there is truly no Tailwind equivalent (e.g., grid-cols-[1fr_2fr]).

Gradients — Use v4 Syntax (MANDATORY)

Tailwind v4 renamed gradients and added radial/conic support. Stop using v3 bg-gradient-to-*.

// BAD: v3 syntax (no longer valid)
<div className="bg-gradient-to-r from-primary to-secondary" />

// GOOD: v4 syntax
<div className="bg-linear-to-r from-primary to-secondary" />
<div className="bg-linear-45 from-primary via-accent to-secondary" />
<div className="bg-radial from-primary to-transparent" />
<div className="bg-conic-180 from-primary via-accent to-secondary" />

v3 (old)	v4 (new)
`bg-gradient-to-r`	`bg-linear-to-r`
`bg-gradient-to-br`	`bg-linear-to-br`
Not available	`bg-linear-45` (any angle)
Not available	`bg-radial`
Not available	`bg-conic-180` (any angle)

Gradient stops support positions: from-primary from-20% via-accent via-60% to-secondary to-100%

Theming Setup (MANDATORY)

First ask the user: Do you need one theme or two (light + dark)?

Every project must define its color system in globals.css using CSS variables + Tailwind's @theme directive.

Single theme (light only)

If the user only needs one theme, define everything in :root. No .dark, no @custom-variant.

/* globals.css */
@import "tailwindcss";

@theme {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... register all tokens */
}

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.15 0 0);
  --primary: oklch(0.55 0.2 250);
  --primary-foreground: oklch(1 0 0);
  /* ... see references/theming.md for full token list */
}

Two themes (light + dark)

If the user needs both themes, :root = light, .dark = dark, plus enable class-based toggle.

@import "tailwindcss";

@theme {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... register all tokens */
}

/* Light mode */
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.15 0 0);
  --primary: oklch(0.55 0.2 250);
  --primary-foreground: oklch(1 0 0);
  /* ... */
}

/* Dark mode */
.dark {
  --background: oklch(0.12 0 0);
  --foreground: oklch(0.95 0 0);
  --primary: oklch(0.65 0.2 250);
  --primary-foreground: oklch(0.1 0 0);
  /* ... */
}

/* Enable class-based dark mode */
@custom-variant dark (&:where(.dark, .dark *));

Then use semantic classes everywhere:

<button class="bg-primary text-primary-foreground hover:bg-primary/90">Save</button>

For full theming guide, see references/theming.md.

Dark Mode (only when two themes are used)

Class-based toggle via .dark on <html>. Semantic tokens handle it automatically.

// Components automatically adapt — no extra work
<div className="bg-background text-foreground" />  {/* Works in light AND dark */}

Never use dark: with hardcoded colors:

// BAD
<div className="bg-white dark:bg-gray-900 text-black dark:text-white" />

// GOOD — tokens handle it
<div className="bg-background text-foreground" />

Component Styling

Pattern	When to Use
Utility classes	Default — most styling
`cn()` utility	Conditional/merged classes
CSS variables + @theme	Design tokens, theme colors
`@variant`	Custom CSS needing Tailwind variants
`@apply`	Rarely — only base element resets

Responsive Design

Mobile-first. Use breakpoint prefixes to scale up:

<div className="px-4 md:px-8 lg:px-12" />
<h1 className="text-2xl md:text-4xl lg:text-5xl" />
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3" />

Always ascending order: base → sm: → md: → lg: → xl: → 2xl:

Tailwind v4 also provides max-* and not-* variants:

<div class="max-lg:p-8">Below lg only</div>
<div class="not-lg:bg-red-500">When NOT at lg or above</div>
<div class="md:max-xl:flex">Range: md to xl only</div>

Animation

Define custom animations in globals.css via @theme + @keyframes:

@theme {
  --animate-fade-in: fade-in 0.3s ease-out;
  --animate-slide-up: slide-up 0.3s ease-out;
}

<div class="animate-fade-in">Fades in</div>

Always respect reduced motion: motion-safe:animate-fade-in

For full responsive + animation guide, see references/responsive-animation.md.

Code Review

Quick checks for Tailwind code:

No hardcoded colors? (bg-blue-500, text-[#fff])
Semantic tokens used? (bg-primary, text-foreground)
cn() for conditional classes?
Focus styles on all interactive elements?
Mobile-first responsive? Breakpoints ascending?
Reduced motion respected?

For full checklist, see references/code-review-checklist.md.

tailwind-best-practice