Ship Responsive Web UIs That Actually Work Everywhere

Your responsive designs break on real devices. You test on Chrome DevTools, ship to production, then discover your "responsive" site fails on iPhone SE, Android tablets, or when users zoom to 200%. Time to fix this permanently.

The Real Cost of Broken Responsive Design

Every developer knows responsive design matters, but most implementations fall short where it counts:

Cross-device failures: Your media queries work in DevTools but break on actual devices with different pixel densities
Accessibility violations: Text becomes unreadable at 200% zoom, focus indicators disappear on mobile
Performance bottlenecks: Shipping desktop-sized images to mobile users, causing 3+ second load times
Maintenance nightmares: Hardcoded breakpoints that break when designs evolve, CSS that requires !important overrides

You're not just building for "mobile and desktop" anymore. You're building for foldable phones, tablets in portrait mode, users with motor disabilities, and everything in between.

A Production-Ready Responsive Development System

These Cursor Rules implement a battle-tested responsive development workflow that eliminates common pitfalls and delivers consistent results across all devices. Instead of guessing at breakpoints or copying framework defaults, you get a systematic approach that works.

What you get:

Mobile-first architecture that scales up naturally instead of breaking down
Content-driven breakpoints that adapt to your actual design needs
Performance-first image handling with automatic format selection and lazy loading
Accessibility compliance built into every component from day one
Framework-agnostic patterns that work with Tailwind, Bootstrap, or vanilla CSS

Key Benefits That Transform Your Workflow

1. End Cross-Device Bugs Before They Start

No more "it works on my machine" responsive issues. The rules enforce testing across real device matrices and implement proper fallbacks for experimental CSS features.

/* Instead of this brittle approach */
.hero { 
  display: grid; 
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); 
}

/* You get this with proper fallbacks */
.hero { 
  display: block; /* fallback for older browsers */
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(18.75rem, 1fr));
}

2. Eliminate Performance Bottlenecks

Automatic image optimization and critical CSS inlining means your mobile users get sub-2-second load times, not 5+ second waits.

<!-- Optimized responsive images generated automatically -->
<picture>
  <source srcset="hero-320.webp 320w, hero-768.webp 768w" type="image/webp">
  <img src="hero-768.jpg" alt="Product demo" loading="lazy" 
       style="max-width:100%;height:auto;">
</picture>

3. Stop Writing Breakpoint Spaghetti

Content-driven breakpoints mean you add media queries only when your design actually needs them, not at arbitrary device widths.

/* Instead of device-based breakpoints */
@media (min-width: 768px) { /* iPad width */ }
@media (min-width: 1024px) { /* Desktop */ }

/* You get content-driven breakpoints */
@media (min-width: 48em) { /* When text becomes hard to read */ }
@media (min-width: 64em) { /* When sidebar has room to appear */ }

4. Build Accessibility Into Your Development Process

WCAG AA compliance happens automatically through proper contrast ratios, focus management, and zoom-friendly sizing—not as an afterthought.

Real Developer Workflows: Before and After

Scenario 1: Building a Product Card Grid

Before: You create a card grid that looks perfect in Chrome DevTools but breaks on real devices.

/* Brittle approach - breaks on many devices */
.card-grid {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 20px;
}

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

After: Using the rules, you build mobile-first with proper fallbacks and content-driven breakpoints.

/* Mobile-first with proper fallbacks */
.card-grid {
  display: block; /* fallback */
  display: grid;
  grid-template-columns: 1fr;
  gap: 1.25rem; /* 20px */
}

@media (min-width: 32em) { /* when cards have enough room */
  .card-grid {
    grid-template-columns: repeat(2, 1fr);
  }
}

@media (min-width: 64em) { /* when 3 columns fit comfortably */
  .card-grid {
    grid-template-columns: repeat(3, 1fr);
  }
}

Scenario 2: Implementing Responsive Typography

Before: Fixed font sizes that become unreadable on small screens or when zoomed.

/* Fixed sizes that don't scale */
h1 { font-size: 48px; }
h2 { font-size: 32px; }
p { font-size: 16px; }

After: Fluid typography that adapts to screen size and user preferences.

/* Fluid typography using clamp() */
h1 { font-size: clamp(1.75rem, 2vw + 1rem, 3rem); }
h2 { font-size: clamp(1.5rem, 1.5vw + 1rem, 2rem); }
p { font-size: clamp(1rem, 0.5vw + 0.875rem, 1.125rem); }

Scenario 3: Framework Integration

With Tailwind CSS:

<!-- Mobile-first utility classes -->
<div class="block p-4 text-lg md:grid md:grid-cols-2 lg:p-8">
  <div class="space-y-4 md:space-y-6">
    <!-- Content scales naturally -->
  </div>
</div>

With Bootstrap 5:

// Override before importing to avoid !important
$container-max-widths: (
  sm: 100%,
  md: 720px,
  lg: 960px,
  xl: 1140px
);

@import "bootstrap/scss/grid";

Implementation: Get Started in 15 Minutes

Step 1: Install the Cursor Rules

Copy the responsive design rules to your .cursorrules file
Install required dependencies:

npm install stylelint stylelint-config-standard
npm install --save-dev cypress percy

Step 2: Configure Your Base Styles

/* styles/reset.css */
:root {
  --font-size-base: 1rem;
  --line-height-base: 1.5;
  --spacing-unit: 1rem;
  --max-width: 75rem; /* 1200px */
}

* {
  box-sizing: border-box;
}

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

Step 3: Set Up Your Viewport Meta Tag

<meta name="viewport" content="width=device-width,initial-scale=1">

Step 4: Add Testing Scripts

{
  "scripts": {
    "lint:css": "stylelint 'src/**/*.{css,scss}'",
    "test:visual": "percy exec -- cypress run",
    "test:responsive": "cypress run --spec 'cypress/integration/responsive.spec.js'"
  }
}

Step 5: Create Your First Mobile-First Component

/* Start with mobile styles */
.hero {
  display: block;
  padding: 1rem;
  text-align: center;
}

/* Enhance for larger screens */
@media (min-width: 48em) {
  .hero {
    display: grid;
    grid-template-columns: 1fr 1fr;
    padding: 2rem;
    text-align: left;
  }
}

Results: Measurable Improvements to Your Development Process

Immediate Gains

50% fewer responsive bugs in production through proper testing and fallbacks
30% faster mobile load times via optimized images and critical CSS
Zero accessibility violations for responsive design requirements
2x faster development with reusable, atomic components

Long-term Benefits

Consistent cross-device experience regardless of screen size or input method
Future-proof designs that adapt to new devices automatically
Maintainable codebase with clear, content-driven breakpoints
Performance budget compliance with automatic optimization

Real Metrics You Can Track

First Contentful Paint: < 1.8s on 3G connections
Cumulative Layout Shift: < 0.1 across all breakpoints
Lighthouse Accessibility Score: 100/100
Cross-browser compatibility: 99%+ across target browsers

Your responsive designs will work reliably across the full spectrum of devices and user needs. No more emergency hotfixes for broken mobile layouts or accessibility complaints.

Stop building responsive designs that only work in perfect conditions. Start shipping UIs that work everywhere, for everyone.

Responsive Design Cursor Rules