--- name: web-vitals-analyzer description: "Diagnoses Core Web Vitals failures (LCP, CLS, INP) from Lighthouse JSON or PageSpeed traces into ranked file-and-line root causes with expected metric deltas. Use when a Lighthouse score, LCP/CLS/INP number, layout shift, laggy click, or bundle-size complaint needs RCA. Not a CI budget gate (frontend-lighthouse) and not the markup-remediation implementer (performance-and-web-vitals)." version: 1.0.1 --- # Web Vitals Analyzer Diagnoses Core Web Vitals failures and frontend performance issues by analyzing page structure, resource loading patterns, JavaScript bundle composition, and rendering behavior. Produces prioritized fixes with estimated metric improvements. ## When to Use - User asks to optimize frontend performance or Core Web Vitals (LCP, CLS, INP). - User shares a Lighthouse report (JSON or screenshot) and wants root-cause analysis. - User reports slow page load, layout shift, or laggy interactions. - User asks to reduce JavaScript bundle size or identify render-blocking resources. - User mentions specific metrics: "LCP is 5s", "CLS is 0.25", "INP is 600ms". - User asks for quick wins to improve Lighthouse performance score. Trigger keywords: Core Web Vitals, LCP, CLS, INP, Lighthouse, PageSpeed, performance score, render-blocking, bundle size, lazy loading, layout shift, main thread, long tasks, code splitting, TTFB, first paint. ## Prerequisites - A Lighthouse report (JSON preferred), PageSpeed Insights URL, or Chrome DevOps performance trace if available. - The page URL or source code (HTML, CSS, JS entry points). - Framework identification (React, Next.js, Vue, Nuxt, SvelteKit, vanilla, etc.). - Current metric values if known (LCP, CLS, INP, TTFB, total bundle size). If any of these are missing, ask for them before proceeding. Do not give generic advice without knowing what is actually slow. ## Procedure ### 1. Gather Current State Ask for or analyze: - Lighthouse report (JSON or screenshot) - The page URL or source code (HTML, CSS, JS entry points) - Framework used (React, Next.js, Vue, vanilla, etc.) - Current LCP, CLS, and INP values if available ### 2. Analyze Largest Contentful Paint (LCP) — target < 2.5s Identify the LCP element (usually hero image, heading, or above-fold content), then check each item: 1. **Is the LCP image lazy-loaded?** It should NOT be. Remove `loading="lazy"` from above-fold hero images. 2. **Is there a `` for the LCP resource?** If not, add one: ```html ``` 3. **Are render-blocking CSS/JS delaying first paint?** Inline critical CSS; defer non-critical stylesheets. 4. **Server response time (TTFB):** If > 800ms, flag as a server-side issue (CDN, caching, SSR optimization). 5. **Font loading strategy:** Is `font-display: swap` or `optional` used? If not, add it. 6. **Critical CSS:** Is it inlined in `` or loaded as a blocking stylesheet? Inline above-fold critical CSS. ### 3. Analyze Cumulative Layout Shift (CLS) — target < 0.1 Identify elements causing layout shifts (images without dimensions, dynamic content, ads, web fonts), then check: 1. **Do all `` and `