| name | web-vitals |
| description | Specialist tool that wraps `pnpm audit:lighthouse` + `pnpm audit:visual`. p75 LCP/INP/CLS per page type, JS bundle vs budget. Used by Stage 1 Discovery (surfaces CWV regressions as opportunities) and Stage 8 UX (gates ship on perf budget). |
| metadata | {"family":"ops","owner":"perf","last_reviewed":"2026-04-29T00:00:00.000Z","version":"1.0.0","related_skills":["seo-foundations","performance","accessibility"],"kpis":["p75 LCP <2.5s every page type","p75 INP <200ms every page type","p75 CLS <0.1 every page type","JS bundle within budget per route family"],"marketing_pillar":4,"seo_standard":"D","kpi_tier":1,"funnel_stage":"all","maturity_stage":"diagnostic","used_by_stages":[1,8]} |
Web Vitals
Wraps pnpm audit:lighthouse + pnpm audit:visual. Aggregates p75 metrics per page type. Reports per-route JS bundle vs budget.
When to Use
- Stage 1 Discovery weekly — surfaces CWV regressions as
90_10_class: schema_fix (perf-fix variant) opportunities.
- Stage 8 UX per-ship — gates merge on perf budget.
- Ad-hoc: incident-response on CWV regression.
Do Not Use When
- Need overall traffic / engagement view — use
traffic-monitor.
- Need accessibility audit — use
accessibility skill (run pnpm audit:axe).
Inputs
pnpm audit:lighthouse (existing script)
pnpm audit:visual (existing script)
- Vercel Speed Insights / RUM (if available, for real-user p75)
- Per-route JS bundle analyzer output
Targets
Per seo-foundations/reference/cwv-budgets.md:
| Metric | Target |
|---|
| LCP | <2.5s p75 mobile (homepage <2.0s) |
| INP | <200ms p75 mobile (homepage <150ms; tools allow <300ms) |
| CLS | <0.1 p75 mobile (homepage <0.05) |
| Route family | JS bundle budget |
|---|
| Homepage | ≤80KB |
| Tool pages | ≤120KB |
| Role / city / guide | ≤60KB |
| Programmatic city × role | ≤40KB |
| State paycheck / unemployment | ≤80KB |
Workflow
Weekly run
- Run
pnpm audit:lighthouse against a representative sample (1 URL per page type).
- Run
pnpm audit:visual against the same sample for CLS detection.
- Aggregate: compute p75 LCP/INP/CLS per page type.
- Compute current JS bundle size per route family from build output.
- Compare against budgets.
- Flag any breach.
Per-ship run (Stage 8)
- Run lighthouse + visual against the changed routes' preview deploy.
- Pass: Lighthouse Performance ≥90, all CWV within budget, bundle within budget.
- Fail: trigger Stage 8 APPROVAL gate in Slack.
Output Contract
Markdown block at nextjs-app/docs/reports/<date>/web-vitals.md:
## Web Vitals — <date>
### CWV p75 per Page Type
| Page type | LCP | INP | CLS | Status |
|---|---|---|---|---|
| Homepage | 1.8s | 145ms | 0.04 | PASS |
| Role pages | 2.4s | 180ms | 0.08 | PASS |
| Tool pages | 2.9s | 280ms | 0.09 | PASS (within tool tolerance) |
| ... | ... | ... | ... | ... |
### JS Bundle vs Budget
| Route family | Current | Budget | Status |
|---|---|---|---|
| Homepage | 76KB | 80KB | PASS (95%) |
| Tool pages | 115KB | 120KB | PASS (96%) |
| Role / city / guide | 58KB | 60KB | PASS (97%) |
### Regressions (WoW)
- `<page-type>`: LCP +`<delta>`ms — `<link to lighthouse trace>`
- `<page-type>`: bundle +`<delta>`KB — `<link to PR diff>`
### Recommendations
- Surface `<page-type>` LCP regression as `schema_fix` opportunity in next Discovery
- Schedule `<page-type>` bundle reduction via Stage 6 template work
Incident Triggers
Per seo-foundations/reference/excellence-targets.md Standard D:
- Launched-pillar p75 LCP regression >500ms WoW = S2 →
cwv-regression.md runbook.
- Launched-pillar p75 INP regression >50ms WoW = S3.
- Launched-pillar CLS regression >0.05 WoW = S2.
- CWV breach for 14 consecutive days on any page type = S2.
References