secondsky/claude-skills / plugins/design-review/skills/design-review
design-review
Verified7-phase frontend design review with accessibility (WCAG 2.1 AA), responsive testing, visual polish. Use for PR reviews, UI audits, or encountering contrast issues, broken layouts, accessibility violations, inconsistent spacing, missing focus states.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 24.1 KB |
| assets/checklist-template.md | markdown | 9.5 KB |
| assets/review-report-template.md | markdown | 11.0 KB |
| references/accessibility-wcag.md | markdown | 22.6 KB |
| references/browser-tools-reference.md | markdown | 14.3 KB |
| references/code-health-patterns.md | markdown | 13.2 KB |
| references/design-principles-s-tier.mdexecutable | script | 9.1 KB |
| references/interaction-patterns.md | markdown | 15.7 KB |
| references/responsive-testing.md | markdown | 13.1 KB |
| references/visual-polish.md | markdown | 15.4 KB |
references/responsive-testing.md
View on GitHub# Responsive Design Testing Guide
**Objective**: Ensure UI works flawlessly across all device sizes
**Standard Viewports**: Desktop (1440px), Tablet (768px), Mobile (375px)
**Target**: No horizontal scrolling, readable text, accessible touch targets
---
## Standard Test Viewports
### Desktop: 1440px × 900px
- **Represents**: Modern laptop screens (MacBook Pro 15", common desktop resolutions)
- **Focus**: Optimal layout, full feature set, efficient use of space
- **Common issues**: Excessive whitespace, stretched content
### Tablet: 768px × 1024px
- **Represents**: iPad, Android tablets in portrait
- **Focus**: Graceful layout adaptation, touch-friendly targets
- **Common issues**: Cramped layouts, awkward column wrapping
### Mobile: 375px × 667px
- **Represents**: iPhone SE/8, common Android phones
- **Focus**: Single-column layout, thumb-friendly navigation
- **Common issues**: Horizontal scrolling, tiny text, small touch targets
---
## Testing Procedure
### Step 1: Desktop Testing (1440px)
**Browser setup:**
```bash
# Using Playwright MCP
mcp__playwright__browser_resize(width: 1440, height: 900)
mcp__playwright__browser_take_screenshot(fullPage: true)
# Using Chrome DevTools
# Open DevTools → Device Toolbar → Responsive → Set 1440 × 900
```
**Checklist:**
- [ ] Layout uses available space efficiently (no excessive whitespace)
- [ ] Multi-column layouts aligned properly
- [ ] Images scaled appropriately
- [ ] Navigation fully expanded and accessible
- [ ] All content visible without horizontal scrolling
- [ ] Text remains readable (not stretched wide across screen)
**Common desktop issues:**
- Content stretched too wide (>1200px max-width recommended)
- Poor use of whitespace (content lost in sea of empty space)
- Fixed-width elements not scaling
- Awkward column layouts
---
### Step 2: Tablet Testing (768px)
**Browser setup:**
```bash
# Using Playwright MCP
mcp__playwright__browser_resize(width: 768, height: 1024)
mcp__playwright__browser_take_screenshot(fullPage: true)
# Using Chrome DevTools
# Device Toolbar → iPad → Portrait
```
**Checklist:**
- [ ] Multi-column layouts collapse gracefully (e.g., 3-col → 2-col)
- [ ] Navigation adapts (hamburger menu or simplified nav)
- [ ] Touch targets minimum 44px × 44px
- [ ] No overlapping elements from column wrapping
- [ ] Images and media scale appropriately
- [ ] Forms remain usable (not cramped)
- [ ] No horizontal scrolling
**Common tablet issues:**
- Awkward 3-to-2 column transitions
- Touch targets too small (<44px)
- Navigation doesn't collapse appropriately
- Content cramped or overlapping
- Fixed-width sidebars breaking layout
**Tablet-specific considerations:**
```css
/* ✅ Good: Tablet breakpoint */
@media (max-width: 768px) {
.grid-3-col {
grid-template-columns: repeat(2, 1fr); /* 3 → 2 columns */
}
.sidebar {
width: 100%; /* Stack sidebar below content */
}
}
```
---
### Step 3: Mobile Testing (375px)
**Browser setup:**
```bash
# Using Playwright MCP
mcp__playwright__browser_resize(width: 375, height: 667)
mcp__playwright__browser_take_screenshot(fullPage: true)
# Using Chrome DevTools
# Device Toolbar → iPhone SE or Responsive 375 × 667
```
**Critical mobile checklist:**
- [ ] **No horizontal scrolling** (most common issue)
- [ ] Single-column layout throughout
- [ ] Text minimum 16px (prevents zoom on iOS)
- [ ] Touch targets minimum 44px × 44px
- [ ] Navigation collapses to hamburger menu
- [ ] Forms stacked vertically (not side-by-side)
- [ ] Images scale down to container width
- [ ] Adequate spacing between clickable elements (8-12px minimum)
- [ ] Bottom navigation or sticky elements don't cover content
**Common mobile issues:**
- **Horizontal scrolling** (viewport overflow)
- **Text too small** (<16px triggers iOS zoom)
- **Touch targets too small** (<44px hard to tap)
- **Fixed-width containers** breaking layout
- **Images not responsive** (exceeding viewport)
- **Cramped spacing** (elements too close to tap accurately)
- **Hidden content** behind sticky headers/footers
**Mobile-specific code patterns:**
```css
/* ❌ Bad: Fixed width causes overflow */
.container {
width: 1200px;
}
/* ✅ Good: Responsive width */
.container {
width: 100%;
max-width: 1200px;
padding: 0 16px; /* Breathing room */
}
/* ❌ Bad: Tiny text on mobile */
body {
font-size: 14px;
}
/* ✅ Good: Readable text (prevents iOS zoom) */
body {
font-size: 16px;
}
/* ❌ Bad: Small touch targets */
button {
padding: 4px 8px;
}
/* ✅ Good: Thumb-friendly targets */
button {
padding: 12px 24px; /* At least 44px tall */
min-height: 44px;
}
```
---
## Touch Target Guidelines
### Minimum Sizes (WCAG 2.5.5)
**Target Size (Enhanced - AAA):** 44 × 44 pixels minimum
**Target Size (Level AA):** 24 × 24 pixels minimum
**Best practice:** Use 48 × 48 pixels for comfortable tapping
**Testing procedure:**
1. Inspect interactive elements (buttons, links, form inputs)
2. Measure height and width using DevTools
3. Verify minimum 44px in at least one dimension
4. Check adequate spacing between adjacent targets (8px minimum)
**Common violations:**
```css
/* ❌ Bad: Too small to tap reliably */
.icon-button {
width: 24px;
height: 24px;
}
/* ✅ Good: Large enough for thumbs */
.icon-button {
width: 44px;
height: 44px;
/* Icon can be 24px, but padding makes target 44px */
}
```
**Examples of adequate touch targets:**
- Primary buttons: 48px height minimum
- Icon buttons: 44 × 44px minimum
- List items: 44px height minimum
- Navigation links: 44px height minimum
- Form inputs: 44px height minimum
---
## Text Readability Guidelines
### Minimum Font Sizes
**Body text:** 16px minimum (prevents mobile browser zoom)
**Small text:** 14px acceptable for captions/labels
**Never below 12px** (illegible on mobile)
### Line Length
**Optimal:** 45-75 characters per line
**Mobile:** 35-50 characters per line
**Avoid:** Text stretching full width on large screens
```css
/* ✅ Good: Constrained line length */
.content {
max-width: 65ch; /* ~65 characters */
margin: 0 auto;
}
```
### Line Height
**Body text:** 1.5-1.7 (WCAG recommends 1.5 minimum)
**Headings:** 1.2-1.4
**Small text:** 1.6-1.8 (more leading helps readability)
```css
/* ✅ Good: Readable line height */
body {
line-height: 1.6;
}
h1, h2, h3 {
line-height: 1.3;
}
```
---
## Navigation Patterns
### Desktop (1440px)
- Full horizontal navigation bar
- All menu items visible
- Dropdowns or mega menus for subpages
### Tablet (768px)
**Option A**: Simplified horizontal nav (fewer items)
**Option B**: Hamburger menu (mobile-style)
**Option C**: Horizontal scrolling nav
### Mobile (375px)
- Hamburger menu (☰) standard
- Drawer or full-screen menu overlay
- Bottom navigation bar (for apps)
**Common mistakes:**
- Desktop nav not collapsing on mobile (overflow)
- Hamburger icon too small (<44px)
- Menu drawer doesn't scroll when content overflows
- No visual indicator for current page
```html
<!-- ✅ Good: Responsive navigation -->
<nav class="navbar">
<button class="hamburger" aria-label="Menu" aria-expanded="false">
☰
</button>
<ul class="nav-menu">
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
<!-- ... -->
</ul>
</nav>
<style>
/* Desktop: Full nav */
@media (min-width: 769px) {
.hamburger { display: none; }
.nav-menu { display: flex; }
}
/* Mobile: Hamburger menu */
@media (max-width: 768px) {
.hamburger {
display: block;
min-width: 44px;
min-height: 44px;
}
.nav-menu {
display: none; /* Hidden by default */
position: fixed;
top: 0;
left: 0;
width: 80%;
height: 100vh;
background: white;
}
.nav-menu[aria-expanded="true"] {
display: block;
}
}
</style>
```
---
## Image Responsiveness
### Techniques
**1. Fluid images:**
```css
img {
max-width: 100%;
height: auto;
}
```
**2. Responsive images with srcset:**
```html
<img
srcset="
image-320w.jpg 320w,
image-768w.jpg 768w,
image-1440w.jpg 1440w
"
sizes="(max-width: 768px) 100vw, 768px"
src="image-768w.jpg"
alt="Descriptive alt text"
>
```
**3. Background images with media queries:**
```css
.hero {
background-image: url('hero-mobile.jpg');
}
@media (min-width: 769px) {
.hero {
background-image: url('hero-desktop.jpg');
}
}
```
**Common issues:**
- Fixed pixel widths breaking on small screens
- High-res images loading on mobile (slow)
- Images not maintaining aspect ratio
- Background images not scaling
---
## Form Responsiveness
### Mobile Form Best Practices
1. **Stack inputs vertically** (not side-by-side)
2. **Full-width inputs** on mobile
3. **Large touch targets** for buttons and checkboxes
4. **Appropriate input types** (triggers correct keyboard)
5. **Minimize typing** with dropdowns and defaults
```html
<!-- ✅ Good: Mobile-friendly form -->
<form class="responsive-form">
<!-- Full-width on mobile, half-width on desktop -->
<div class="form-group">
<label for="email">Email</label>
<input
type="email"
id="email"
autocomplete="email"
inputmode="email"
>
</div>
<!-- Large submit button -->
<button type="submit" class="submit-btn">
Submit
</button>
</form>
<style>
.form-group {
margin-bottom: 16px;
}
.form-group input {
width: 100%;
min-height: 44px;
padding: 12px;
font-size: 16px; /* Prevents iOS zoom */
}
.submit-btn {
width: 100%;
min-height: 48px;
font-size: 18px;
}
/* Desktop: 2-column form */
@media (min-width: 769px) {
.form-group input {
width: 50%;
}
.submit-btn {
width: auto;
padding: 12px 48px;
}
}
</style>
```
**Mobile input types:**
```html
<!-- Triggers email keyboard -->
<input type="email" inputmode="email">
<!-- Triggers numeric keyboard -->
<input type="tel" inputmode="tel">
<!-- Triggers number keyboard with decimals -->
<input type="number" inputmode="decimal">
<!-- Triggers URL keyboard -->
<input type="url" inputmode="url">
```
---
## Testing for Horizontal Scrolling
### How to identify:
**Visual inspection:**
1. Resize browser to 375px
2. Scroll down entire page
3. Look for content extending beyond viewport edge
**DevTools detection:**
```javascript
// Run in console to find overflow
document.body.scrollWidth > window.innerWidth
// Returns true if horizontal scroll exists
// Find offending elements
document.querySelectorAll('*').forEach(el => {
if (el.scrollWidth > window.innerWidth) {
console.log('Overflow element:', el);
}
});
```
### Common causes:
1. **Fixed-width elements:**
```css
/* ❌ Causes overflow */
.container { width: 1200px; }
/* ✅ Fix */
.container { max-width: 1200px; width: 100%; }
```
2. **Oversized images:**
```css
/* ❌ Image exceeds container */
img { width: 800px; }
/* ✅ Fix */
img { max-width: 100%; height: auto; }
```
3. **Viewport units:**
```css
/* ❌ 100vw includes scrollbar width */
.full-width { width: 100vw; }
/* ✅ Fix */
.full-width { width: 100%; }
```
4. **Negative margins:**
```css
/* ❌ Pushes content outside container */
.element { margin-left: -50px; }
/* ✅ Fix: Use relative positioning or adjust layout */
```
---
## Breakpoint Strategy
### Standard Breakpoints
```css
/* Mobile First Approach */
/* Base styles: Mobile (375px-767px) */
body {
font-size: 16px;
padding: 16px;
}
/* Tablet (768px-1023px) */
@media (min-width: 768px) {
body {
font-size: 18px;
padding: 24px;
}
}
/* Desktop (1024px+) */
@media (min-width: 1024px) {
body {
font-size: 18px;
padding: 32px;
}
}
/* Large Desktop (1440px+) */
@media (min-width: 1440px) {
body {
font-size: 20px;
padding: 48px;
}
}
```
### Tailwind CSS Breakpoints
```javascript
// tailwind.config.js
module.exports = {
theme: {
screens: {
'sm': '640px', // Small devices
'md': '768px', // Tablets
'lg': '1024px', // Laptops
'xl': '1280px', // Desktops
'2xl': '1536px', // Large desktops
}
}
}
```
---
## Quick Checklist
### Desktop (1440px)
- [ ] Layout optimized for wide screen
- [ ] Multi-column layouts work
- [ ] Images appropriately sized
- [ ] Navigation fully visible
- [ ] No excessive whitespace
### Tablet (768px)
- [ ] Layout adapts (columns reduce)
- [ ] Touch targets 44px minimum
- [ ] Navigation collapses or simplifies
- [ ] No overlapping elements
- [ ] Forms remain usable
### Mobile (375px)
- [ ] **No horizontal scrolling**
- [ ] Single-column layout
- [ ] Text 16px minimum
- [ ] Touch targets 44px minimum
- [ ] Hamburger menu works
- [ ] Forms stacked vertically
- [ ] Images scale to fit
---
## Triage Priorities
**[Blocker]:** Layout completely broken, horizontal scrolling on mobile
**[High]:** Touch targets too small, text unreadable, major alignment issues
**[Medium]:** Suboptimal space usage, minor wrapping issues
**[Nitpick]:** Slight spacing inconsistencies, aesthetic preferences
---
## Tools
- **Chrome DevTools**: Device Toolbar (Cmd+Shift+M)
- **Firefox Responsive Design Mode**: (Cmd+Opt+M)
- **BrowserStack**: Test on real devices
- **Playwright**: Automated viewport testing
- **Responsive Viewer**: Chrome extension for multiple viewports
---
**For more on responsive design patterns, see:**
- https://web.dev/responsive-web-design-basics/
- https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Responsive_Design
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |