klz-cables.com/RESPONSIVE_DESIGN_GUIDE.md

Responsive Design Guide - KLZ Cables

This guide documents the responsive design patterns and utilities implemented for the KLZ Cables Next.js application.

Overview

The responsive design system follows a mobile-first approach with comprehensive breakpoints, fluid typography, and optimized touch interactions.

Breakpoints

Breakpoint	Width	Use Case
xs	475px	Extra small phones
sm	640px	Small phones (landscape)
md	768px	Tablets (portrait)
lg	1024px	Tablets (landscape) / Small desktops
xl	1280px	Desktops
2xl	1400px	Large desktops
3xl	1600px	Very large desktops

Core Utilities

1. Responsive Utilities (lib/responsive.ts)

import { 
  getViewport, 
  checkBreakpoint, 
  resolveResponsiveProp,
  generateImageSizes,
  getResponsiveGrid,
  clamp
} from '@/lib/responsive';

// Get current viewport information
const viewport = getViewport();

// Check specific breakpoint
const isMobile = checkBreakpoint('mobile', viewport);

// Resolve responsive prop
const spacing = resolveResponsiveProp({
  mobile: '1rem',
  tablet: '1.5rem',
  desktop: '2rem'
}, viewport);

2. Responsive Components

Button Component

<Button 
  variant="primary"
  size="md"
  responsiveSize={{
    mobile: 'sm',
    tablet: 'md',
    desktop: 'lg'
  }}
  touchTarget={true}
>
  Click Me
</Button>

Container Component

<Container 
  maxWidth="xl"
  padding="responsive"
  safeArea={true}
>
  {content}
</Container>

Grid Component

<Grid 
  responsiveCols={{
    mobile: 1,
    tablet: 2,
    desktop: 3
  }}
  gap="responsive"
  stackMobile={true}
>
  {items}
</Grid>

FeaturedImage Component

<FeaturedImage
  src="/image.jpg"
  alt="Description"
  quality="auto"
  placeholder="blur"
  blurDataURL="data:image/..."
  responsiveSrc={{
    mobile: '/image-mobile.jpg',
    tablet: '/image-tablet.jpg',
    desktop: '/image-desktop.jpg'
  }}
/>

3. Responsive Layout Patterns

ResponsiveWrapper

<ResponsiveWrapper
  stackOnMobile={true}
  centerOnMobile={true}
  padding="responsive"
  container={true}
  maxWidth="xl"
>
  {content}
</ResponsiveWrapper>

ResponsiveGrid

<ResponsiveGrid
  columns={{
    mobile: 1,
    tablet: 2,
    desktop: 3,
    largeDesktop: 4
  }}
  gap="responsive"
  stackMobile={true}
>
  {items}
</ResponsiveGrid>

ResponsiveSection

<ResponsiveSection
  padding="responsive"
  maxWidth="6xl"
  centered={true}
  safeArea={true}
>
  {content}
</ResponsiveSection>

Mobile-First Design Principles

1. Touch Targets

• Minimum: 44px × 44px (WCAG requirement)
• Recommended: 48px × 48px
• Large: 56px × 56px (for important actions)

2. Typography

• Fluid typography using CSS clamp()
• Minimum font size: 16px (WCAG requirement)
• Optimized line heights: 1.4-1.6
• Mobile: tighter line height for readability

3. Spacing

• Mobile: smaller spacing (0.5-1rem)
• Tablet: medium spacing (1-1.5rem)
• Desktop: larger spacing (1.5-2rem)

4. Images

• Mobile: 75% quality, smaller dimensions
• Tablet: 85% quality, medium dimensions
• Desktop: 90% quality, full dimensions
• Lazy loading: enabled by default
• Placeholder blur: for better UX

5. Navigation

• Mobile: hamburger menu with full-screen drawer
• Tablet: hybrid approach
• Desktop: full navigation bar

Testing Utilities

1. Viewport Testing

import { ResponsiveTestUtils } from '@/lib/responsive-test';

// Simulate different viewports
ResponsiveTestUtils.simulateMobile();
ResponsiveTestUtils.simulateTablet();
ResponsiveTestUtils.simulateDesktop();

2. Validation

import { validateResponsiveDesign } from '@/lib/responsive-test';

const result = validateResponsiveDesign();
console.log(result.passed); // true/false
console.log(result.warnings); // []
console.log(result.errors); // []

3. Generate Report

import { generateResponsiveReport } from '@/lib/responsive-test';

const report = generateResponsiveReport();
console.log(report);

Responsive Checklist

Layout

• Content stacks properly on mobile (1 column)
• Grid layouts adapt to screen size (2-4 columns)
• No horizontal scrolling at any breakpoint
• Content remains within safe areas
• Padding and margins scale appropriately

Typography

• Text remains readable at all sizes
• Line height is optimized for mobile
• Headings scale appropriately
• No text overflow or clipping
• Font size meets WCAG guidelines (16px minimum)

Navigation

• Mobile menu is accessible (44px touch targets)
• Desktop navigation hides on mobile
• Menu items are properly spaced
• Active states are visible
• Back/forward navigation works

Images

• Images load with appropriate sizes
• Aspect ratios are maintained
• No layout shift during loading
• Lazy loading works correctly
• Placeholder blur is applied

Forms

• Input fields are 44px minimum touch target
• Labels remain visible
• Error messages are readable
• Form submits on mobile
• Keyboard navigation works

Performance

• Images are properly sized for viewport
• No unnecessary large assets on mobile
• Critical CSS is loaded
• Touch interactions are smooth
• No layout thrashing

Accessibility

• Touch targets are 44px minimum
• Focus indicators are visible
• Screen readers work correctly
• Color contrast meets WCAG AA
• Zoom is not restricted

Common Patterns

1. Mobile-First Grid

<Grid 
  cols={1} 
  sm={2} 
  md={3} 
  gap="md"
>
  {items}
</Grid>

2. Stacked to Row

<ResponsiveStack gap="md" wrap={false}>
  <div>Left</div>
  <div>Right</div>
</ResponsiveStack>

3. Hide on Mobile

<div className="hidden md:block">
  Desktop only content
</div>

4. Show on Mobile Only

<div className="block md:hidden">
  Mobile only content
</div>

Performance Optimization

1. Image Optimization

• Use quality="auto" for automatic optimization
• Implement responsive src sets
• Enable lazy loading
• Use blur placeholders

2. Component Optimization

• Use React.memo() for expensive components
• Implement proper key props
• Avoid unnecessary re-renders
• Use dynamic imports for heavy components

3. CSS Optimization

• Use Tailwind's JIT compiler
• Minimize custom CSS
• Leverage CSS containment
• Implement proper z-index layers

Browser Support

• iOS Safari: 12+
• Chrome: 90+
• Firefox: 88+
• Edge: 90+
• Samsung Internet: 13+

Accessibility Standards

• WCAG 2.1 AA compliance
• Keyboard navigation support
• Screen reader compatibility
• Color contrast 4.5:1 minimum
• Focus indicators visible

Testing Strategy

1. Manual Testing

• Test on real devices
• Check all breakpoints
• Verify touch interactions
• Test with screen readers

2. Automated Testing

• Use responsive test utilities
• Validate design rules
• Generate reports
• Monitor performance

3. Browser DevTools

• Use device emulation
• Test network throttling
• Check accessibility
• Audit performance

Migration Guide

From Static to Responsive

1. Update components with responsive props
2. Add breakpoint classes
3. Implement fluid typography
4. Optimize images for responsive
5. Test on all devices

Legacy Support

For older components:

// Wrap with ResponsiveWrapper
<ResponsiveWrapper stackOnMobile={true}>
  <LegacyComponent />
</ResponsiveWrapper>

Troubleshooting

Common Issues

1. Horizontal scrolling

   • Check for fixed widths
   • Verify container padding
   • Test with overflow-x: hidden

2. Layout shift

   • Add width/height to images
   • Use CSS aspect-ratio
   • Implement proper loading

3. Touch target too small

   • Increase padding
   • Use touch-target utilities
   • Check minimum 44px

4. Text too small

   • Use fluid typography
   • Check clamp() values
   • Verify base font size

Resources

• WCAG 2.1 Guidelines
• Next.js Image Optimization
• Tailwind Responsive Design
• Mobile First Design

---

Last Updated: 2025-12-29
Version: 1.0.0
Maintainer: KLZ Cables Development Team