migration wip

2025-12-29 18:18:48 +01:00
parent 292975299d
commit f86785bfb0
182 changed files with 30131 additions and 9321 deletions
--- a/RESPONSIVE_DESIGN_GUIDE.md
+++ b/RESPONSIVE_DESIGN_GUIDE.md
@@ -0,0 +1,410 @@
+# 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