--- playbook: web-perf-budgets owner: wize-agent-test-architect # Hawkeye (with Tony on stack picks) applies_when: web-overlay active status: ready --- # Web Performance Budgets — Hawkeye Playbook Budgets are decisions, not measurements. Set them once, enforce them on every PR. ## 1. Core Web Vitals — the floor | Metric | Good | Needs work | Poor | |---|---|---|---| | **LCP** (Largest Contentful Paint) | ≤ 2.5s | 2.5–4.0s | > 4.0s | | **INP** (Interaction to Next Paint) | ≤ 200ms | 200–500ms | > 500ms | | **CLS** (Cumulative Layout Shift) | ≤ 0.1 | 0.1–0.25 | > 0.25 | Measure on **mobile, slow 4G, mid-range device** — not your laptop on fiber. ## 2. Baseline budgets (mid-range mobile, 3G fast) | Resource | Budget | How to enforce | |---|---|---| | **Total transferred** (initial route) | ≤ 200 KB compressed | `lighthouse-ci` budget. | | **JS** | ≤ 100 KB compressed (≤ 300 KB uncompressed) | Bundle analyzer + CI check. | | **CSS** | ≤ 30 KB | Critical-CSS inlined; rest deferred. | | **Images (above the fold)** | ≤ 100 KB total | AVIF/WebP, ``. | | **Fonts** | ≤ 30 KB (2 weights subset) | `font-display: swap`, preload. | | **Third-party requests** | ≤ 5 | Audit on every release. | These are starting points. Tony tunes them per project after the PRD nails the audience and target device. ## 3. JS budget — what eats it - Framework runtime (React: ~50 KB gz, Vue: ~30 KB, Svelte: 0 KB at runtime). - Router. - State manager. - Date library (date-fns ≪ moment). - Form library. - UI components from `node_modules`. Audit with `npx vite-bundle-visualizer` (Vite) or `next-bundle-analyzer` (Next). Remove the top 3 by size every quarter. ## 4. Image strategy 1. **Format:** AVIF first → WebP → JPEG/PNG fallback. 2. **Width:** never serve more than 2× the rendered CSS width. 3. **Lazy:** below-the-fold = `loading="lazy"`. LCP image = ``. 4. **Dimensions:** always set `width` and `height` HTML attrs to prevent CLS. 5. **Responsive:** `` with `srcset` + `sizes`, or a framework-native ``. ## 5. Font strategy - Self-host. Don't fetch from CDN for performance work. - Subset to the characters you actually use (Glyphhanger / fonttools). - `font-display: swap` so text appears instantly. - Preload the primary font; defer secondaries. - Cap variable fonts at 2 axes. ## 6. Third parties (the silent killers) For every third-party script, answer: 1. **What user value does it deliver?** 2. **Can it load after `load` event?** (analytics, A/B, chat) 3. **Can it load only on interaction?** (chat widgets, video embeds) 4. **Has it been replaced by a smaller alternative?** (e.g., Plausible vs GA) 5. **Is it sandboxed in a `