Frontend Performance Budgets
An outcome metric (LCP, INP, CLS) tells you the page is slow. It does not tell
you what to change — that requires tracing the outcome to the causal resource
that produced it. This skill keeps the two separate on purpose: outcome
metrics are what the user experiences and what you measure in the field;
causal budgets are what you constrain at build/review time because they
are the actual levers.
Composes with the library:
- resource-exhaustion-review — covers cost blow-up from untrusted input
size (server-side); this skill covers cost from your own shipped
resources (client-side), a different axis of the same discipline
- frontend-component-boundaries — client/server component boundary
decisions in RSC frameworks directly gate hydration cost, one of the causal
budgets below
- non-overwhelming-ux — perceived speed and jank contribute to cognitive
load; this skill supplies the mechanism, that skill the user-facing
rationale
Outcome metrics (empirical evidence: field data, from web.dev / CrUX)
Source: web.dev, Core Web Vitals.
| Metric |
Good threshold (75th percentile, field data) |
What it measures |
| LCP (Largest Contentful Paint) |
≤2.5s |
Time to render the largest visible element |
| INP (Interaction to Next Paint) |
≤200ms |
Responsiveness of the slowest interaction across the session |
| CLS (Cumulative Layout Shift) |
≤0.1 |
Unexpected layout movement |
MUST measure these at the 75th percentile of real users (field data), not
lab/synthetic averages — a lab score can pass while real users on slower
devices/networks fail the threshold. SHOULD set a budget per metric before
starting work on a page, not after shipping and noticing a regression.
Causal resource budgets (methodological decision: what actually moves the outcome metrics)
These are not standards — they are the mechanism. Set explicit numeric
ceilings per project/route; the numbers below are starting points from field
practice, not universal law.
| Resource |
Typical starting budget |
Feeds which outcome metric |
Applies when |
| JS shipped to client (compressed) |
≤170KB on the critical route |
INP, and LCP via main-thread blocking |
Any route rendering interactive UI |
| Total image weight above the fold |
Sized to viewport, served in next-gen format (avif/webp) |
LCP |
Any route with a hero/above-fold image |
| Web font loading |
font-display: swap or preloaded, ≤2 font families |
CLS (swap-induced shift), LCP (if font blocks text render) |
Any custom web font |
| Third-party scripts |
Justified individually; each one is a request, a parse cost, and an unmanaged layout risk |
LCP, INP, CLS simultaneously |
Analytics, chat widgets, ad tech, embeds |
| Critical-path requests (render-blocking) |
Minimize; nothing render-blocking that isn't needed for the LCP element |
LCP |
Any synchronous <script>/<link> in <head> |
| Hydration cost (React/Next.js RSC, or equivalent) |
Client components only where interactivity is actually needed |
INP, TBT |
Any SSR/RSC framework — see frontend-component-boundaries |
MUST set the JS and image budgets explicitly per route before
implementation, when the route is known to be LCP- or INP-sensitive (landing
pages, checkout, any high-traffic entry point). MAY skip formal budgeting
for low-traffic internal tooling where the cost of measurement exceeds the
cost of the regression.
Tracing outcome → cause (the actual debugging method)
- LCP is bad → find the LCP element (Chrome DevTools Performance panel
names it). Is it render-blocked by JS/CSS? Not preloaded? Is it an image
with no explicit
width/height, or loaded from a slow third-party host?
- INP is bad → find the long task on the slowest interaction. Usually:
too much JS parsing/executing on the main thread, or a synchronous
handler doing work that should be deferred/chunked/moved off-thread.
- CLS is bad → find the element that shifted. Usually: an image/ad/embed
with no reserved space, a web font swap without matching fallback metrics,
or content injected above existing content after load.
Never optimize the outcome metric directly ("just make LCP faster") without
naming the causal resource — that produces cargo-cult fixes (adding
loading="lazy" to an above-the-fold image, which worsens LCP).
Failure modes / anti-patterns
- Lazy-loading the LCP element.
loading="lazy" on the hero image delays
the metric it's supposed to help.
- Budget measured only in the lab. A dev-machine Lighthouse score of 95
says nothing about a real user on a mid-tier phone on 4G — always check
field data (CrUX, RUM) before declaring victory.
- One giant third-party bundle for one small feature (e.g. a full charting
library for a single sparkline) — the causal-budget check ("what does this
dependency cost") is skipped because the outcome metric hasn't been
measured yet.
- Client component by default in an RSC framework — every component
marked
'use client' ships its JS and hydrates, whether or not it needs
interactivity.
- No
width/height (or aspect-ratio) on images/embeds — the browser
can't reserve space, so content shifts when the resource loads.
Verifiable checks
1---2name: frontend-performance-budgets3description: Set and enforce explicit performance budgets before writing frontend code, not measure after the fact — outcome metrics (LCP/INP/CLS) and the causal resource budgets that actually produce them (JS shipped, image weight, font loading, third-party scripts, critical request count, hydration cost). Use whenever adding a dependency, image, route, or client component, or when a page "feels slow" and the cause isn't obvious. Trigger on "bundle size", "Core Web Vitals", "hydration", "third-party script", "lazy load", "code split", "why is this slow", "LCP/INP/CLS", "render-blocking". Not a general "make it fast" skill — it is specifically about setting the budget before the fact and tracing outcome metrics to their causal resource.4metadata:5 source: https://skillmd.com/skills/annatchijova/frontend-performance-budgets6---78# Frontend Performance Budgets910An outcome metric (LCP, INP, CLS) tells you the page is slow. It does not tell11you what to change — that requires tracing the outcome to the causal resource12that produced it. This skill keeps the two separate on purpose: **outcome13metrics** are what the user experiences and what you measure in the field;14**causal budgets** are what you constrain at build/review time because they15are the actual levers.1617Composes with the library:1819- **resource-exhaustion-review** — covers cost blow-up from *untrusted input*20 size (server-side); this skill covers cost from *your own* shipped21 resources (client-side), a different axis of the same discipline22- **frontend-component-boundaries** — client/server component boundary23 decisions in RSC frameworks directly gate hydration cost, one of the causal24 budgets below25- **non-overwhelming-ux** — perceived speed and jank contribute to cognitive26 load; this skill supplies the mechanism, that skill the user-facing27 rationale2829---3031## Outcome metrics (empirical evidence: field data, from web.dev / CrUX)3233Source: [web.dev, Core Web Vitals](https://web.dev/articles/vitals).3435| Metric | Good threshold (75th percentile, field data) | What it measures |36|---|---|---|37| LCP (Largest Contentful Paint) | ≤2.5s | Time to render the largest visible element |38| INP (Interaction to Next Paint) | ≤200ms | Responsiveness of the *slowest* interaction across the session |39| CLS (Cumulative Layout Shift) | ≤0.1 | Unexpected layout movement |4041**MUST** measure these at the 75th percentile of real users (field data), not42lab/synthetic averages — a lab score can pass while real users on slower43devices/networks fail the threshold. **SHOULD** set a budget per metric before44starting work on a page, not after shipping and noticing a regression.4546## Causal resource budgets (methodological decision: what actually moves the outcome metrics)4748These are not standards — they are the mechanism. Set explicit numeric49ceilings per project/route; the numbers below are starting points from field50practice, not universal law.5152| Resource | Typical starting budget | Feeds which outcome metric | Applies when |53|---|---|---|---|54| JS shipped to client (compressed) | ≤170KB on the critical route | INP, and LCP via main-thread blocking | Any route rendering interactive UI |55| Total image weight above the fold | Sized to viewport, served in next-gen format (avif/webp) | LCP | Any route with a hero/above-fold image |56| Web font loading | `font-display: swap` or preloaded, ≤2 font families | CLS (swap-induced shift), LCP (if font blocks text render) | Any custom web font |57| Third-party scripts | Justified individually; each one is a request, a parse cost, and an unmanaged layout risk | LCP, INP, CLS simultaneously | Analytics, chat widgets, ad tech, embeds |58| Critical-path requests (render-blocking) | Minimize; nothing render-blocking that isn't needed for the LCP element | LCP | Any synchronous `<script>`/`<link>` in `<head>` |59| Hydration cost (React/Next.js RSC, or equivalent) | Client components only where interactivity is actually needed | INP, TBT | Any SSR/RSC framework — see `frontend-component-boundaries` |6061**MUST** set the JS and image budgets explicitly per route before62implementation, when the route is known to be LCP- or INP-sensitive (landing63pages, checkout, any high-traffic entry point). **MAY** skip formal budgeting64for low-traffic internal tooling where the cost of measurement exceeds the65cost of the regression.6667## Tracing outcome → cause (the actual debugging method)68691. **LCP is bad** → find the LCP element (Chrome DevTools Performance panel70 names it). Is it render-blocked by JS/CSS? Not preloaded? Is it an image71 with no explicit `width`/`height`, or loaded from a slow third-party host?722. **INP is bad** → find the long task on the slowest interaction. Usually:73 too much JS parsing/executing on the main thread, or a synchronous74 handler doing work that should be deferred/chunked/moved off-thread.753. **CLS is bad** → find the element that shifted. Usually: an image/ad/embed76 with no reserved space, a web font swap without matching fallback metrics,77 or content injected above existing content after load.7879Never optimize the outcome metric directly ("just make LCP faster") without80naming the causal resource — that produces cargo-cult fixes (adding81`loading="lazy"` to an above-the-fold image, which *worsens* LCP).8283## Failure modes / anti-patterns8485- **Lazy-loading the LCP element.** `loading="lazy"` on the hero image delays86 the metric it's supposed to help.87- **Budget measured only in the lab.** A dev-machine Lighthouse score of 9588 says nothing about a real user on a mid-tier phone on 4G — always check89 field data (CrUX, RUM) before declaring victory.90- **One giant third-party bundle for one small feature** (e.g. a full charting91 library for a single sparkline) — the causal-budget check ("what does this92 dependency cost") is skipped because the outcome metric hasn't been93 measured yet.94- **Client component by default** in an RSC framework — every component95 marked `'use client'` ships its JS and hydrates, whether or not it needs96 interactivity.97- **No `width`/`height` (or `aspect-ratio`) on images/embeds** — the browser98 can't reserve space, so content shifts when the resource loads.99100## Verifiable checks101102- [ ] Route has a stated LCP/INP/CLS budget, checked against field data (CrUX103 report or RUM), not only lab Lighthouse.104- [ ] The LCP element is identified and is not render-blocked, not105 lazy-loaded, and preloaded if it's a late-discovered resource.106- [ ] JS bundle size for the route is measured (build analyzer) against a107 stated ceiling.108- [ ] Every image/embed has explicit dimensions or `aspect-ratio` reserved.109- [ ] Every third-party script is individually justified and, where possible,110 loaded async/deferred or on interaction.111- [ ] Every component marked as client-rendered (`'use client'` or112 equivalent) is client-rendered because it needs interactivity, not by113 default — see `frontend-component-boundaries`.