Web Vitals Optimizer Agent

Core Web Vitals specialist that measures, diagnoses, and remediates LCP, INP, and CLS issues to achieve and maintain passing scores in Google PageSpeed Insights and field data.

When to Use This Agent

Choose this agent when you need to:

• Diagnose and fix Largest Contentful Paint (LCP), Interaction to Next Paint (INP), or Cumulative Layout Shift (CLS) failures
• Optimize resource loading order, critical rendering path, and asset delivery for faster page loads
• Set up Real User Monitoring (RUM) dashboards and performance budgets with automated alerting
• Prepare for Google search ranking signals by meeting Core Web Vitals thresholds

Consider alternatives when:

• Performance issues are React-specific rendering or bundle problems (use the React Performance Consultant)
• You need to stress-test backend infrastructure capacity under concurrent load (use the Load Testing Specialist)

Quick Start

Configuration

Copy
name: web-vitals-optimizer-agent
type: agent
category: performance-testing

Example Invocation

Copy
claude agent:invoke web-vitals-optimizer-agent "Audit homepage LCP and CLS, then provide a prioritized fix plan targeting good thresholds"

Example Output

Web Vitals Audit — Homepage (mobile, 4G throttled)
LCP: 4.8s [POOR — threshold 2.5s] Element: <img class="hero-banner">
INP: 145ms [NEEDS IMPROVEMENT — threshold 200ms]
CLS: 0.28 [POOR — threshold 0.1] Shift source: unsized ad slot + web font swap

Priority Fix Plan:
1. [LCP] Preload hero image, serve WebP with srcset — estimated savings: 2.1s
2. [CLS] Add explicit width/height to ad container — eliminates 0.18 shift
3. [CLS] Use font-display:optional for body font — eliminates 0.10 shift
4. [LCP] Inline critical CSS, defer render-blocking stylesheets — saves 0.4s

Projected After Fix: LCP 2.3s [GOOD], INP 145ms [GOOD], CLS 0.00 [GOOD]

Core Concepts

Core Web Vitals Thresholds Overview

Metric	Good	Needs Improvement	Poor	What It Measures
LCP	<= 2.5s	<= 4.0s	> 4.0s	Loading — time until largest visible content element renders
INP	<= 200ms	<= 500ms	> 500ms	Interactivity — worst-case latency of user interactions throughout page life
CLS	<= 0.1	<= 0.25	> 0.25	Visual stability — cumulative unexpected layout shifts during page life
TTFB	<= 800ms	<= 1800ms	> 1800ms	Server responsiveness — time from request to first response byte

Optimization Pipeline Architecture

┌─────────────────┐     ┌─────────────────┐
│  Lighthouse /    │────▶│  Metric         │
│  CrUX Field Data │     │  Triage Engine  │
└─────────────────┘     └─────────────────┘
        │                       │
        ▼                       ▼
┌─────────────────┐     ┌─────────────────┐
│  Resource        │────▶│  Critical Path  │
│  Waterfall Trace │     │  Optimizer      │
└─────────────────┘     └─────────────────┘
        │                       │
        ▼                       ▼
┌─────────────────┐     ┌─────────────────┐
│  Layout Shift    │────▶│  Fix Plan &     │
│  Attribution     │     │  Budget Monitor │
└─────────────────┘     └─────────────────┘

Configuration

Parameter	Type	Default	Description
lcp_target	string	2.5s	Target LCP threshold for the optimization plan
cls_target	float	0.1	Maximum acceptable cumulative layout shift score
inp_target	string	200ms	Target Interaction to Next Paint latency
throttle_profile	string	mobileRegular3G	Network throttling profile for lab testing
rum_sample_rate	float	0.1	Fraction of real user sessions to capture for field metrics (10% default)

Best Practices

1. Prioritize Field Data Over Lab Data Lighthouse lab scores are useful for development feedback, but CrUX (Chrome User Experience Report) field data reflects what real users experience across diverse devices and network conditions. Always validate lab improvements against field data trends before declaring a metric fixed.

2. Optimize the LCP Element Directly, Not Just General Page Speed Identify the specific LCP element (often a hero image or heading) and ensure it loads as early as possible. Preload the resource, inline its critical CSS, and eliminate any render-blocking dependencies on its critical path. General page speed improvements help but targeting the LCP element yields the largest single improvement.

3. Reserve Layout Space for All Dynamic Content Every element that loads asynchronously (images, ads, embeds, web fonts) must have explicit dimensions or an aspect-ratio container reserved in the initial HTML. This single practice eliminates the majority of CLS issues because the browser never needs to reflow content when the resource arrives.

4. Defer Non-Critical JavaScript with Yield-to-Main Patterns Long JavaScript tasks block the main thread and inflate INP. Break expensive work into smaller chunks using scheduler.yield(), requestIdleCallback, or setTimeout(0) patterns so that user interactions can be processed between chunks without perceptible delay.

5. Establish Performance Budgets with CI Enforcement Define explicit budgets for total JS size, image weight, LCP time, and CLS score. Integrate Lighthouse CI or SpeedCurve into your deployment pipeline to automatically block releases that exceed budgets, preventing gradual performance regression over time.

Common Issues

1. Hero image LCP delayed by late discovery When the hero image URL is only known after CSS or JavaScript executes, the browser cannot start fetching it during HTML parsing. Add a <link rel="preload" as="image" href="..."> tag in the document <head> to initiate the fetch immediately. For responsive images, use imagesrcset and imagesizes attributes on the preload link.

2. Web font swap causing both CLS and LCP regression Using font-display: swap causes a visible text reflow when the custom font arrives, contributing to CLS. Meanwhile, if the LCP element is text styled with the custom font, LCP waits for the font download. Use font-display: optional to eliminate the swap shift entirely, accepting that some users on slow connections will see the fallback font.

3. Third-party scripts dominating the main thread Analytics, ad, and chat widget scripts often execute synchronously and block INP-critical event handlers. Load third-party scripts with async or defer, and where possible use the Partytown library or web workers to move their execution off the main thread entirely, reclaiming interaction responsiveness.