096 — Web Performance {Performance}
Purpose
Achieve and maintain excellent Core Web Vitals scores. Optimize Largest Contentful Paint, Interaction to Next Paint, and Cumulative Layout Shift through systematic measurement and targeted fixes. [EXPLICIT]
Physics — 3 Immutable Laws
- Law of User Perception: Performance is measured by what users experience — LCP < 2.5s, INP < 200ms, CLS < 0.1. Server metrics are secondary. [EXPLICIT]
- Law of Critical Path: The browser renders what's on the critical path. Anything not needed for first paint must be deferred, lazy-loaded, or eliminated. [EXPLICIT]
- Law of Budgets: Performance budgets are enforced in CI. No PR may regress a Core Web Vital without justification and compensating optimization. [EXPLICIT]
Protocol
Phase 1 — Measurement Baseline
- Run Lighthouse CI on all key pages: homepage, dashboard, listing, detail. [EXPLICIT]
- Record baseline CWV: LCP, INP (formerly FID), CLS for each page. [EXPLICIT]
- Set up Real User Monitoring (RUM) via
web-vitals library reporting to analytics. [EXPLICIT]
- Configure Lighthouse CI budget file:
lighthouserc.js with per-metric thresholds. [EXPLICIT]
Phase 2 — LCP Optimization
- Preload hero image:
<link rel="preload" as="image" href="hero.webp">. [EXPLICIT]
- Inline critical CSS: extract above-the-fold CSS via
critters or critical. [EXPLICIT]
- Eliminate render-blocking resources: defer non-critical JS, async load fonts. [EXPLICIT]
- Server response time < 200ms: use Firebase Hosting CDN cache. [EXPLICIT]
Phase 3 — INP & CLS Optimization
- INP: Break long tasks > 50ms. Use
requestIdleCallback or scheduler.yield() for heavy computation. [EXPLICIT]
- INP: Debounce rapid input handlers. Use
startTransition for non-urgent React updates. [EXPLICIT]
- CLS: Set explicit
width/height on images and embeds. [EXPLICIT]
- CLS: Reserve space for async content (skeletons). No layout shifts after initial paint. [EXPLICIT]
I/O
| Input | Output |
|---|
| Page URL | Lighthouse report (Performance, CWV scores) |
lighthouserc.js budget | CI pass/fail per metric |
web-vitals library integration | RUM data in analytics |
| CSS source | Critical CSS extracted + inlined |
Quality Gates — 5 Checks
- LCP < 2.5s on p75 for all key pages. [EXPLICIT]
- INP < 200ms on p75 — no interaction takes longer. [EXPLICIT]
- CLS < 0.1 — no unexpected layout shifts. [EXPLICIT]
- Lighthouse Performance >= 90 in CI. [EXPLICIT]
- Performance budget enforced — CI fails on regression. [EXPLICIT]
Edge Cases
- Third-party scripts: Analytics, chat widgets degrade CWV. Load via
requestIdleCallback or after load event.
- Dynamic content: Content from Firestore may shift layout. Use skeleton placeholders matching final dimensions.
- Font loading: Use
font-display: swap + preload WOFF2. Avoid FOIT (flash of invisible text).
- SPA navigation: Measure soft navigation CWV separately from hard navigation.
Self-Correction Triggers
- LCP regresses above 2.5s → audit critical path, check preload hints, verify CDN cache.
- CLS spikes → search for new dynamic content without reserved space.
- Lighthouse drops below 90 → run full audit, compare with previous report.
- RUM data diverges from lab data → investigate real-world network conditions.
Usage
Example invocations:
- "/web-performance" — Run the full web performance workflow
- "web performance on this project" — Apply to current context
Assumptions & Limits
- Assumes access to project artifacts (code, docs, configs) [EXPLICIT]
- Requires English-language output unless otherwise specified [EXPLICIT]
- Does not replace domain expert judgment for final decisions [EXPLICIT]