ADR 0005: Performance Budget & Measurement

Status: ✅ Approved
Date: 2025-12-11
Owner: Delivery Lead (Performance/QA)

Context

Performance budget is required by spec-kit/checklist.md:10 and ensures the marketing site delivers an optimal experience while we iterate. We rely on Next.js’s optimizations, but we must set explicit Core Web Vitals targets and describe how we measure them.

Budget

Metric	Target	Tool
Largest Contentful Paint (LCP)	≤ 2.5s	Lighthouse 10+ / WebPageTest
Interaction to Next Paint (INP)	≤ 200ms	Lighthouse / Web Vitals
Cumulative Layout Shift (CLS)	≤ 0.1	Lighthouse
Total Blocking Time (TBT)	≤ 150ms (optional)	Lighthouse

Goal: achieve these targets within the “Hero + CTA” above-the-fold experience on a simulated slow 4G connection (Network throttling in Lighthouse).

Measurement Workflow

Run npm run build and next start locally or on nexus-vector.
Open Lighthouse (Chrome DevTools > Lighthouse), choose “Performance + SEO + Best practices”, enable “Simulated throttling”, and run the report.
Record the values (screenshot or note them in a performance.md log).
If any metric exceeds the target, identify heavy assets (fonts, JS) via Lighthouse diagnostics and rerun after optimization.

Automation & Monitoring

Add a CI job (future) that runs npm run build plus Lighthouse via lighthouse-ci or npm run analyze to guard each deploy.
For now, rerun Lighthouse after each sprint or when new hero/content sections change to ensure budgets hold.

References

Core Web Vitals: https://web.dev/vitals/
Lighthouse CLI: https://github.com/GoogleChrome/lighthouse/tree/main/lighthouse-cli

1.7 KiB Raw Blame History Unescape Escape