# Core Web Vitals Performance Audit Playbook **Portable spec for running a Core Web Vitals (CWV) lab audit on any new app's marketing surface — pre-launch baseline + 60-day field re-audit.** Built from the BKE `cwv-2026-05-19` audit. Reference repo: `reference app`. --- ## 0. Use this spec **Inputs:** - Production URL (Vercel preview or `vercel --prod` deploy — NEVER dev mode) - 5 priority URLs to test (landing, one cluster hub, one spoke/long-form, dashboard initial load, one free tool) - Access to Chrome DevTools MCP (`mcp__chrome-devtools__lighthouse_audit` + `performance_start_trace`) - Repo write access to drop the audit artifacts under `docs/audits/` **Outputs:** - `docs/audits/cwv-YYYY-MM-DD/REPORT.md` — human-readable summary with verdict per URL - `docs/audits/cwv-YYYY-MM-DD/report.json` — raw Lighthouse JSON per URL - `docs/audits/cwv-YYYY-MM-DD/report.html` — Lighthouse HTML for archival - `docs/audits/cwv-YYYY-MM-DD/*.png` — full-page screenshots at mobile/tablet/desktop - A locked-in performance budget in the repo's CLAUDE.md "Known Issues & Decisions" --- ## 1. The three metrics (Google CWV thresholds) Targets are **75th percentile of real-user data** — meaning 75% of your visitors must clear them. | Metric | Threshold | What it measures | |--------|-----------|------------------| | **LCP** (Largest Contentful Paint) | < **2.5s** | When the biggest above-fold element finishes rendering | | **CLS** (Cumulative Layout Shift) | < **0.1** | Total visual instability — content jumping during load | | **INP** (Interaction to Next Paint) | < **200ms** | Worst-case latency from any user input to next paint | INP replaced FID in March 2024. Lab tools (Lighthouse, DevTools) cannot measure INP without scripted interactions — it surfaces only via field data (CrUX / RUM). --- ## 2. Lab vs field - **Lab data** = synthetic device profile (Lighthouse, Chrome DevTools MCP, PageSpeed Insights "lab" tab). Reproducible, controllable, runs at launch with zero traffic. Doesn't measure INP. - **Field data** = real users in the wild (Chrome User Experience Report = CrUX, or your own RUM beacon). Surfaces INP, captures real network conditions, surfaces regressions invisible to lab. **At launch you only have lab data.** CrUX needs ~28 days of meaningful traffic before it populates. Plan a 60-90 day re-audit once field data is available. --- ## 3. URLs to test on each launch Cover the five archetypes — every marketing surface lives in one of these buckets: 1. **Landing page** (homepage / primary marketing entry) 2. **One cluster hub** (category/index page — the highest-DOM-density type) 3. **One spoke / long-form post** (blog post, research page, case study) 4. **Dashboard initial load** if the app has one (auth'd shell render is its own beast) 5. **One free tool page** (calculator, generator, lookup — interactive, JS-heavy) If the site doesn't have one of these, skip it. Don't pad the audit with redundant URLs. --- ## 4. Device profiles — mobile + desktop both Run every URL at all three: | Profile | Viewport | Why | |---------|----------|-----| | **Mobile** | 375×667, DPR 2, touch, mobile UA | Hard test. 70% of marketing traffic in 2026. Google ranks mobile-first. | | **Tablet** | 768×1024 | Visual regression only — Lighthouse doesn't score tablet separately, but layout breaks here. | | **Desktop** | 1440×900 | Easy mode — passes here mean nothing if mobile fails. | Mobile is the audit. Desktop is the sanity check. --- ## 5. Running the audit — Chrome DevTools MCP The tool is `mcp__chrome-devtools__lighthouse_audit`. For each URL × device profile combo: ``` 1. mcp__chrome-devtools__new_page → URL 2. mcp__chrome-devtools__emulate (device profile: mobile / desktop) 3. mcp__chrome-devtools__lighthouse_audit (categories: ['performance']) 4. Capture report.html + report.json → save to docs/audits/cwv-YYYY-MM-DD/ 5. mcp__chrome-devtools__take_screenshot (fullPage: true) → save PNG ``` For deeper LCP/CLS/INP traces beyond Lighthouse's aggregate score, use `performance_start_trace` → interact → `performance_stop_trace` → `performance_analyze_insight`. --- ## 6. Performance budget (hard limits — set in CLAUDE.md, enforce in PRs) | Asset | Mobile budget | |-------|---------------| | Initial JS bundle (compressed) | **< 150KB** | | Initial CSS (compressed) | **< 50KB** | | Total page weight | **< 500KB** | | LCP element size | < 200KB image, < 4KB if text | | Third-party scripts | 0 at launch (revisit at re-audit) | PR review rule: if `npm run build` output shows the route exceeds these, the PR doesn't merge until the regression is justified or fixed. --- ## 7. Common LCP culprits + fixes | Culprit | Fix | |---------|-----| | **Render-blocking CSS** | Inline critical CSS — Next.js: `experimental: { inlineCss: true }` in `next.config.ts`. Saves **1–1.3s mobile LCP** on BKE. | | **Web fonts FOIT/FOUT** | Preload via `` + `font-display: swap` in `@font-face`. Self-host (no Google Fonts CDN hop). | | **Hero image** | Use `next/image` with `priority` prop + responsive `sizes` + AVIF/WebP via `formats: ['image/avif','image/webp']` in next.config. | | **Above-the-fold JS** | Defer non-critical scripts (`