@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/frontend-review.md

@@ -0,0 +1,783 @@
+# Frontend Code Review - Complete Guide
+
+Comprehensive frontend code review covering UI anomaly detection, interaction quality, performance optimization, and cross-browser compatibility.
+
+---
+
+## 🎯 Frontend Review Philosophy
+
+### Core Perspective: Visual → Interaction → Performance → Code
+
+Frontend CR ensures high-quality user experience by evaluating from multiple dimensions, **simulating real user scenarios** across devices, browsers, and network conditions.
+
+```
+Review Dimensions:
+┌─────────────────────────────────────────┐
+│  Dimension 1: Visual Quality            │
+│  - UI consistency with design           │
+│  - Layout correctness                   │
+│  - Responsive behavior                  │
+└─────────────────────────────────────────┘
+         ↓
+┌─────────────────────────────────────────┐
+│  Dimension 2: Interaction Quality       │
+│  - Smooth animations                    │
+│  - Responsive feedback                  │
+│  - Error state handling                 │
+└─────────────────────────────────────────┘
+         ↓
+┌─────────────────────────────────────────┐
+│  Dimension 3: Performance               │
+│  - Core Web Vitals                      │
+│  - Bundle size                          │
+│  - Runtime efficiency                   │
+└─────────────────────────────────────────┘
+         ↓
+┌─────────────────────────────────────────┐
+│  Dimension 4: Code Quality              │
+│  - Component architecture               │
+│  - State management                     │
+│  - Error handling                       │
+└─────────────────────────────────────────┘
+```
+
+### Review Time Allocation
+
+| PR Size | Files | Recommended Time | Focus |
+|---------|-------|------------------|-------|
+| Small | <5 | 15-30 min | Visual + Code |
+| Medium | 5-15 | 30-60 min | All dimensions |
+| Large | 15-30 | 1-2 hours | All + cross-browser |
+| XL | >30 | 2+ hours | Consider splitting |
+
+---
+
+## 🛠️ Mandatory Pre-Review Scans
+
+### Automated Tool Checklist
+
+```bash
+# Style & Code Quality
+npx stylelint "**/*.css" --fix        # CSS linting
+npx eslint . --max-warnings 0         # JS/TS linting
+npx prettier --check .                # Formatting
+
+# Type Checking
+npx tsc --noEmit                      # TypeScript strict mode
+
+# Security
+npm audit                             # Dependency vulnerabilities
+npx snyk test                         # Deep security scan
+
+# Performance
+npx lighthouse-ci                     # Lighthouse CI (target: >90)
+npx bundlesize                        # Bundle size check
+
+# Accessibility
+npx axe-cli http://localhost:3000     # Accessibility scan
+```
+
+### Tool Configuration Requirements
+
+```markdown
+## Required Tool Configurations
+
+### ESLint
+- [ ] Strict mode enabled
+- [ ] React/Vue plugin configured
+- [ ] Import order rules
+- [ ] No unused vars/imports
+
+### TypeScript
+- [ ] strict: true
+- [ ] noImplicitAny: true
+- [ ] strictNullChecks: true
+
+### Stylelint
+- [ ] Order rules
+- [ ] No !important (or limited)
+- [ ] Color format consistency
+
+### Lighthouse Thresholds
+| Metric | Minimum | Target |
+|--------|---------|--------|
+| Performance | 80 | 90+ |
+| Accessibility | 90 | 100 |
+| Best Practices | 90 | 100 |
+| SEO | 90 | 100 |
+```
+
+---
+
+## 👁️ UI Anomaly Detection
+
+### Visual Inspection Checklist
+
+```markdown
+## Visual Review Steps
+
+### Step 1: Browser DevTools Setup
+1. Open Elements panel
+2. Enable device toolbar (responsive mode)
+3. Open Computed styles panel
+4. Enable Rendering > Paint flashing (optional)
+
+### Step 2: Layout Inspection
+| Check | Tool | Issue Type |
+|-------|------|------------|
+| Box model | DevTools Elements | Margin collapse, padding issues |
+| Flexbox alignment | Flexbox inspector | Justify/align issues |
+| Grid layout | Grid inspector | Track sizing, gaps |
+| Overflow | Scroll to edges | Hidden content, scrollbars |
+
+### Step 3: Spacing & Typography
+| Check | Expected | Actual | Status |
+|-------|----------|--------|--------|
+| Font family | Inter | Inter | ✅ |
+| Font size H1 | 32px | 30px | ⚠️ |
+| Line height body | 1.5 | 1.5 | ✅ |
+| Paragraph margin | 16px | 24px | ⚠️ |
+| Button padding | 12px 24px | 12px 24px | ✅ |
+```
+
+### Design-Code Comparison
+
+```markdown
+## Design vs Implementation Matrix
+
+### Figma/Sketch Comparison
+| Element | Design | Code | Match |
+|---------|--------|------|-------|
+| Primary color | #2563EB | #2563EB | ✅ |
+| Border radius | 8px | 6px | ⚠️ |
+| Shadow | 0 4px 6px rgba(0,0,0,0.1) | 0 2px 4px rgba(0,0,0,0.1) | ⚠️ |
+| Icon size | 24px | 20px | ❌ |
+
+### Spacing System
+| Design Token | Value | Used Consistently |
+|--------------|-------|-------------------|
+| spacing-xs | 4px | ✅ |
+| spacing-sm | 8px | ✅ |
+| spacing-md | 16px | ⚠️ (12px in some places) |
+| spacing-lg | 24px | ✅ |
+```
+
+### Responsive Design Verification
+
+```markdown
+## Responsive Breakpoints Test
+
+### Test Devices
+| Device | Width | Height | Test Status |
+|--------|-------|--------|-------------|
+| iPhone SE | 375px | 667px | ✅ |
+| iPhone 12 | 390px | 844px | ✅ |
+| iPad | 768px | 1024px | ⚠️ Layout issue |
+| iPad Pro | 1024px | 1366px | ✅ |
+| Desktop | 1440px | 900px | ✅ |
+| Wide screen | 1920px | 1080px | ✅ |
+
+### Common Responsive Issues
+| Issue | Breakpoint | Fix |
+|-------|------------|-----|
+| Text overflow | <375px | Add text-wrap or font-size reduction |
+| Sidebar overlap | 768px-1024px | Adjust breakpoint or add collapsible |
+| Images stretch | >1440px | Add max-width |
+```
+
+---
+
+## 🎭 Interaction Quality Review
+
+### Animation & Micro-interaction
+
+```markdown
+## Animation Review
+
+### Performance Metrics
+| Animation | FPS | Duration | Easing | Status |
+|-----------|-----|----------|--------|--------|
+| Page transition | 60 | 300ms | ease-out | ✅ |
+| Button hover | 58 | 150ms | ease | ✅ |
+| Modal open | 45 | 400ms | ease-in-out | ⚠️ Jank |
+| Infinite scroll | 55 | N/A | N/A | ⚠️ Optimize |
+
+### Animation Best Practices
+- [ ] Use transform/opacity only (compositor-friendly)
+- [ ] Avoid animating width/height/top/left
+- [ ] Use will-change sparingly
+- [ ] Respect prefers-reduced-motion
+```
+
+```css
+/* ❌ Janky animation - triggers layout */
+.card {
+  transition: width 0.3s, height 0.3s;
+}
+.card:hover {
+  width: 120%;
+  height: 120%;
+}
+
+/* ✅ Smooth animation - compositor only */
+.card {
+  transition: transform 0.3s ease-out;
+}
+.card:hover {
+  transform: scale(1.1);
+}
+
+/* ✅ Respect reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    transition: none;
+  }
+}
+```
+
+### Loading State Review
+
+```markdown
+## Loading State Checklist
+
+### Initial Load
+- [ ] Skeleton screen implemented
+- [ ] Above-the-fold content prioritized
+- [ ] Critical CSS inlined
+- [ ] Fonts preloaded
+
+### Data Fetching
+- [ ] Loading indicators visible
+- [ ] Partial content display (progressive)
+- [ ] Timeout handling
+- [ ] Error state fallback
+
+### Lazy Loading
+| Resource | Strategy | Threshold | Status |
+|----------|----------|-----------|--------|
+| Images below fold | Intersection Observer | 200px | ✅ |
+| Heavy components | Dynamic import | On route | ✅ |
+| Comments section | Scroll into view | 100px | ✅ |
+| Ads | Viewport entry | 0px | ⚠️ CLS risk |
+```
+
+### Focus & Keyboard Navigation
+
+```markdown
+## Focus Management Review
+
+### Tab Order Verification
+| Element | Expected Order | Actual Order | Status |
+|---------|----------------|--------------|--------|
+| Logo link | 1 | 1 | ✅ |
+| Nav items | 2-5 | 2-5 | ✅ |
+| Search input | 6 | 8 | ❌ Wrong order |
+| Main content | 7+ | 6 | ❌ Skip link missing |
+
+### Focus Visibility
+- [ ] :focus-visible styles applied
+- [ ] Focus ring contrast sufficient (3:1 minimum)
+- [ ] No outline: none without replacement
+- [ ] Modal focus trap implemented
+```
+
+```css
+/* ❌ Removes focus indicator */
+button:focus {
+  outline: none;
+}
+
+/* ✅ Custom focus indicator */
+button:focus-visible {
+  outline: 2px solid var(--color-focus);
+  outline-offset: 2px;
+}
+
+/* ✅ Skip link for keyboard users */
+.skip-link {
+  position: absolute;
+  top: -100%;
+  left: 0;
+  background: var(--color-primary);
+  color: white;
+  padding: 8px 16px;
+  z-index: 100;
+}
+.skip-link:focus {
+  top: 0;
+}
+```
+
+---
+
+## ⚡ Performance Deep Dive
+
+### Memory Leak Prevention
+
+#### Module-Level Variables (Global Cache)
+Long-lived SPAs often accumulate data in module-level variables (outside components).
+
+```typescript
+// ❌ Unbounded growth
+const wsClients: Record<string, WebSocket> = {}; // Grows forever
+
+// ✅ LRU / Cleanup Strategy
+const MAX_CLIENTS = 5;
+function connect(id: string) {
+  if (Object.keys(wsClients).length >= MAX_CLIENTS) {
+    // Cleanup logic
+    const oldest = getOldest(wsClients);
+    oldest.close();
+    delete wsClients[oldest.id];
+  }
+  wsClients[id] = new WebSocket(...);
+}
+```
+
+### WebSocket & Real-Time Review
+
+| Check | Best Practice | Status |
+|-------|---------------|--------|
+| **Connection Limit** | Limit active connections per client (e.g., max 5) | ⚠️ |
+| **Reconnection** | Exponential backoff (not immediate loop) | ✅ |
+| **Heartbeat** | Client-side ping/pong to detect dead connections | ⚠️ |
+| **Cleanup** | Close connection on component unmount / logout | ❌ |
+| **Message Queue** | Queue messages when disconnected | ✅ |
+
+### Core Web Vitals Targets
+
+```markdown
+## Core Web Vitals Review
+
+### Current Metrics
+| Metric | Target | Actual | Status |
+|--------|--------|--------|--------|
+| LCP | <2.5s | 2.8s | ⚠️ |
+| FID | <100ms | 45ms | ✅ |
+| CLS | <0.1 | 0.15 | ❌ |
+| INP | <200ms | 180ms | ✅ |
+| TTFB | <800ms | 650ms | ✅ |
+
+### LCP Optimization Checklist
+- [ ] Hero image preloaded
+- [ ] Critical CSS inlined
+- [ ] Server response <200ms
+- [ ] No render-blocking JS
+- [ ] Font display: swap
+
+### CLS Causes & Fixes
+| Cause | Current | Fix |
+|-------|---------|-----|
+| Images without dimensions | 3 images | Add width/height |
+| Dynamic content insertion | Ads, banners | Reserve space |
+| Web fonts FOUT | 2 fonts | Font display: optional |
+| Iframe without dimensions | 1 embed | Add aspect-ratio |
+```
+
+### Image Optimization
+
+```markdown
+## Image Review
+
+### Format Analysis
+| Image | Current | Optimal | Savings |
+|-------|---------|---------|---------|
+| hero.jpg | 450KB | hero.webp 120KB | 73% |
+| logo.png | 25KB | logo.svg 3KB | 88% |
+| icons/*.png | 200KB | sprite.svg 15KB | 92% |
+
+### Image Checklist
+- [ ] WebP/AVIF with fallback
+- [ ] Responsive srcset
+- [ ] Lazy loading (native or IO)
+- [ ] Explicit width/height
+- [ ] Alt text present
+```
+
+```html
+<!-- ❌ No optimization -->
+<img src="hero.jpg">
+
+<!-- ✅ Fully optimized -->
+<picture>
+  <source srcset="hero.avif" type="image/avif">
+  <source srcset="hero.webp" type="image/webp">
+  <img 
+    src="hero.jpg" 
+    alt="Product showcase"
+    width="1200"
+    height="800"
+    loading="lazy"
+    decoding="async"
+  >
+</picture>
+```
+
+### Bundle Size Analysis
+
+```markdown
+## Bundle Analysis
+
+### Main Chunks
+| Chunk | Size | Limit | Status |
+|-------|------|-------|--------|
+| main.js | 250KB | 200KB | ❌ |
+| vendor.js | 180KB | 150KB | ❌ |
+| styles.css | 45KB | 50KB | ✅ |
+
+### Large Dependencies
+| Package | Size | Used | Alternative |
+|---------|------|------|-------------|
+| lodash | 70KB | 3 functions | lodash-es + tree shake |
+| moment | 65KB | Date formatting | date-fns or dayjs |
+| chart.js | 60KB | 1 chart type | Lightweight alternative |
+
+### Code Splitting Opportunities
+| Route | Current | After Split | Lazy Load |
+|-------|---------|-------------|-----------|
+| /dashboard | 250KB | 80KB | ✅ |
+| /settings | Bundled | 35KB | Should split |
+| /admin | Bundled | 120KB | Must split |
+```
+
+---
+
+## 🌐 Cross-Browser Compatibility
+
+### Browser Testing Matrix
+
+```markdown
+## Browser Compatibility
+
+### Required Testing
+| Browser | Version | Desktop | Mobile | Status |
+|---------|---------|---------|--------|--------|
+| Chrome | Latest | ✅ | ✅ | ✅ |
+| Firefox | Latest | ✅ | ✅ | ✅ |
+| Safari | Latest | ✅ | ✅ | ⚠️ |
+| Edge | Latest | ✅ | ✅ | ✅ |
+| Safari | 14+ | ✅ | ✅ | ⚠️ flexbox gap |
+| Chrome | 90+ | ✅ | ✅ | ✅ |
+
+### Known Compatibility Issues
+| Feature | Support | Fallback |
+|---------|---------|----------|
+| CSS gap (flexbox) | Safari 14.1+ | margin hack |
+| :has() selector | Safari 15.4+ | JS fallback |
+| Container queries | Limited | @media queries |
+| CSS subgrid | Firefox only | Nested grid |
+```
+
+### Polyfill Strategy
+
+```markdown
+## Polyfill Review
+
+### Required Polyfills
+| Feature | Polyfill | Size | Conditional |
+|---------|----------|------|-------------|
+| fetch | whatwg-fetch | 3KB | ✅ |
+| Promise | es6-promise | 6KB | ✅ |
+| IntersectionObserver | intersection-observer | 7KB | ✅ |
+| ResizeObserver | resize-observer-polyfill | 8KB | ✅ |
+
+### Loading Strategy
+```javascript
+// ✅ Conditional polyfill loading
+if (!('IntersectionObserver' in window)) {
+  import('intersection-observer');
+}
+
+// ✅ Or use polyfill.io
+<script src="https://polyfill.io/v3/polyfill.min.js?features=IntersectionObserver"></script>
+```
+```
+
+---
+
+## 🎨 Dark Mode Review
+
+### Theme Implementation
+
+```markdown
+## Dark Mode Checklist
+
+### CSS Variables
+- [ ] Color scheme declared (color-scheme: light dark)
+- [ ] All colors use CSS variables
+- [ ] Semantic naming (--color-background, not --color-white)
+- [ ] Transition on theme change
+
+### Media Query Support
+- [ ] prefers-color-scheme: dark respected
+- [ ] Manual toggle available
+- [ ] Preference persisted (localStorage)
+- [ ] No flash on load (FOUC prevention)
+
+### Contrast Check
+| Element | Light Mode | Dark Mode | WCAG |
+|---------|------------|-----------|------|
+| Body text | 7:1 ✅ | 6:1 ✅ | AA |
+| Links | 4.5:1 ✅ | 3.8:1 ⚠️ | Needs fix |
+| Disabled | 3:1 ⚠️ | 2.5:1 ❌ | Needs fix |
+```
+
+```css
+/* ✅ Complete dark mode setup */
+:root {
+  color-scheme: light dark;
+  
+  /* Light mode (default) */
+  --color-bg: #ffffff;
+  --color-text: #1a1a1a;
+  --color-primary: #2563eb;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg: #1a1a1a;
+    --color-text: #f5f5f5;
+    --color-primary: #60a5fa;
+  }
+}
+
+/* Manual override via data attribute */
+[data-theme="dark"] {
+  --color-bg: #1a1a1a;
+  --color-text: #f5f5f5;
+  --color-primary: #60a5fa;
+}
+
+/* Smooth transition */
+body {
+  background: var(--color-bg);
+  color: var(--color-text);
+  transition: background-color 0.3s, color 0.3s;
+}
+```
+
+---
+
+## 📱 Mobile UX Review
+
+### Touch Interaction
+
+```markdown
+## Touch Target Review
+
+### Minimum Sizes
+| Element | Current Size | Required | Status |
+|---------|--------------|----------|--------|
+| Buttons | 44x44px | 44x44px | ✅ |
+| Links | 32x20px | 44x44px | ❌ |
+| Icons | 24x24px | 44x44px | ❌ (add padding) |
+| Checkboxes | 16x16px | 44x44px | ❌ |
+
+### Touch Spacing
+- [ ] 8px minimum between touch targets
+- [ ] No hover-only interactions
+- [ ] Touch feedback (active state)
+```
+
+### Mobile-Specific Issues
+
+```markdown
+## Mobile UX Checklist
+
+### Viewport
+- [ ] viewport meta tag correct
+- [ ] No horizontal scroll
+- [ ] 100vh issues handled (address bar)
+- [ ] Safe area insets for notch
+
+### Input Handling
+- [ ] Appropriate input types (email, tel, number)
+- [ ] Autocomplete attributes
+- [ ] No zoom on input focus (font-size >= 16px)
+- [ ] Virtual keyboard doesn't hide inputs
+
+### Gestures
+- [ ] Swipe actions accessible via buttons too
+- [ ] Pull-to-refresh if applicable
+- [ ] No interference with system gestures
+```
+
+```css
+/* ❌ Input zoom on mobile Safari */
+input {
+  font-size: 14px;  /* Triggers zoom on focus */
+}
+
+/* ✅ Prevent zoom */
+input {
+  font-size: 16px;  /* Or larger */
+}
+
+/* ✅ Handle safe areas (notch) */
+.header {
+  padding-top: env(safe-area-inset-top);
+}
+
+.footer {
+  padding-bottom: env(safe-area-inset-bottom);
+}
+
+/* ✅ Fix 100vh on mobile */
+.full-height {
+  height: 100vh;
+  height: 100dvh;  /* Dynamic viewport height */
+}
+```
+
+---
+
+## 🔒 TypeScript Runtime Safety
+
+### Import Type Usage (CRITICAL)
+**Anti-Pattern**: Importing interfaces/types as values. This causes "does not provide an export" runtime errors in modern bundlers (Vite/esbuild).
+
+```typescript
+// ❌ Runtime Error Risk
+import { MyInterface } from './types'; // Bundler looks for a value export
+
+// ✅ Correct: Type-Only Import
+import type { MyInterface } from './types'; // Explicitly removed at runtime
+// OR
+import { type MyInterface } from './types';
+```
+
+### Type Organization & Circular Dependencies
+**Anti-Pattern**: Defining types in Service/Component files that import other Services/Components.
+
+```typescript
+// ❌ Circular Dependency Risk
+// userService.ts
+import { Order } from './orderService'; // Cycle!
+export interface User { ... }
+
+// ✅ Centralized Types
+// types/index.ts or types/models.ts
+export interface User { ... }
+export interface Order { ... }
+```
+
+---
+
+## 📚 Component Documentation
+
+### Storybook Review
+
+```markdown
+## Component Documentation Checklist
+
+### Storybook Coverage
+| Component | Stories | Variants | Docs | Status |
+|-----------|---------|----------|------|--------|
+| Button | ✅ | 5/5 | ✅ | ✅ |
+| Input | ✅ | 4/6 | ⚠️ | ⚠️ Missing error state |
+| Modal | ❌ | 0/3 | ❌ | ❌ Not documented |
+| Card | ✅ | 3/3 | ✅ | ✅ |
+
+### Required Documentation
+- [ ] Component description
+- [ ] Props table with types
+- [ ] Usage examples
+- [ ] Accessibility notes
+- [ ] Do's and Don'ts
+```
+
+### Props API Design
+
+```typescript
+// ❌ Poor props design
+interface ButtonProps {
+  type: string;  // What values?
+  size: 1 | 2 | 3;  // Magic numbers
+  onClick: Function;  // Too generic
+}
+
+// ✅ Well-designed props
+interface ButtonProps {
+  /** Visual variant of the button */
+  variant: 'primary' | 'secondary' | 'ghost' | 'danger';
+  /** Size of the button */
+  size: 'sm' | 'md' | 'lg';
+  /** Whether the button is disabled */
+  disabled?: boolean;
+  /** Loading state shows spinner and disables interaction */
+  loading?: boolean;
+  /** Click handler */
+  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+  /** Button contents */
+  children: React.ReactNode;
+}
+```
+
+---
+
+## 📋 Frontend Review Summary Template
+
+```markdown
+# Frontend Review Report
+
+## Tool Scan Results
+| Tool | Status | Critical | Warning |
+|------|--------|----------|---------|
+| ESLint | ✅ | 0 | 3 |
+| TypeScript | ✅ | 0 | 1 |
+| Stylelint | ⚠️ | 0 | 5 |
+| Lighthouse | ⚠️ | Performance: 75 | - |
+| Accessibility | ✅ | 0 | 2 |
+| Bundle Size | ❌ | Over limit | - |
+
+## Visual Review
+| Check | Status | Issues |
+|-------|--------|--------|
+| Design match | ⚠️ | 3 spacing differences |
+| Responsive | ⚠️ | iPad layout issue |
+| Dark mode | ✅ | Works correctly |
+| Typography | ✅ | Consistent |
+
+## Interaction Review
+| Check | Status | Issues |
+|-------|--------|--------|
+| Animations | ⚠️ | Modal jank at 45 FPS |
+| Loading states | ✅ | All covered |
+| Error states | ⚠️ | Missing retry on network error |
+| Focus management | ❌ | Tab order incorrect |
+
+## Performance Review
+| Metric | Target | Actual | Status |
+|--------|--------|--------|--------|
+| LCP | <2.5s | 2.8s | ⚠️ |
+| CLS | <0.1 | 0.05 | ✅ |
+| Bundle | <200KB | 250KB | ❌ |
+
+## Browser Compatibility
+| Browser | Status | Issues |
+|---------|--------|--------|
+| Chrome | ✅ | None |
+| Firefox | ✅ | None |
+| Safari | ⚠️ | Flexbox gap fallback needed |
+| Mobile Safari | ⚠️ | 100vh issue |
+
+## Accessibility
+| Check | Status | Issues |
+|-------|--------|--------|
+| Color contrast | ⚠️ | Links in dark mode |
+| Screen reader | ✅ | Tested with VoiceOver |
+| Keyboard | ❌ | Missing skip link |
+| Touch targets | ⚠️ | Icons too small |
+
+## Critical Issues (Must Fix)
+1. **[P0]** Tab order incorrect in form
+2. **[P0]** Bundle size exceeds limit
+3. **[P1]** LCP exceeds target
+
+## Recommendations
+1. **[P1]** Add skeleton screens for better perceived performance
+2. **[P2]** Implement code splitting for admin routes
+3. **[P2]** Add Storybook stories for Modal component
+4. **[P3]** Consider adding haptic feedback on mobile
+```
+