Web Perf

Web Performance Audit

Structured 5-phase web performance audit workflow. Diagnose performance bottlenecks, measure Core Web Vitals, and produce actionable optimization recommendations.

When to Apply

Use this skill when:

• Auditing website performance for Core Web Vitals compliance
• Diagnosing slow page loads, high Time to Interactive, or layout shifts
• Optimizing Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), or Interaction to Next Paint (INP)
• Reviewing frontend code for performance anti-patterns
• Preparing a site for Google's page experience ranking signals
• Optimizing build output for Webpack, Vite, Next.js, or Nuxt

Core Web Vitals Thresholds

Additional Performance Metrics

5-Phase Audit Workflow

Phase 1: Performance Trace

Capture a performance trace to establish baseline metrics.

Browser-Based (Chrome DevTools):

1. Open Chrome DevTools (F12) > Performance tab
2. Click "Record" and reload the page
3. Stop recording after page fully loads
4. Analyze the flame chart for:
   • Long tasks (> 50ms, marked in red)
   • Layout thrashing (forced reflow cycles)
   • Render-blocking resources
   • JavaScript execution bottlenecks

Lighthouse Audit:

# CLI-based Lighthouse audit
npx lighthouse https://example.com --output=json --output-path=./lighthouse-report.json

# With specific categories
npx lighthouse https://example.com --only-categories=performance --output=html

# Mobile simulation (default)
npx lighthouse https://example.com --preset=perf --throttling-method=simulate

Key Trace Indicators:

• Main thread busy time: Should be < 4s total
• Largest task duration: Should be < 250ms
• Script evaluation time: Should be < 2s
• Layout/style recalculation: Should be < 500ms

Phase 2: Core Web Vitals Analysis

Measure each Core Web Vital and identify specific causes.

LCP Diagnosis

LCP measures loading performance -- when the largest content element becomes visible.

Common LCP Elements:

• <img> elements (hero images)
• <video> poster images
• Block-level elements with background images
• Text blocks (<h1>, <p>)

LCP Optimization Checklist:

1. Preload the LCP resource

   <link rel="preload" as="image" href="/hero.webp" fetchpriority="high" />
   

2. Eliminate render-blocking resources

   <!-- Defer non-critical CSS -->
   <link rel="stylesheet" href="/non-critical.css" media="print" />
   
   <!-- Async non-critical JS -->
   <script src="/analytics.js" async></script>
   

3. Optimize server response time (TTFB)

   • Use CDN for static assets
   • Enable HTTP/2 or HTTP/3
   • Implement server-side caching
   • Use streaming SSR where supported

4. Optimize image delivery

   <!-- Modern format with fallback -->
   <picture>
     <source srcset="/hero.avif" type="image/avif" />
     <source srcset="/hero.webp" type="image/webp" />
     <img
       src="/hero.jpg"
       alt="Hero"
       width="1200"
       height="600"
       fetchpriority="high"
       decoding="async"
     />
   </picture>
   

CLS Diagnosis

CLS measures visual stability -- unexpected layout shifts during page load.

Common CLS Causes:

• Images without explicit dimensions
• Ads or embeds without reserved space
• Dynamically injected content above the fold
• Web fonts causing FOIT/FOUT (Flash of Invisible/Unstyled Text)

CLS Optimization Checklist:

1. Always set image dimensions

   <img src="/photo.jpg" width="800" height="600" alt="Photo" />
   

   Or use CSS aspect-ratio:

   .hero-image {
     aspect-ratio: 16 / 9;
     width: 100%;
   }
   

2. Reserve space for dynamic content

   .ad-slot {
     min-height: 250px;
   }
   .skeleton {
     height: 200px;
     background: #f0f0f0;
   }
   

3. Use font-display: swap with size-adjust

   @font-face {
     font-family: 'CustomFont';
     src: url('/font.woff2') format('woff2');
     font-display: swap;
     size-adjust: 100.5%; /* Match fallback font metrics */
   }
   

4. Avoid inserting content above existing content

   • Banners should push down from top, not shift existing content
   • Use transform animations instead of top/left/width/height

INP Diagnosis

INP measures interactivity -- the delay between user interaction and visual response.

Common INP Causes:

• Long JavaScript tasks blocking the main thread
• Synchronous layout/style recalculations
• Heavy event handlers
• Excessive re-renders (React, Vue)

INP Optimization Checklist:

1. Break up long tasks

   // Instead of one long task
   function processAllItems(items) {
     for (const item of items) {
       /* heavy work */
     }
   }
   
   // Break into chunks with scheduler
   async function processAllItems(items) {
     for (const item of items) {
       processItem(item);
       // Yield to main thread between items
       await scheduler.yield();
     }
   }
   

2. Debounce/throttle event handlers

   // Throttle scroll handler
   let ticking = false;
   window.addEventListener(
     'scroll',
     () => {
       if (!ticking) {
         requestAnimationFrame(() => {
           updateUI();
           ticking = false;
         });
         ticking = true;
       }
     },
     { passive: true }
   );
   

3. Use requestIdleCallback for non-urgent work

   requestIdleCallback(() => {
     // Analytics, prefetching, non-visible updates
     sendAnalytics(data);
   });
   

Phase 3: Network Analysis

Analyze network waterfall for optimization opportunities.

Key Checks:

1. Resource count and total size

   • Target: < 100 requests, < 2MB total (compressed)
   • Check: performance.getEntriesByType('resource').length

2. Critical request chains

   • Identify chains longer than 3 requests
   • Break chains with preload/prefetch hints

3. Compression

   • All text resources should use Brotli (br) or gzip
   • Check Content-Encoding header in response

4. Caching headers

   # Immutable assets (hashed filenames)
   Cache-Control: public, max-age=31536000, immutable
   
   # HTML documents
   Cache-Control: no-cache
   
   # API responses
   Cache-Control: private, max-age=0, must-revalidate
   

5. HTTP/2+ multiplexing

   • Verify protocol in DevTools Network tab
   • Multiple resources should load in parallel over single connection

Phase 4: Accessibility Performance

Performance optimizations must not degrade accessibility.

Validation Checklist:

• Lazy-loaded images have alt attributes
• Deferred scripts do not break keyboard navigation
• Skeleton loaders have aria-busy="true" and aria-label
• prefers-reduced-motion is respected for animations
• Focus management works with dynamically loaded content

/* Respect reduced motion preference */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

Phase 5: Codebase Analysis

Review source code for performance anti-patterns.

Webpack Optimization

// webpack.config.js
module.exports = {
  optimization: {
    splitChunks: {
      chunks: 'all',
      maxInitialRequests: 25,
      minSize: 20000,
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name(module) {
            const packageName = module.context.match(/[\\/]node_modules[\\/](.*?)([\\/]|$)/)[1];
            return `vendor.${packageName.replace('@', '')}`;
          },
        },
      },
    },
  },
};

Vite Optimization

// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          router: ['react-router-dom'],
        },
      },
    },
    cssCodeSplit: true,
    sourcemap: false, // Disable in production
  },
});

Next.js Optimization

// next.config.ts
const nextConfig = {
  images: {
    formats: ['image/avif', 'image/webp'],
    deviceSizes: [640, 750, 828, 1080, 1200],
  },
  experimental: {
    optimizePackageImports: ['lucide-react', '@heroicons/react'],
  },
};

Common Code Anti-Patterns

Audit Report Template

# Web Performance Audit Report

**URL:** [target URL]
**Date:** [audit date]
**Tool:** Lighthouse [version] / Chrome DevTools

## Core Web Vitals Summary

| Metric | Score | Rating                      | Target   |
| ------ | ----- | --------------------------- | -------- |
| LCP    | X.Xs  | GOOD/NEEDS IMPROVEMENT/POOR | <= 2.5s  |
| CLS    | X.XX  | GOOD/NEEDS IMPROVEMENT/POOR | <= 0.1   |
| INP    | Xms   | GOOD/NEEDS IMPROVEMENT/POOR | <= 200ms |
| FCP    | X.Xs  | -                           | <= 1.8s  |
| TTFB   | Xms   | -                           | <= 800ms |
| TBT    | Xms   | -                           | <= 200ms |

## Critical Findings

### P0 (Immediate Action Required)

1. [Finding] - [Impact] - [Recommended Fix]

### P1 (Address This Sprint)

1. [Finding] - [Impact] - [Recommended Fix]

### P2 (Address This Quarter)

1. [Finding] - [Impact] - [Recommended Fix]

## Optimization Recommendations (Priority Order)

1. [Recommendation with estimated impact]
2. [Recommendation with estimated impact]
3. [Recommendation with estimated impact]

Anti-Patterns

• Do NOT optimize without measuring first -- always capture baseline metrics
• Do NOT lazy-load above-the-fold content -- it worsens LCP
• Do NOT remove image dimensions to "fix" CLS -- use CSS aspect-ratio instead
• Do NOT bundle all JS into a single file -- use code splitting
• Do NOT ignore mobile performance -- test with CPU/network throttling
• Do NOT use loading="lazy" on the LCP image -- it delays loading
• Do NOT serve images without modern formats (AVIF/WebP)

References

• web.dev Core Web Vitals
• Chrome User Experience Report
• Lighthouse Performance Scoring
• Web Almanac Performance Chapter

Iron Laws

1. ALWAYS measure Core Web Vitals (LCP, INP, CLS) with field data (CrUX) before proposing optimizations
2. NEVER optimize based on lab data alone — real user metrics determine actual user experience
3. ALWAYS prioritize LCP ≤2.5s, INP ≤200ms, CLS ≤0.1 as the primary performance targets
4. NEVER ship a performance fix without a before/after measurement proving improvement
5. ALWAYS address critical rendering path issues before layout or paint optimizations

Anti-Patterns

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md