tailwind-4

When to Use

Triggers: When styling with Tailwind, using className, conditional styles, or dark mode.

Load when: styling with Tailwind CSS 4, using className, implementing dark mode, or needing conditional styles.

Critical Patterns

Pattern 1: Semantic classes — never var() in className

// ✅ Use semantic classes
<div className="bg-primary text-white" />
<div className="border-border" />
<div className="text-foreground bg-background" />

// ❌ Never var() in className
<div className="bg-[var(--color-primary)]" />
<div className="text-[var(--foreground)]" />

Pattern 2: Literal values over hex

// ✅ Semantic
<p className="text-white bg-slate-900" />
<p className="text-gray-500" />

// ❌ Avoid hex in className when an equivalent exists
<p className="text-[#ffffff] bg-[#0f172a]" />

Pattern 3: cn() for conditional styles

import { clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

// ✅ Use cn() for conditionals and conflicts
<button
  className={cn(
    'px-4 py-2 rounded-md font-medium',
    variant === 'primary' && 'bg-primary text-white',
    variant === 'ghost' && 'bg-transparent hover:bg-accent',
    disabled && 'opacity-50 cursor-not-allowed',
    className // allows external override
  )}
/>

// ✅ Static classes — no cn() needed
<div className="flex items-center gap-4 p-6" />

Code Examples

Variants with cva (class-variance-authority)

import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
        outline: 'border border-input bg-background hover:bg-accent',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4',
        lg: 'h-12 px-6 text-lg',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'md',
    },
  }
);

interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}

function Button({ variant, size, className, ...props }: ButtonProps) {
  return (
    <button
      className={cn(buttonVariants({ variant, size }), className)}
      {...props}
    />
  );
}

Dark Mode

// ✅ Dark mode with Tailwind classes
<div className="bg-white dark:bg-gray-900">
  <p className="text-gray-900 dark:text-gray-100">Content</p>
  <button className="bg-blue-600 dark:bg-blue-500 hover:bg-blue-700 dark:hover:bg-blue-400">
    Action
  </button>
</div>

// CSS config (tailwind.config.ts)
export default {
  darkMode: 'class', // or 'media'
  // ...
}

Responsive Design

// Mobile-first with breakpoints
<div className="
  flex flex-col          // mobile: column
  md:flex-row            // tablet: row
  lg:grid lg:grid-cols-3 // desktop: 3-col grid
  gap-4
">
  <Card />
  <Card />
  <Card />
</div>

Exception for Libraries (Recharts, etc.)

// ✅ For libraries that don't support className, use CSS var constants
const CHART_COLORS = {
  primary: 'var(--color-primary)',
  secondary: 'var(--color-secondary)',
  muted: 'var(--color-muted)',
} as const;

<LineChart>
  <Line stroke={CHART_COLORS.primary} />
</LineChart>

Dynamic values at runtime

// ✅ style prop for runtime calculations
<div style={{ width: `${percentage}%` }} className="bg-primary h-2 rounded" />

// ✅ CSS custom properties for theming
<div
  style={{ '--card-cols': columns } as React.CSSProperties}
  className="grid grid-cols-[repeat(var(--card-cols),1fr)]"
/>

Anti-Patterns

❌ var() in className

// ❌ Breaks Tailwind's optimizer
<div className="bg-[var(--primary)] text-[var(--fg)]" />

// ✅
<div className="bg-primary text-foreground" />

❌ String concatenation for conditionals

// ❌ Can generate invalid classes
<div className={'text-sm ' + (active ? 'text-blue-600' : 'text-gray-500')} />

// ✅
<div className={cn('text-sm', active ? 'text-blue-600' : 'text-gray-500')} />

❌ cn() for purely static classes

// ❌ Unnecessary
<div className={cn('flex items-center gap-4')} />

// ✅
<div className="flex items-center gap-4" />

Quick Reference

Task	Pattern
Semantic color	bg-primary, text-foreground
Conditional	cn('base', condition && 'variant')
Variants	cva('base', { variants: ... })
Dark mode	dark:bg-slate-900
Responsive	sm: md: lg: xl:
Runtime value	style={{ width: \${val}%` }}`
External override	Accept and apply className prop with cn()

Rules

• Use the cn() utility (clsx + tailwind-merge) for all conditional class composition; string concatenation for dynamic classes causes class conflicts that tailwind-merge resolves
• Tailwind 4 uses CSS-first configuration (@theme in CSS) — never use tailwind.config.js theme extensions for new Tailwind 4 projects
• Avoid @apply in component CSS files; Tailwind utility classes belong in the markup, not extracted into CSS rules
• Component library classes (shadcn/ui, Radix) must not be overridden with Tailwind classes on the same element — extend via variants or wrapper elements
• Dynamic class names must be complete strings (e.g., 'text-red-500'), never constructed by string interpolation (e.g., `text-${color}-500`) — PurgeCSS/Tailwind cannot detect partial class names