Responsive layout reviewer

Responsive Layout Reviewer

What this skill does

This skill reviews HTML/CSS, Tailwind, or React component code for responsive design issues. It checks for layout problems at mobile (320–480px), tablet (768–1024px), and desktop (1280px+) breakpoints, identifies common mistakes like fixed widths, missing overflow handling, inaccessible touch targets, and viewport-breaking elements, and produces a specific list of issues with exact fixes for each.

Use this during code review, before shipping a new component or page, or when a layout is broken on certain screen sizes and you need a systematic diagnosis.

How to use

Claude Code / Cline

Copy this file to .agents/skills/responsive-layout-reviewer/SKILL.md in your project root.

Then ask:

• "Use the Responsive Layout Reviewer skill on src/components/ProductCard.tsx."
• "Review this CSS for responsive issues using the Responsive Layout Reviewer skill."

Provide the component file or the HTML/CSS to review.

Cursor

Add the instructions below to your .cursorrules or paste them into the Cursor AI pane before sharing the code to review.

Codex

Paste the HTML/CSS or component code and ask Codex to follow the instructions below.

The Prompt / Instructions for the Agent

When asked to review for responsive design issues, check every item in this checklist:

Breakpoints to evaluate

Unless the project uses a custom breakpoint system, evaluate at:

• Mobile: 320px (small phone), 375px (iPhone standard)
• Mobile landscape: 667px
• Tablet: 768px, 1024px
• Desktop: 1280px, 1440px
• Wide: 1920px

Note the breakpoint system used by the project (Tailwind defaults, Bootstrap, custom media queries) and use those values.

Checklist

Fixed widths

• Any element with a hardcoded pixel width that could overflow on smaller screens (e.g., width: 600px without max-width: 100%)
• Flex or grid children with flex: 0 0 [fixed] that could overflow
• Tables without overflow-x: auto on a wrapper

Overflow and clipping

• Long text strings (URLs, email addresses, names) that don't have overflow-wrap: break-word or text-overflow: ellipsis
• Images without max-width: 100% or width: 100%
• Horizontal scroll introduced by an element wider than the viewport
• overflow: hidden on a parent that clips important content on small screens

Typography

• Font sizes below 16px on mobile (causes iOS to auto-zoom on input focus)
• line-height too tight for small screens
• Heading sizes that remain large on mobile without downscaling

Touch targets

• Clickable elements smaller than 44×44px (Apple HIG) or 48×48dp (Material Design) on mobile
• Links or buttons too close together without sufficient spacing (< 8px gap)
• Hover-only interactions with no touch equivalent

Navigation

• Desktop navigation that doesn't adapt (no mobile menu, items overflow, hamburger missing)
• Dropdown menus that don't work on touch devices

Spacing and padding

• Elements with no padding on small screens, causing content to touch the screen edge
• Fixed margins that eat into usable space on narrow screens

Images and media

• <img> without width and height attributes (causes layout shift)
• Background images without background-size: cover or equivalent
• Video embeds with no responsive wrapper (padding-top: 56.25%; position: relative)

Flexbox and grid

• flex-wrap: nowrap on a row that can't fit all items at small sizes
• Grid with fixed column counts that should switch to fewer columns on mobile
• gap values that are too large on mobile

Input fields and forms

• Inputs without width: 100% or equivalent on mobile
• font-size below 16px on inputs (triggers iOS zoom)
• Select dropdowns with fixed widths that overflow

Output format

## Responsive Layout Review — [Component/File]

### Critical Issues (will break layout or block usage on mobile)

#### 1. [Issue title]
- **Breakpoint affected**: [e.g., 320px–768px]
- **Location**: [CSS class, line number, or component prop]
- **Problem**: [What breaks and why]
- **Fix**: [Exact CSS/Tailwind/code change]

### High-Priority Issues (visible problems, degrades UX significantly)

[Same format]

### Warnings (minor issues or edge cases)

[Same format]

### What's Working Well
[Brief note on responsive patterns already done correctly]

Example

Input to Agent:

"Use the Responsive Layout Reviewer skill on this component:

<div style={{ display: 'flex', gap: 24 }}>
  <img src={product.image} style={{ width: 300, height: 300 }} />
  <div style={{ width: 400 }}>
    <h2 style={{ fontSize: 28 }}>{product.name}</h2>
    <p style={{ fontSize: 14 }}>{product.description}</p>
    <button style={{ padding: '4px 8px', fontSize: 12 }}>Add to cart</button>
  </div>
</div>
```"

Output from Agent:

Responsive Layout Review — ProductCard

Critical Issues

1. Fixed widths cause overflow on mobile

• Breakpoint affected: All screens below 724px (300 + 400 + 24 gap = 724px minimum width)
• Location: img width 300px, inner div width 400px
• Problem: The total minimum width (724px) exceeds most phone screens, causing horizontal scroll
• Fix: Remove fixed widths; use flex: 1 on the text div and flex-shrink: 0 on the image, or switch to a column layout below 640px:

  @media (max-width: 640px) {
    .card { flex-direction: column; }
    .card img { width: 100%; height: auto; }
  }
  

High-Priority Issues

2. Touch target too small

• Breakpoint affected: Mobile
• Location: button with padding: 4px 8px
• Problem: The button is approximately 30px tall — well below the 44px minimum for comfortable touch interaction
• Fix: padding: '12px 20px' — this produces a taller target and also improves visual balance

3. Font size below 16px on mobile

• Location: <p> with fontSize: 14 and <button> with fontSize: 12
• Problem: On iOS, inputs and interactive elements with font-size < 16px trigger page zoom on focus. Also, 12px text is hard to read on small screens.
• Fix: Set body text to minimum 16px; button text to 14–16px

Notes

• Static code review can catch most structural issues, but testing in actual browser DevTools (or on a real device) is still necessary for confirming scroll and touch behavior.
• Tailwind projects should use the sm:, md:, lg: prefixes consistently — look for Tailwind utilities with no mobile-first base value.
• For complex layouts, suggest testing with Chrome DevTools Device Mode at 375px width as a baseline.