Responsive Design Auditor

Audit web applications for responsive design issues across breakpoints, identifying layout problems, touch target violations, and accessibility gaps on mobile, tablet, and desktop viewports.

When to Use This Template

Choose Responsive Design Auditor when:

• Your site looks broken on mobile devices or specific screen sizes
• You need to verify responsive behavior across standard breakpoints
• Touch targets, font sizes, or spacing need accessibility compliance checks
• A design review requires systematic viewport-by-viewport analysis

Consider alternatives when:

• You need automated visual regression testing (use Percy or Chromatic)
• You need device-specific browser testing (use BrowserStack or Sauce Labs)
• Your design issues are purely CSS bugs, not responsive layout problems

Quick Start

Copy
# .claude/skills/responsive-design-auditor.yml
name: responsive-design-auditor
description: Audit responsive design across viewports and breakpoints
prompt: |
  Audit the specified pages for responsive design issues.

  Check across these breakpoints:
  - Mobile: 320px, 375px, 414px
  - Tablet: 768px, 1024px
  - Desktop: 1280px, 1440px, 1920px

  Verify:
  1. No horizontal scrolling at any breakpoint
  2. Touch targets >= 44x44px on mobile
  3. Font sizes >= 16px for body text on mobile
  4. Images scale properly without overflow
  5. Navigation is accessible on all viewports
  6. Content hierarchy adapts appropriately

  Report issues with specific breakpoints and CSS fixes.

Example invocation:

Copy
claude "Audit the homepage and pricing page for responsive issues"

Sample audit output:

Responsive Design Audit — Homepage
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Score: 74/100

Issues Found: 8

[CRITICAL] 320px — Hero text overflows container
  Element: .hero-title
  Fix: Add `overflow-wrap: break-word` and reduce font-size
  at 320px from 3rem to 1.75rem

[HIGH] 375px — CTA buttons too small for touch (32x28px)
  Element: .cta-button
  Fix: Set min-height: 44px; min-width: 44px; padding: 12px 24px;

[MEDIUM] 768px — Three-column grid does not collapse
  Element: .feature-grid
  Fix: Add `grid-template-columns: 1fr` below 768px

[LOW] 1920px — Content stretches too wide (max-width missing)
  Element: .content-wrapper
  Fix: Add `max-width: 1280px; margin: 0 auto;`

Core Concepts

Breakpoint Audit Matrix

Viewport	Width	Primary Concern	Common Issues
Small phone	320px	Content overflow	Text wrapping, horizontal scroll
Phone	375px	Touch targets	Buttons too small, links too close
Large phone	414px	Layout adaptation	Grid collapse, image sizing
Tablet portrait	768px	Navigation shift	Menu transition, sidebar behavior
Tablet landscape	1024px	Layout efficiency	Wasted space, awkward grids
Desktop	1280px	Content width	Max-width constraints
Large desktop	1920px	Scaling	Ultra-wide layout, spacing

Automated CSS Audit Checks

Copy
// Check for common responsive issues in stylesheets
function auditResponsiveCSS(cssContent) {
  const issues = [];

  // Check for fixed widths that break on mobile
  const fixedWidths = cssContent.match(/width:\s*\d{4,}px/g);
  if (fixedWidths) {
    issues.push({
      severity: 'high',
      issue: 'Fixed pixel widths over 1000px',
      matches: fixedWidths,
      fix: 'Use max-width with percentage or viewport units'
    });
  }

  // Check for missing viewport meta (in HTML)
  // <meta name="viewport" content="width=device-width, initial-scale=1">

  // Check touch target sizes
  const smallTargets = cssContent.match(
    /\.(btn|button|link|nav-item)[^{]*\{[^}]*(height:\s*[0-3]\dpx|padding:\s*[0-4]px)/g
  );
  if (smallTargets) {
    issues.push({
      severity: 'critical',
      issue: 'Touch targets may be smaller than 44x44px',
      fix: 'Ensure all interactive elements have min 44x44px touch area'
    });
  }

  // Check for media query coverage
  const breakpoints = cssContent.match(/@media[^{]+/g) || [];
  const coveredWidths = breakpoints.map(bp => {
    const match = bp.match(/(\d+)px/);
    return match ? parseInt(match[1]) : null;
  }).filter(Boolean);

  const requiredBreakpoints = [480, 768, 1024, 1280];
  const missing = requiredBreakpoints.filter(bp =>
    !coveredWidths.some(cw => Math.abs(cw - bp) < 50)
  );

  if (missing.length > 0) {
    issues.push({
      severity: 'medium',
      issue: `Missing media queries for breakpoints: ${missing.join(', ')}px`,
      fix: 'Add responsive styles for missing viewport ranges'
    });
  }

  return issues;
}

Tailwind CSS Responsive Patterns

Copy
<!-- Common responsive pattern fixes -->

<!-- Grid: 1 column mobile, 2 tablet, 3 desktop -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  <!-- cards -->
</div>

<!-- Typography: Scale with viewport -->
<h1 class="text-2xl sm:text-3xl md:text-4xl lg:text-5xl">
  Responsive Heading
</h1>

<!-- Navigation: Hamburger on mobile, inline on desktop -->
<nav class="flex items-center justify-between">
  <div class="hidden md:flex space-x-6">
    <!-- Desktop nav links -->
  </div>
  <button class="md:hidden p-2 min-h-[44px] min-w-[44px]">
    <!-- Hamburger icon -->
  </button>
</nav>

<!-- Images: Responsive with aspect ratio -->
<div class="relative w-full aspect-video">
  <img
    src="/hero.jpg"
    alt="Hero"
    class="absolute inset-0 w-full h-full object-cover"
    sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
  />
</div>

Configuration

Option	Type	Default	Description
breakpoints	number[]	[320, 375, 768, 1024, 1280, 1920]	Viewport widths to audit
touchTargetMin	number	44	Minimum touch target size in px
minFontSize	number	16	Minimum body font size on mobile
maxContentWidth	number	1280	Maximum content width before centering
checkAccessibility	boolean	true	Include WCAG responsive checks
framework	string	"auto"	CSS framework: tailwind, bootstrap, vanilla

Best Practices

1. Design mobile-first, then expand — Write base styles for the smallest viewport, then use min-width media queries to add complexity for larger screens. This prevents the common pattern of building for desktop first and then scrambling to make it work on mobile.

2. Use relative units for spacing and typography — Replace fixed pixel values with rem, em, or clamp() for font sizes and spacing. clamp(1rem, 2.5vw, 2rem) creates fluid typography that scales smoothly between breakpoints without abrupt jumps.

3. Test with real devices, not just browser resize — Browser dev tools simulate viewport width but miss touch interaction, actual font rendering, and device-specific browser behaviors. Test on at least one physical iOS and Android device for every major change.

4. Ensure 44x44px minimum touch targets — WCAG 2.5.5 requires interactive elements to have at least a 44x44 CSS pixel touch area. This applies to buttons, links, form inputs, and any clickable element. Add padding rather than increasing the visual size if the design requires small elements.

5. Avoid horizontal scrolling at every breakpoint — The single most disruptive responsive issue is horizontal overflow causing side-scrolling. Set overflow-x: hidden on the body as a safety net, but fix the root cause — typically a fixed-width element or an element with negative margins exceeding its container.

Common Issues

Content overflows at 320px viewport — Long words (URLs, email addresses, technical terms) break out of containers on very small screens. Apply overflow-wrap: break-word and word-break: break-word to text containers. For code blocks, use overflow-x: auto to add a horizontal scrollbar within the block rather than the page.

Navigation menu does not transition smoothly to mobile — The desktop navigation disappears at a breakpoint but the mobile hamburger menu does not appear, leaving users with no navigation. Ensure the hamburger trigger element becomes visible at the exact breakpoint where desktop nav items are hidden. Test the transition at the exact breakpoint width, not just well above and below it.

Images cause layout shift on load — Images without explicit width and height attributes cause the layout to jump when they load, especially on slower mobile connections. Always set width and height attributes on <img> tags (the browser uses them to calculate aspect ratio) or use the CSS aspect-ratio property on the container to reserve space.