Responsive Layout Repair

---
name: responsive-repair
description: "Diagnose and repair responsive layouts on vibecoded sites, fixing overflow, tiny tap targets, and non-collapsing grids for mobile and tablet."
metadata:
  tags: "visual-design, responsive-design, css, web-layout, mobile-layout, grid-system, overflow-management"
  source: "https://skilldb.dev/skills/web-polish-skills/responsive-repair"
  pack: "web-polish-skills"
  category: "Visual Arts & Design"
---

# Responsive Layout Repair

## When to use this skill
Use when the user says things like:
- "how do I fix responsive layout issues on a site"
- "i need responsive layout repair for a vibecoded site"
- "my mobile layout has overflow or small tap targets"
- "the grid isn't collapsing on mobile, fix it"
- "breakpoints are inconsistent, repair the layout"


You are a responsive design specialist who fixes the mobile and tablet breakage that vibecoded
sites invariably ship with. When code is generated for a desktop viewport and mobile is an
afterthought, you get horizontal scrollbars, text too small to read, buttons too small to tap,
and layouts that crumble below 768px.

## Common Vibecoded Responsive Failures

1. **Horizontal overflow.** Fixed-width elements (tables, code blocks, images) wider than the
   viewport causing horizontal scrollbars.
2. **Grids that don't collapse.** Three-column grids staying three columns on a 375px phone.
3. **Touch targets too small.** 24px buttons and 16px-tall links that are impossible to tap.
4. **Text too small.** Body text below 16px causing iOS zoom on form inputs.
5. **Navigation doesn't adapt.** Desktop nav bar wrapping uglily instead of becoming a mobile menu.
6. **Modals don't fit.** Fixed-width modals overflowing on small screens.
7. **Images break layout.** Images without max-width extending beyond their containers.
8. **Padding doesn't scale.** Same 48px padding on desktop and mobile, cramping content.

## The Fix Process

### Step 1: Set the Foundation

```css
/* Prevent ALL overflow issues — this catches most vibecode breakage */
html {
  overflow-x: hidden;
}

/* Every image and media respects its container */
img, video, svg, iframe, canvas {
  max-width: 100%;
  height: auto;
}

/* Prevent iOS zoom on form inputs */
input, select, textarea {
  font-size: 16px; /* iOS zooms if font-size < 16px */
}

/* Minimum tap target size */
button, a, [role="button"], input[type="checkbox"], input[type="radio"] {
  min-height: 44px;
  min-width: 44px;
}

/* Box sizing everywhere */
*, *::before, *::after {
  box-sizing: border-box;
}
```

### Step 2: Define Consistent Breakpoints

Use the same breakpoints everywhere. Don't invent per-component breakpoints.

```css
/* Mobile-first breakpoints */
/* Default: 0-639px    (mobile) */
/* sm:      640-767px  (large phone / small tablet) */
/* md:      768-1023px (tablet) */
/* lg:      1024-1279px (small desktop) */
/* xl:      1280+px    (large desktop) */

/* In Tailwind these are default. In CSS: */
@media (min-width: 640px)  { /* sm */ }
@media (min-width: 768px)  { /* md */ }
@media (min-width: 1024px) { /* lg */ }
@media (min-width: 1280px) { /* xl */ }
```

### Step 3: Fix Grids

```tsx
/* BEFORE: Fixed 3 columns everywhere */
<div className="grid grid-cols-3 gap-6">

/* AFTER: Responsive columns */
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 md:gap-6">
```

Common patterns:
```
1 col mobile → 2 col tablet → 3 col desktop:
  grid-cols-1 sm:grid-cols-2 lg:grid-cols-3

1 col mobile → 2 col desktop:
  grid-cols-1 md:grid-cols-2

Full width mobile → sidebar + content desktop:
  flex flex-col lg:flex-row

Stack mobile → inline desktop:
  flex flex-col sm:flex-row
```

### Step 4: Fix Container Width

```css
/* One max-width container used everywhere */
.container {
  width: 100%;
  max-width: 1280px;
  margin-left: auto;
  margin-right: auto;
  padding-left: 1rem;    /* 16px on mobile */
  padding-right: 1rem;
}

@media (min-width: 640px) {
  .container {
    padding-left: 1.5rem;  /* 24px on tablet */
    padding-right: 1.5rem;
  }
}

@media (min-width: 1024px) {
  .container {
    padding-left: 2rem;    /* 32px on desktop */
    padding-right: 2rem;
  }
}
```

### Step 5: Fix Tables

Tables are the most common overflow offender:

```tsx
/* Option 1: Horizontal scroll wrapper */
<div className="overflow-x-auto -mx-4 px-4 md:mx-0 md:px-0">
  <table className="min-w-[600px] w-full">
    {/* table content */}
  </table>
</div>

/* Option 2: Cards on mobile, table on desktop */
<div className="hidden md:block">
  <Table data={items} />
</div>
<div className="md:hidden space-y-3">
  {items.map(item => <MobileCard key={item.id} item={item} />)}
</div>

/* Option 3: Collapse columns on mobile */
<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th className="hidden md:table-cell">Phone</th>
      <th className="hidden lg:table-cell">Role</th>
      <th>Actions</th>
    </tr>
  </thead>
</table>
```

### Step 6: Fix Navigation

```tsx
/* Desktop: horizontal nav */
<nav className="hidden lg:flex items-center gap-6">
  {links.map(link => (
    <a key={link.href} href={link.href}>{link.label}</a>
  ))}
</nav>

/* Mobile: hamburger + slide-out or bottom sheet */
<button className="lg:hidden" onClick={() => setMenuOpen(true)}>
  <Menu className="h-6 w-6" />
</button>

{/* Mobile menu */}
{menuOpen && (
  <div className="fixed inset-0 z-50 lg:hidden">
    <div className="fixed inset-0 bg-black/50" onClick={() => setMenuOpen(false)} />
    <nav className="fixed inset-y-0 right-0 w-72 bg-white shadow-xl p-6">
      <button onClick={() => setMenuOpen(false)} className="mb-6">
        <X className="h-6 w-6" />
      </button>
      {links.map(link => (
        <a key={link.href} href={link.href} className="block py-3 text-lg">
          {link.label}
        </a>
      ))}
    </nav>
  </div>
)}
```

### Step 7: Fix Modals on Mobile

```tsx
/* Modal content should be full-width on mobile, centered on desktop */
<DialogContent className={cn(
  'w-full',
  // Mobile: full width with margins
  'mx-4 max-h-[85vh]',
  // Desktop: centered with max-width
  'md:mx-auto md:max-w-md'
)}>
```

### Step 8: Fix Typography Scaling

```css
/* Text that's too big on mobile */
.hero-title {
  font-size: 2rem;      /* 32px mobile */
}
@media (min-width: 768px) {
  .hero-title {
    font-size: 3rem;    /* 48px tablet */
  }
}
@media (min-width: 1024px) {
  .hero-title {
    font-size: 3.75rem; /* 60px desktop */
  }
}

/* Or use clamp for fluid sizing */
.hero-title {
  font-size: clamp(2rem, 1rem + 5vw, 3.75rem);
}
```

### Step 9: Fix Spacing

```css
/* Section padding that scales */
.section {
  padding-top: 3rem;     /* 48px mobile */
  padding-bottom: 3rem;
}
@media (min-width: 768px) {
  .section {
    padding-top: 5rem;   /* 80px tablet+ */
    padding-bottom: 5rem;
  }
}

/* Gap that scales */
.card-grid {
  gap: 1rem;             /* 16px mobile */
}
@media (min-width: 768px) {
  .card-grid {
    gap: 1.5rem;         /* 24px tablet+ */
  }
}
```

## Testing Checklist

Test at these widths:
- **320px** — Smallest phone (iPhone SE)
- **375px** — Standard phone (iPhone 12/13/14)
- **428px** — Large phone (iPhone Pro Max)
- **768px** — Tablet portrait (iPad)
- **1024px** — Tablet landscape / small laptop
- **1280px** — Standard desktop
- **1920px** — Large desktop

At each width, verify:
- [ ] No horizontal scrollbar
- [ ] All text is readable (min 16px body)
- [ ] All tap targets are at least 44px
- [ ] Navigation works
- [ ] Modals fit the screen
- [ ] Images don't overflow
- [ ] Tables don't break layout
- [ ] Forms are usable

## Anti-Patterns

- Don't hide content on mobile that users need. Collapsing secondary info is fine; removing
  navigation items is not.
- Don't use `display: none` to "fix" overflow. Find and fix the actual overflow source.
- Don't use viewport units (vw/vh) for layout — they don't account for mobile browser chrome.
  Use `dvh` or percentages instead.
- Don't set fixed heights on content areas. Content length varies; let heights be flexible.
- Don't assume hover is available on mobile. Touch devices don't hover.