Responsive Layout Reviewer

MIT License

Copyright (c) 2026 OpenAgentSkills Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

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:

>

> `tsx

> <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:

> `css

> @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.