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" onload="this.media='all'" />

   <!-- 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

Invoke the web-perf skill and follow it exactly as presented to you

web-perf Research Requirements

Generated: 2026-02-28

Skill Description

Structured 5-phase web performance audit workflow with Core Web Vitals thresholds and actionable optimization recommendations. Use when auditing website performance, diagnosing slow page loads, optimizing Core Web Vitals scores, or reviewing frontend performance patterns. Covers Webpack, Vite, Next.js, and Nuxt optimization.

Research Areas

• Current best practices for web-perf
• Industry standards and tooling
• Integration patterns

Source References

• To be populated by skill-updater research phase

web-perf Rules

Purpose

Structured 5-phase web performance audit workflow with Core Web Vitals thresholds and actionable optimization recommendations. Use when auditing website performance, diagnosing slow page loads, optimizing Core Web Vitals scores, or reviewing frontend performance patterns. Covers Webpack, Vite, Next.js, and Nuxt optimization.

Best Practices

• Follow established patterns
• Validate inputs at boundaries

Integration Points

See SKILL.md for complete documentation.

web-perf Implementation Template

Goal

• Define target outcome and acceptance criteria.

TDD

1. Red 2. Green 3. Refactor

Verification

• lint
• format
• targeted tests