tailwind

Tailwind CSS

Tailwind CSS utility-first patterns for React and Next.js applications.

Critical Rules

1. Utility-first — compose styles from utility classes directly in markup; extract components, not CSS classes
2. Never use @apply to build component classes — extract a React component instead; @apply defeats the purpose of utility-first and creates abstraction layers that are harder to maintain
3. Use the cn() helper for conditional classes — combine clsx + tailwind-merge to handle conflicts and conditionals cleanly
4. Mobile-first responsive — unprefixed utilities target mobile; use sm:, md:, lg:, xl:, 2xl: for larger screens
5. Semantic color tokens — use design-system colors (bg-primary, text-muted-foreground) rather than raw scales (bg-blue-500) when a design system is in place
6. Dark mode via dark: variant — pair light and dark utilities on the same element; never maintain separate component trees for themes

Setup with Next.js

Tailwind v4 (CSS-first configuration)

npm install tailwindcss @tailwindcss/postcss

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

// postcss.config.ts
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Tailwind v4 uses CSS for configuration instead of tailwind.config.js. Define custom values with @theme:

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

@theme {
  --color-primary: #2563eb;
  --color-primary-foreground: #ffffff;
  --color-muted: #f1f5f9;
  --color-muted-foreground: #64748b;
  --color-destructive: #ef4444;

  --font-sans: "Inter", sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  --radius-lg: 0.75rem;
  --radius-md: 0.5rem;
  --radius-sm: 0.25rem;
}

These become utilities automatically: bg-primary, text-muted-foreground, font-sans, rounded-lg.

Tailwind v3 (JS configuration)

// tailwind.config.ts
import type { Config } from "tailwindcss";

const config: Config = {
  content: ["./app/**/*.{ts,tsx}", "./components/**/*.{ts,tsx}"],
  darkMode: "class",
  theme: {
    extend: {
      colors: {
        primary: { DEFAULT: "#2563eb", foreground: "#ffffff" },
        muted: { DEFAULT: "#f1f5f9", foreground: "#64748b" },
      },
    },
  },
};

export default config;