Responsive Design Audit

Static Websites on cPanel

A site that works on desktop but breaks on mobile is not a finished site. Responsive design is not a feature — it is a baseline requirement. This audit verifies that every layout, component, and typographic decision adapts correctly across all screen sizes from 320px to 1920px, in both portrait and landscape orientations.

The goal is not pixel-perfect recreation of the desktop layout on every device. The goal is that every user, on every device, can access all content and complete all tasks without horizontal scrolling, broken layouts, or unusably small touch targets.

Severity Levels

Section 1 — Mobile-First Foundation

1.1 The Mobile-First Rule

Base styles must target mobile. Media queries must use min-width to enhance for larger screens — never max-width to override for smaller ones.

/* ❌ Desktop-first — overrides for mobile */
.card-grid {
  display: grid;
  grid-template-columns: 1fr 1fr 1fr;
  gap: var(--space-6);
}

@media (max-width: 768px) {
  .card-grid { grid-template-columns: 1fr; }
}

/* ✅ Mobile-first — enhances for larger screens */
.card-grid {
  display: grid;
  grid-template-columns: 1fr;
  gap: var(--space-4);
}

@media (min-width: 768px) {
  .card-grid {
    grid-template-columns: 1fr 1fr;
    gap: var(--space-6);
  }
}

@media (min-width: 1024px) {
  .card-grid { grid-template-columns: 1fr 1fr 1fr; }
}

Flag every max-width media query overriding a desktop-first base style.

Do not duplicate base styles in breakpoints — media queries contain only the differences:

/* ❌ Duplicating common styles */
@media (min-width: 768px) {
  .card {
    background: var(--bg-surface);   /* Same as base */
    border-radius: var(--radius-md); /* Same as base */
    padding: var(--space-6);         /* Different — belongs here */
  }
}

/* ✅ Only what changes */
@media (min-width: 768px) {
  .card { padding: var(--space-6); }
}

1.2 Breakpoint Scale

The project must use a consistent breakpoint scale throughout. No arbitrary breakpoints per component.

/* ✅ Standard breakpoint scale */
/* Base: Mobile — no media query needed */
@media (min-width: 640px)  { /* sm  — landscape phones  */ }
@media (min-width: 768px)  { /* md  — tablets           */ }
@media (min-width: 1024px) { /* lg  — laptops           */ }
@media (min-width: 1280px) { /* xl  — desktops          */ }
@media (min-width: 1536px) { /* 2xl — large desktops    */ }

Flag one-off breakpoints like @media (min-width: 850px) — these indicate a layout problem that should be solved differently, not with a custom breakpoint.

Section 2 — Fluid Typography and Spacing

2.1 Fluid Typography with clamp()

Fixed font sizes create abrupt jumps at breakpoints. clamp() creates smooth scaling. The value must always include rem — viewport units alone ignore browser font preferences.

/* ❌ Viewport unit only — ignores user font preferences */
h1 { font-size: 5vw; }

/* ❌ Fixed sizes with abrupt breakpoint jumps */
h1 { font-size: 2rem; }
@media (min-width: 768px) { h1 { font-size: 3rem; } }

/* ✅ Fluid scale — rem anchored, smooth scaling */
:root {
  --text-sm:   clamp(0.875rem, 0.8rem  + 0.375vw, 1rem);
  --text-base: clamp(1rem,     0.9rem  + 0.5vw,   1.125rem);
  --text-lg:   clamp(1.125rem, 1rem    + 0.625vw,  1.25rem);
  --text-xl:   clamp(1.25rem,  1rem    + 1.25vw,   1.5rem);
  --text-2xl:  clamp(1.5rem,   1.25rem + 1.25vw,   2rem);
  --text-3xl:  clamp(1.875rem, 1.5rem  + 1.875vw,  2.5rem);
  --text-4xl:  clamp(2.25rem,  1.75rem + 2.5vw,    3.5rem);
}

Flag headings with hardcoded px font sizes. Flag clamp() values using only vw without rem.

2.2 Typography Readability Rules

What to check:

• Body text minimum 1rem (16px) on mobile
• Form inputs font-size: 1rem — prevents iOS auto-zoom on focus
• Secondary text minimum 0.875rem (14px)
• line-height: 1.5 on body text, 1.2 on headings
• max-width: 65ch on paragraph text for optimal reading width

2.3 Fluid Spacing with clamp()

:root {
  --space-4:  clamp(0.5rem,  0.4rem + 0.5vw,  0.75rem);
  --space-8:  clamp(1rem,    0.8rem + 1vw,    1.5rem);
  --space-12: clamp(1.5rem,  1.2rem + 1.5vw,  2.5rem);
  --space-16: clamp(2rem,    1.5rem + 2.5vw,  4rem);
  --space-24: clamp(3rem,    2rem   + 5vw,     6rem);
}

Flag hardcoded px padding and margin on section-level elements that should scale.

Section 3 — Viewport Units

100vh on mobile includes the browser UI (address bar). When visible, content gets cut off.

/* ❌ Causes overflow on mobile browsers */
.hero { height: 100vh; }

/* ✅ With fallback for older browsers */
.hero {
  height: 100vh;   /* Fallback */
  height: 100dvh;  /* Dynamic — accounts for browser UI */
}

Flag every 100vh on full-screen sections without a dvh override.

Section 4 — Layout Adaptability

4.1 Containers

/* ✅ Fluid container pattern */
.container {
  width: 90%;
  max-width: 1200px;
  margin-inline: auto;
}

Flag containers with fixed px widths. Flag containers without max-width.

4.2 CSS Grid Responsive Patterns

/* ✅ Auto-fit — wraps naturally without media queries */
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(300px, 100%), 1fr));
  gap: var(--space-6);
}

4.3 Flexbox Wrapping

/* ✅ Wraps with minimum item width */
.features {
  display: flex;
  flex-wrap: wrap;
  gap: var(--space-6);
}

.features__item {
  flex: 1 1 280px;
}

Flag flex containers without flex-wrap: wrap that could overflow on mobile.

4.4 Content Priority on Mobile

Secondary content like sidebars should not appear before main content on mobile. Use order to reorder without changing DOM.

4.5 Horizontal Overflow

The most disruptive mobile failure — forces users to scroll sideways.

/* ✅ Global overflow protection */
html, body { overflow-x: hidden; }

img { max-width: 100%; height: auto; }

p, li, td, h1, h2, h3 {
  overflow-wrap: break-word;
  word-break: break-word;
}

.table-wrapper { width: 100%; overflow-x: auto; }

Flag any element with fixed px width wider than 320px without max-width: 100%. Flag long strings without overflow-wrap.

Section 5 — Navigation

Mobile navigation must have a toggle button with correct ARIA, update aria-expanded on click, and use hidden attribute for open/close state.

Full navigation pattern with HTML, CSS, and JS: see references/responsive-patterns.md

What to check:

• Toggle button with aria-expanded, aria-controls, and aria-label
• Toggle updates aria-expanded and hidden on click
• Desktop navigation hidden on mobile via display: none
• Mobile menu is keyboard accessible
• Active page indicated in mobile navigation

Section 6 — Touch Targets and Interactions

6.1 Touch Target Size

All interactive elements must be minimum 44×44px on mobile with at least 8px spacing between them. Small icons can expand their tap area with ::after pseudo-element.

Full touch target code examples: see references/responsive-patterns.md

Flag every interactive element below 44px height on mobile. Flag interactive elements with less than 8px spacing.

6.2 Hover States — Mobile Compatibility

On mobile there is no hover. Hover effects get stuck after a tap.

/* ❌ Hover stuck on mobile */
.card:hover {
  transform: translateY(-4px);
  box-shadow: var(--shadow-lg);
}

/* ✅ Hover only on devices that support it */
@media (hover: hover) {
  .card:hover {
    transform: translateY(-4px);
    box-shadow: var(--shadow-lg);
  }
}

Flag all :hover rules not wrapped in @media (hover: hover) when they involve transforms or state changes that could get stuck on touch.

Section 7 — Viewport Configuration

7.1 Meta Viewport Tag

Flag user-scalable=no — prevents zoom, accessibility violation. Content must be usable at 200% zoom.

7.2 Safe Areas for Notched Devices

Fixed elements at the bottom must respect the iPhone home indicator and notch area. Requires viewport-fit=cover in meta viewport.

.bottom-nav {
  position: fixed;
  bottom: 0;
  padding-bottom: max(1rem, env(safe-area-inset-bottom));
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
}

Flag fixed bottom elements without env(safe-area-inset-bottom).

Section 8 — Responsive Images at Layout Level

Note: Image format, srcset, sizes, loading priority, fetchpriority, object-fit, and decoding are covered in Audit 04 — Performance. This section covers only how images integrate with responsive layouts.

/* ✅ Global image rule */
img { max-width: 100%; height: auto; display: block; }

/* ✅ Hero image fills viewport responsively */
.hero__image {
  width: 100%;
  height: 60vh;
  height: 60dvh;
  object-fit: cover;
}

/* ✅ Card images maintain aspect ratio */
.card__image {
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}

Flag images with fixed px widths exceeding mobile viewport. Flag hero images that distort on mobile.

Section 9 — Common Responsive Failures

Check for each explicitly — the most frequently occurring problems:

• Fixed width breaking mobile: width: 800px → use width: 100%; max-width: 800px;
• Input font size triggering iOS zoom: font-size: 14px → use font-size: 1rem
• Aspect ratio distortion: height: 200px → use aspect-ratio: 16/9; object-fit: cover
• Z-index stacking on mobile: fixed navbar overlapping skip link, mobile menu below other fixed elements, modals exceeding viewport
• Hover states stuck on mobile: covered in Section 6.2

Testing Viewports

Verify at these specific sizes, in both portrait and landscape:

Audit Output Format

Responsive Design Audit — [Project Name]
Date: [Date]
Tested viewports: 320px, 375px, 414px, 768px, 1024px, 1280px, 1440px
Orientations tested: Portrait and Landscape
Summary

Critical issues: X
High priority: X
Medium priority: X
Low priority: X
Most affected breakpoint: [mobile / tablet / desktop]
Overall: [Fully responsive / Partially responsive / Broken on mobile]

Critical Issues
[Issue title]

Viewport affected: [320px–767px / 768px–1023px / 1024px+ / all]
Orientation: [Portrait / Landscape / Both]
File: [filename and line]
Issue: [What breaks and how it affects the user]
Fix: [Specific correction with code example]

High Priority
[Same format]
Medium Priority
[Same format]
Low Priority
[Same format]
Recommended Fix Order

Horizontal overflow — affects all content on all pages
Navigation — affects all pages
Input font sizes — iOS zoom breaks layouts
Touch targets — affects all interactions
Typography and spacing — affects readability
Hover states — affects mobile polish
Layout refinements — affects visual quality

Full quick-reference checklist: see references/checklist.md