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;

The cn() Utility

Every project using Tailwind in React should have this helper:

// lib/utils.ts
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

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

npm install clsx tailwind-merge

Usage — twMerge resolves conflicting utilities so the last one wins:

import { cn } from "@/lib/utils";

Without twMerge, cn("p-4", "p-6") would produce "p-4 p-6" (both applied, unpredictable). With twMerge, it correctly produces "p-6".

Responsive Design

Mobile-first breakpoints — unprefixed utilities are the base (mobile):

| Prefix | Min-width | Target | |--------|-----------|--------| | (none) | 0px | Mobile (base) | | sm: | 640px | Landscape phones | | md: | 768px | Tablets | | lg: | 1024px | Laptops | | xl: | 1280px | Desktops | | 2xl: | 1536px | Large screens |

  {items.map(item => )}

  Responsive heading

Container pattern:

  {children}

Dark Mode

Class-based (recommended for Next.js)

Toggle the dark class on ` — use next-themes` for persistence:

npm install next-themes

// app/providers.tsx
"use client";
import { ThemeProvider } from "next-themes";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    
      {children}
    
  );
}

// Usage — pair light and dark utilities:

  Muted text

CSS variable approach (scales with design systems)

@theme {
  --color-background: #ffffff;
  --color-foreground: #0a0a0a;
  --color-card: #ffffff;
  --color-card-foreground: #0a0a0a;
  --color-border: #e5e7eb;
}

.dark {
  --color-background: #0a0a0a;
  --color-foreground: #fafafa;
  --color-card: #111111;
  --color-card-foreground: #fafafa;
  --color-border: #27272a;
}

Then use bg-background, text-foreground, border-border — no dark: prefix needed because the variables themselves change.

Component Patterns

Reusable Button with Variants (CVA)

npm install class-variance-authority

// components/ui/button.tsx
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        secondary: "bg-muted text-muted-foreground hover:bg-muted/80",
        destructive: "bg-destructive text-white hover:bg-destructive/90",
        outline: "border border-border bg-transparent hover:bg-muted",
        ghost: "hover:bg-muted",
        link: "text-primary underline-offset-4 hover:underline",
      },
      size: {
        sm: "h-8 px-3 text-xs",
        default: "h-10 px-4",
        lg: "h-12 px-6 text-base",
        icon: "h-10 w-10",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
);

interface ButtonProps
  extends React.ButtonHTMLAttributes,
    VariantProps {}

export function Button({ className, variant, size, ...props }: ButtonProps) {
  return (
    
  );
}

Card Component

// components/ui/card.tsx
import { cn } from "@/lib/utils";

export function Card({ className, ...props }: React.HTMLAttributes) {
  return (
    
  );
}

export function CardHeader({ className, ...props }: React.HTMLAttributes) {
  return ;
}

export function CardTitle({ className, ...props }: React.HTMLAttributes) {
  return ;
}

export function CardContent({ className, ...props }: React.HTMLAttributes) {
  return ;
}

Input Component

// components/ui/input.tsx
import { cn } from "@/lib/utils";

interface InputProps extends React.InputHTMLAttributes {}

export function Input({ className, ...props }: InputProps) {
  return (
    
  );
}

Layout Patterns

Sticky Header + Scrollable Content

  
    
      {/* nav content */}
    
  
  
    {children}
  

Sidebar Layout

  
    {/* sidebar */}
  
  
    {children}
  

Centered Content

  
    {/* login form, etc. */}
  

Typography

{/* Heading hierarchy */}
Page title
Section
Subsection

{/* Body text */}
Body copy with relaxed leading.
Small helper text.

{/* Prose (for markdown/CMS content) */}

  {/* rendered markdown */}

The @tailwindcss/typography plugin provides the prose class for styling rendered HTML/markdown content.

Animation Utilities

{/* Built-in animations */}
     {/* loading spinner */}
    {/* skeleton loader */}
   {/* attention indicator */}

{/* Transition utilities */}

  Smooth hover

  Card hover effect

For complex animations, use Framer Motion instead of Tailwind animation utilities.

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | @apply for component styles | Extract a React component | | Raw color scales everywhere (bg-blue-500) | Define semantic tokens (bg-primary) | | Duplicating class strings across files | Extract a component or use CVA | | className="..." with 20+ utilities on one line | Break across multiple lines or use cn() with grouped strings | | Inline style={} for spacing/colors | Use Tailwind utilities | | Custom CSS file for simple layouts | Compose with flex/grid utilities | | Forgetting dark: variants | Always pair light and dark styles | | Not using twMerge for overridable components | Always use cn() for components that accept className |

For spacing, sizing, color, and typography reference tables, see reference/utility-reference.md. For form styling, table patterns, and advanced layout techniques, see reference/component-patterns.md.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: iwritec0de
• Source: iwritec0de/app-dev
• License: MIT

Install and usage instructions live in the source repository linked above.