Tailwind CSS - Utility-First Styling

Patterns for Tailwind CSS v4, responsive design, and component composition

---

When to Use This Skill

Use this skill when:

• Styling applications with Tailwind CSS
• Building responsive layouts
• Creating reusable UI components
• Configuring Tailwind themes
• Implementing dark mode
• Optimizing for production

Don't use this skill when:

• Using CSS-in-JS libraries (styled-components, Emotion)
• Writing traditional CSS/SCSS
• Using other utility frameworks (UnoCSS, Windi)

---

Critical Patterns

Pattern 1: Responsive Design

When: Building mobile-first responsive layouts

// ✅ GOOD: Mobile-first responsive design
<div className="
  flex flex-col gap-4
  md:flex-row md:gap-6
  lg:gap-8
">
  {/* Stack on mobile, row on md+, larger gap on lg+ */}
  <aside className="w-full md:w-64 lg:w-80">
    <Sidebar />
  </aside>
  <main className="flex-1">
    <Content />
  </main>
</div>

// ✅ GOOD: Responsive typography
<h1 className="text-2xl sm:text-3xl md:text-4xl lg:text-5xl font-bold">
  Responsive Heading
</h1>

// ✅ GOOD: Responsive grid
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4">
  {products.map(p => <ProductCard key={p.id} product={p} />)}
</div>

// ❌ BAD: Desktop-first (harder to maintain)
<div className="flex-row md:flex-col"> {/* Confusing! */}

Breakpoints (Tailwind defaults):

• sm: 640px
• md: 768px
• lg: 1024px
• xl: 1280px
• 2xl: 1536px

Pattern 2: Component Composition with CVA

When: Building variant-based components

// ✅ GOOD: Using class-variance-authority (CVA)
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';

const buttonVariants = cva(
  // Base styles
  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50',
  {
    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 hover:text-accent-foreground',
        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
        link: 'text-primary underline-offset-4 hover:underline',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 px-3 text-sm',
        lg: 'h-11 px-8 text-lg',
        icon: 'h-10 w-10',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
);

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

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

// Usage
<Button variant="destructive" size="lg">Delete</Button>
<Button variant="outline">Cancel</Button>

// ❌ BAD: Prop-based conditional classes without system
<button className={`
  px-4 py-2 rounded
  ${variant === 'primary' ? 'bg-blue-500' : ''}
  ${variant === 'secondary' ? 'bg-gray-500' : ''}
  ${size === 'large' ? 'text-lg px-6' : ''}
`}>

Pattern 3: Dark Mode

When: Implementing light/dark themes

// ✅ GOOD: Class-based dark mode (recommended)
// tailwind.config.ts
export default {
  darkMode: 'class', // or 'media' for system preference
  // ...
}

// Component with dark mode support
<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
  <h1 className="text-2xl font-bold">Dashboard</h1>
  <p className="text-gray-600 dark:text-gray-400">
    Welcome back
  </p>
</div>

// ✅ GOOD: CSS variables for theming
// globals.css
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 222.2 47.4% 11.2%;
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --primary: 210 40% 98%;
  }
}

// tailwind.config.ts
theme: {
  extend: {
    colors: {
      background: 'hsl(var(--background))',
      foreground: 'hsl(var(--foreground))',
      primary: 'hsl(var(--primary))',
    },
  },
}

// Usage - automatically adapts to theme
<div className="bg-background text-foreground">
  <button className="bg-primary text-primary-foreground">Click</button>
</div>

// ❌ BAD: Hardcoded colors without dark mode
<div className="bg-white text-black"> {/* No dark mode! */}

Pattern 4: Utility Function for Class Merging

When: Combining conditional classes safely

// ✅ GOOD: cn() utility with tailwind-merge
// lib/utils.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

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

// Usage - handles conflicts correctly
<div className={cn(
  'px-4 py-2 rounded',
  isActive && 'bg-blue-500',
  className // Allow override from props
)}>

// twMerge resolves conflicts:
cn('px-4', 'px-6') // → 'px-6' (not 'px-4 px-6')
cn('text-red-500', 'text-blue-500') // → 'text-blue-500'

// ❌ BAD: String concatenation (doesn't resolve conflicts)
className={`px-4 ${className}`} // px-4 and px-6 would both apply!

// ❌ BAD: Just clsx without twMerge
clsx('px-4', 'px-6') // → 'px-4 px-6' (both apply, undefined behavior)

Pattern 5: Layout Patterns

When: Building common layout structures

// ✅ GOOD: Centered container with max-width
<div className="container mx-auto px-4 sm:px-6 lg:px-8">
  <Content />
</div>

// ✅ GOOD: Sticky header with content scroll
<div className="flex h-screen flex-col">
  <header className="sticky top-0 z-50 border-b bg-background/95 backdrop-blur">
    <Nav />
  </header>
  <main className="flex-1 overflow-auto">
    <Content />
  </main>
  <footer className="border-t">
    <Footer />
  </footer>
</div>

// ✅ GOOD: Sidebar layout
<div className="flex h-screen">
  <aside className="w-64 border-r bg-muted/50 overflow-y-auto">
    <Sidebar />
  </aside>
  <main className="flex-1 overflow-y-auto">
    <Content />
  </main>
</div>

// ✅ GOOD: Card grid with equal heights
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  {items.map(item => (
    <div key={item.id} className="flex flex-col rounded-lg border p-6">
      <h3 className="text-lg font-semibold">{item.title}</h3>
      <p className="flex-1 text-muted-foreground">{item.description}</p>
      <button className="mt-4">Learn more</button>
    </div>
  ))}
</div>

---

Code Examples

Example 1: Form Styling

export function LoginForm() {
  return (
    <form className="space-y-4 w-full max-w-sm">
      <div className="space-y-2">
        <label htmlFor="email" className="text-sm font-medium">
          Email
        </label>
        <input
          id="email"
          type="email"
          className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50"
          placeholder="you@example.com"
        />
      </div>

      <div className="space-y-2">
        <label htmlFor="password" className="text-sm font-medium">
          Password
        </label>
        <input
          id="password"
          type="password"
          className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
        />
      </div>

      <button
        type="submit"
        className="w-full rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2"
      >
        Sign in
      </button>
    </form>
  );
}

Example 2: Responsive Navigation

export function Navigation() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <nav className="border-b">
      <div className="container mx-auto flex h-16 items-center justify-between px-4">
        <Logo />

        {/* Desktop nav */}
        <div className="hidden md:flex items-center gap-6">
          <NavLink href="/products">Products</NavLink>
          <NavLink href="/about">About</NavLink>
          <NavLink href="/contact">Contact</NavLink>
          <Button>Sign in</Button>
        </div>

        {/* Mobile menu button */}
        <button
          className="md:hidden p-2"
          onClick={() => setIsOpen(!isOpen)}
          aria-label="Toggle menu"
        >
          <MenuIcon className="h-6 w-6" />
        </button>
      </div>

      {/* Mobile nav */}
      {isOpen && (
        <div className="md:hidden border-t p-4 space-y-4">
          <NavLink href="/products" className="block">Products</NavLink>
          <NavLink href="/about" className="block">About</NavLink>
          <NavLink href="/contact" className="block">Contact</NavLink>
          <Button className="w-full">Sign in</Button>
        </div>
      )}
    </nav>
  );
}

Example 3: Animation with Tailwind

// Hover and focus animations
<button className="transform transition-all duration-200 hover:scale-105 hover:shadow-lg active:scale-95">
  Animated Button
</button>

// Fade in on mount (with Tailwind + React)
<div className="animate-in fade-in duration-500">
  Content fades in
</div>

// Custom animation in config
// tailwind.config.ts
theme: {
  extend: {
    keyframes: {
      'slide-in': {
        '0%': { transform: 'translateX(-100%)' },
        '100%': { transform: 'translateX(0)' },
      },
    },
    animation: {
      'slide-in': 'slide-in 0.3s ease-out',
    },
  },
}

// Usage
<div className="animate-slide-in">Slides in from left</div>

---

Anti-Patterns

Don't: Duplicate Class Strings

// ❌ BAD: Copy-pasting the same classes
<button className="px-4 py-2 rounded bg-blue-500 text-white hover:bg-blue-600">Save</button>
<button className="px-4 py-2 rounded bg-blue-500 text-white hover:bg-blue-600">Submit</button>
<button className="px-4 py-2 rounded bg-blue-500 text-white hover:bg-blue-600">Send</button>

// ✅ GOOD: Extract to component or CVA
const Button = ({ children }) => (
  <button className="px-4 py-2 rounded bg-blue-500 text-white hover:bg-blue-600">
    {children}
  </button>
);

Don't: Over-customize in Config

// ❌ BAD: Adding every possible value
theme: {
  extend: {
    spacing: {
      '13': '3.25rem',
      '15': '3.75rem',
      '17': '4.25rem',
      // ...endless custom values
    },
  },
}

// ✅ GOOD: Use arbitrary values when needed
<div className="mt-[3.25rem]">Arbitrary value</div>

// Or stick to the default scale
<div className="mt-12 lg:mt-16">Uses default scale</div>

Don't: Ignore Accessibility

// ❌ BAD: Low contrast, no focus states
<button className="bg-gray-200 text-gray-400">Hard to read</button>

// ✅ GOOD: Proper contrast and focus states
<button className="bg-gray-900 text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2">
  Accessible
</button>

---

Quick Reference

Task	Classes	Example
Center content	flex items-center justify-center	Container centering
Responsive hide	hidden md:block	Show only on md+
Truncate text	truncate	Single line ellipsis
Aspect ratio	aspect-video	16:9 ratio
Gradient	bg-gradient-to-r from-blue-500 to-purple-500	Horizontal gradient
Shadow	shadow-md hover:shadow-lg	Elevation effect
Ring focus	focus:ring-2 focus:ring-offset-2	Focus indicator

---

Resources

Official Documentation:

• Tailwind CSS
• Tailwind UI

Related Skills:

• react: React component patterns
• accessibility: WCAG compliance
• ui-ux: Design principles

---

Keywords

tailwind, tailwindcss, css, styling, responsive, utility-first, dark-mode, components, design-system