web-vitals

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

1. Run pnpm audit:lighthouse against a representative sample (1 URL per page type).
2. Run pnpm audit:visual against the same sample for CLS detection.
3. Aggregate: compute p75 LCP/INP/CLS per page type.
4. Compute current JS bundle size per route family from build output.
5. Compare against budgets.
6. Flag any breach.

Per-ship run (Stage 8)

7. Run lighthouse + visual against the changed routes' preview deploy.
8. Pass: Lighthouse Performance ≥90, all CWV within budget, bundle within budget.
9. 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

• seo-foundations/reference/cwv-budgets.md
• seo-foundations/reference/runbooks/cwv-regression.md
• .agents/rules/060-performance-budgets.mdc