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`)

```typescript
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
```tsx
<Button 
  variant="primary"
  size="md"
  responsiveSize={{
    mobile: 'sm',
    tablet: 'md',
    desktop: 'lg'
  }}
  touchTarget={true}
>
  Click Me
</Button>
```

#### Container Component
```tsx
<Container 
  maxWidth="xl"
  padding="responsive"
  safeArea={true}
>
  {content}
</Container>
```

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

#### FeaturedImage Component
```tsx
<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
```tsx
<ResponsiveWrapper
  stackOnMobile={true}
  centerOnMobile={true}
  padding="responsive"
  container={true}
  maxWidth="xl"
>
  {content}
</ResponsiveWrapper>
```

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

#### ResponsiveSection
```tsx
<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
```typescript
import { ResponsiveTestUtils } from '@/lib/responsive-test';

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

### 2. Validation
```typescript
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
```typescript
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
```tsx
<Grid 
  cols={1} 
  sm={2} 
  md={3} 
  gap="md"
>
  {items}
</Grid>
```

### 2. Stacked to Row
```tsx
<ResponsiveStack gap="md" wrap={false}>
  <div>Left</div>
  <div>Right</div>
</ResponsiveStack>
```

### 3. Hide on Mobile
```tsx
<div className="hidden md:block">
  Desktop only content
</div>
```

### 4. Show on Mobile Only
```tsx
<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:
```tsx
// 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](https://www.w3.org/WAI/WCAG21/quickref/)
- [Next.js Image Optimization](https://nextjs.org/docs/api-reference/next/image)
- [Tailwind Responsive Design](https://tailwindcss.com/docs/responsive-design)
- [Mobile First Design](https://www.smashingmagazine.com/2016/01/progressive-enhancement-mobile-first/)

---

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