Tailwind CSS Component Patterns

Status: Production Ready ✅ Last Updated: 2026-01-14 Tailwind Compatibility: v3.x and v4.x Source: Production projects, shadcn/ui patterns

Quick Start

Essential Patterns

tsx

// Section Container
<section className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-16 sm:py-24">
  {/* content */}
</section>

// Card Base
<div className="bg-card text-card-foreground rounded-lg border border-border p-6">
  {/* content */}
</div>

// Button Primary
<button className="bg-primary text-primary-foreground px-4 py-2 rounded-md hover:bg-primary/90 transition-colors">
  Click me
</button>

// Responsive Grid
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  {/* items */}
</div>

Spacing Scale

Consistent spacing prevents design drift:

Usage	Classes	Output
Tight spacing	`gap-2 p-2 space-y-2`	0.5rem (8px)
Standard spacing	`gap-4 p-4 space-y-4`	1rem (16px)
Comfortable	`gap-6 p-6 space-y-6`	1.5rem (24px)
Loose	`gap-8 p-8 space-y-8`	2rem (32px)
Section spacing	`py-16 sm:py-24`	4rem/6rem (64px/96px)

Standard Pattern: Use increments of 4 (4, 6, 8, 12, 16, 24)

Responsive Breakpoints

Mobile-first approach (base styles = mobile, add larger breakpoints):

Breakpoint	Min Width	Pattern	Example
Base	0px	No prefix	`text-base`
sm	640px	`sm:`	`sm:text-lg`
md	768px	`md:`	`md:grid-cols-2`
lg	1024px	`lg:`	`lg:px-8`
xl	1280px	`xl:`	`xl:max-w-7xl`
2xl	1536px	`2xl:`	`2xl:text-6xl`

tsx

// Mobile: 1 column, Tablet: 2 columns, Desktop: 3 columns
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">

Container Patterns

Standard Page Container

tsx

<div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">{/* content */}</div>

Variations:

•max-w-4xl - Narrow content (blog posts)
•max-w-5xl - Medium content
•max-w-6xl - Wide content
•max-w-7xl - Full width (default)

Section Spacing

tsx

<section className="py-16 sm:py-24">
  <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">{/* content */}</div>
</section>

Card Patterns

Basic Card

tsx

<div className="rounded-lg border border-border bg-card p-6 text-card-foreground">
  <h3 className="mb-2 text-lg font-semibold">Card Title</h3>
  <p className="text-muted-foreground">Card description goes here.</p>
</div>

Feature Card with Icon

tsx

<div className="rounded-lg border border-border bg-card p-6 text-card-foreground transition-shadow hover:shadow-lg">
  <div className="bg-primary/10 mb-4 flex h-12 w-12 items-center justify-center rounded-lg">
    {/* Icon */}
  </div>
  <h3 className="mb-2 text-lg font-semibold">Feature Title</h3>
  <p className="text-muted-foreground">Feature description.</p>
</div>

Pricing Card

tsx

<div className="relative rounded-lg border-2 border-border bg-card p-8 text-card-foreground">
  <div className="mb-2 text-sm font-semibold text-primary">Pro Plan</div>
  <div className="mb-1 text-4xl font-bold">
    $29<span className="text-lg text-muted-foreground">/mo</span>
  </div>
  <p className="mb-6 text-muted-foreground">For growing teams</p>
  <button className="hover:bg-primary/90 w-full rounded-md bg-primary py-2 text-primary-foreground">
    Get Started
  </button>
</div>

See references/card-patterns.md for more variants.

Grid Layouts

Auto-Responsive Grid

tsx

<div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
  {items.map((item) => (
    <Card key={item.id} {...item} />
  ))}
</div>

Auto-Fit Grid (Dynamic Columns)

tsx

<div className="grid grid-cols-[repeat(auto-fit,minmax(280px,1fr))] gap-6">
  {/* Automatically adjusts columns based on available space */}
</div>

Masonry-Style Grid

tsx

<div className="columns-1 gap-6 space-y-6 md:columns-2 lg:columns-3">
  {items.map((item) => (
    <div key={item.id} className="break-inside-avoid">
      <Card {...item} />
    </div>
  ))}
</div>

Button Patterns

tsx

// Primary
<button className="bg-primary text-primary-foreground px-4 py-2 rounded-md hover:bg-primary/90 transition-colors">
  Primary
</button>

// Secondary
<button className="bg-secondary text-secondary-foreground px-4 py-2 rounded-md hover:bg-secondary/80">
  Secondary
</button>

// Outline
<button className="border border-border bg-transparent px-4 py-2 rounded-md hover:bg-accent">
  Outline
</button>

// Ghost
<button className="bg-transparent px-4 py-2 rounded-md hover:bg-accent hover:text-accent-foreground">
  Ghost
</button>

// Destructive
<button className="bg-destructive text-destructive-foreground px-4 py-2 rounded-md hover:bg-destructive/90">
  Delete
</button>

Size Variants:

•Small: px-3 py-1.5 text-sm
•Default: px-4 py-2
•Large: px-6 py-3 text-lg

See references/button-patterns.md for full reference.

Form Patterns

Input Field

tsx

<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-border bg-background px-3 py-2 focus:outline-none focus:ring-2 focus:ring-primary"
    placeholder="you@example.com"
  />
</div>

Select Dropdown

tsx

<select className="w-full rounded-md border border-border bg-background px-3 py-2 focus:outline-none focus:ring-2 focus:ring-primary">
  <option>Option 1</option>
  <option>Option 2</option>
</select>

Checkbox

tsx

<div className="flex items-center space-x-2">
  <input
    id="terms"
    type="checkbox"
    className="h-4 w-4 rounded border-border text-primary focus:ring-2 focus:ring-primary"
  />
  <label htmlFor="terms" className="text-sm">
    I agree to the terms
  </label>
</div>

Error State

tsx

<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-destructive bg-background px-3 py-2 focus:outline-none focus:ring-2 focus:ring-destructive"
  />
  <p className="text-sm text-destructive">Password must be at least 8 characters</p>
</div>

See references/form-patterns.md for complete patterns.

Typography Patterns

Headings

tsx

<h1 className="text-4xl sm:text-5xl lg:text-6xl font-bold">
  Page Title
</h1>

<h2 className="text-3xl sm:text-4xl font-bold">
  Section Title
</h2>

<h3 className="text-2xl sm:text-3xl font-semibold">
  Subsection
</h3>

<h4 className="text-xl font-semibold">
  Card Title
</h4>

Body Text

tsx

<p className="text-base text-muted-foreground">
  Regular paragraph text.
</p>

<p className="text-lg text-muted-foreground leading-relaxed">
  Larger body text with comfortable line height.
</p>

<p className="text-sm text-muted-foreground">
  Small supporting text or captions.
</p>

Lists

tsx

<ul className="space-y-2 text-muted-foreground">
  <li className="flex items-start">
    <CheckIcon className="mr-2 mt-0.5 h-5 w-5 text-primary" />
    <span>Feature one</span>
  </li>
  <li className="flex items-start">
    <CheckIcon className="mr-2 mt-0.5 h-5 w-5 text-primary" />
    <span>Feature two</span>
  </li>
</ul>

See references/typography-patterns.md for complete guide.

Navigation Patterns

Header with Logo

tsx

<header className="bg-background/95 sticky top-0 z-50 w-full border-b border-border backdrop-blur">
  <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
    <div className="flex h-16 items-center justify-between">
      <div className="flex items-center gap-8">
        {/* Logo */}
        <a href="/" className="text-xl font-bold">
          Brand
        </a>

        {/* Desktop Nav */}
        <nav className="hidden gap-6 md:flex">
          <a href="#" className="text-sm transition-colors hover:text-primary">
            Features
          </a>
          <a href="#" className="text-sm transition-colors hover:text-primary">
            Pricing
          </a>
          <a href="#" className="text-sm transition-colors hover:text-primary">
            About
          </a>
        </nav>
      </div>

      {/* CTA */}
      <button className="rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground">
        Sign Up
      </button>
    </div>
  </div>
</header>

Footer

tsx

<footer className="bg-muted/50 border-t border-border">
  <div className="mx-auto max-w-7xl px-4 py-12 sm:px-6 lg:px-8">
    <div className="grid grid-cols-2 gap-8 md:grid-cols-4">
      <div>
        <h4 className="mb-4 font-semibold">Product</h4>
        <ul className="space-y-2 text-sm text-muted-foreground">
          <li>
            <a href="#" className="hover:text-primary">
              Features
            </a>
          </li>
          <li>
            <a href="#" className="hover:text-primary">
              Pricing
            </a>
          </li>
        </ul>
      </div>
      {/* More columns */}
    </div>
  </div>
</footer>

See references/navigation-patterns.md for mobile menus and dropdowns.

Dark Mode Support

All patterns use semantic color tokens that automatically adapt:

Token	Light Mode	Dark Mode
`bg-background`	White	Dark gray
`text-foreground`	Dark gray	White
`bg-card`	White	Slightly lighter gray
`text-muted-foreground`	Gray	Light gray
`border-border`	Light gray	Dark gray
`bg-primary`	Brand color	Lighter brand color

Never use raw colors like bg-blue-500 - always use semantic tokens.

See references/dark-mode-patterns.md for theme toggle implementation.

Common Class Combinations

Section with Heading

tsx

<section className="py-16 sm:py-24">
  <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
    <h2 className="mb-12 text-center text-3xl font-bold sm:text-4xl">Section Title</h2>
    <div className="grid grid-cols-1 gap-6 md:grid-cols-3">{/* content */}</div>
  </div>
</section>

Centered Content

tsx

<div className="flex flex-col items-center justify-center text-center">
  <h1 className="mb-4 text-4xl font-bold">Centered Title</h1>
  <p className="max-w-2xl text-muted-foreground">Centered description</p>
</div>

Hover Effects

tsx

// Lift on hover
<div className="transition-transform hover:scale-105">

// Shadow on hover
<div className="transition-shadow hover:shadow-lg">

// Color change on hover
<button className="transition-colors hover:bg-primary/90">

Critical Rules

✅ Always Do

•Use semantic color tokens (bg-card, text-foreground)
•Apply mobile-first responsive design (base → sm: → md:)
•Use consistent spacing scale (4, 6, 8, 12, 16, 24)
•Add transition-* classes for smooth interactions
•Test in both light and dark modes

❌ Never Do

•Use raw Tailwind colors (bg-blue-500 breaks themes)
•Skip responsive prefixes (mobile users suffer)
•Mix spacing scales randomly (creates visual chaos)
•Forget hover states on interactive elements
•Use fixed px values for text (text-base not text-[16px])

Template Components

Ready-to-use components in templates/components/:

•hero-section.tsx - Responsive hero with CTA
•feature-grid.tsx - 3-column feature grid with icons
•contact-form.tsx - Full form with validation styles
•footer.tsx - Multi-column footer with links

Copy and customize for your project.

Reference Documentation

Detailed patterns in references/ directory:

•layout-patterns.md - Containers, grids, flexbox layouts
•card-patterns.md - All card variants and states
•navigation-patterns.md - Headers, menus, breadcrumbs, footers
•form-patterns.md - Complete form styling guide
•button-patterns.md - All button variants and sizes
•typography-patterns.md - Text styles and hierarchies
•dark-mode-patterns.md - Theme switching implementation

Official Documentation

•Tailwind CSS: https://tailwindcss.com/docs
•shadcn/ui: https://ui.shadcn.com
•Tailwind UI: https://tailwindui.com (premium examples)

Last Updated: 2026-01-14 Skill Version: 1.0.0 Production: Tested across 10+ projects