Frontend Performance Budgeting
Original project-agnostic procedure. Agent-host effectiveness remains experimental.
When to use
Set and evaluate route-specific frontend budgets for transfer size, main-thread work and user-visible loading without equating synthetic checks with field performance. Use for a concrete implementation, review or repair in this domain.
When not to use
Do not impose this full workflow on unrelated or trivial edits. Do not replace the existing framework, design system or package manager merely to follow this skill. Installation, publication and private-data access require the consuming task’s authority.
Inputs
Resolve the user flow, accepted requirements, owned files, installed package versions, runtime/deployment target, existing component and token contracts, supported browsers, and actual check commands. Private product paths, credentials and policy stay in the consuming adapter. Read existing source and configuration before asking for information it already contains.
Procedure
1. Freeze the comparison contract
Name critical routes/interactions, device/network conditions, datasets, build mode and budgets before optimizing. Distinguish compressed transfer, decoded asset bytes, parse/execute work and memory. A dependency’s installed size is not the delivered bundle size.
2. Inspect the production graph
Use actual bundle analysis to locate eagerly imported libraries, icon registries, duplicate packages and clientified modules. Defer optional features behind deliberate boundaries rather than splitting every tiny function. Keep fonts/images sized and loaded according to their role.
3. Budget rendering and delivery
Prioritize visible content, avoid unnecessary waterfalls and reserve dimensions that prevent layout shifts. Do not lazy-load the key visual merely because lazy loading sounds faster. Treat third-party scripts as owned costs with a measured need.
4. Measure comparable signals
Use production artifacts and repeated lab measurements for regressions; use appropriately consented field data for real-user Core Web Vitals. Report LCP, INP and CLS only with their measurement basis and scope. A browser test duration is not a Core Web Vital.
5. Retain guardrails
Record before/after versions and output hashes, check required interactions and include memory/accessibility regressions. Do not increase the budget after seeing a failure without a reviewed product decision. Keep external analytics installation outside an unapproved optimization task.
Output
Return the bounded implementation or review, the state/ownership decisions that matter to the task, exact changed paths, actual checks and evidence, and remaining limitations. Distinguish a passing build, a browser observation and an agent-host evaluation. Do not claim production accessibility, performance or security from a narrow fixture.
Failure handling
An icon picker imports every icon pack to avoid a few explicit imports and makes the initial route much larger. Measure the emitted graph, select a bounded registry or deferred picker, and enforce a predeclared transfer budget while retaining accessible controls. When a required tool, dependency or permission is unavailable, preserve work and report the specific untested boundary instead of fabricating a pass.
Example
Consider this synthetic case: An icon picker imports every icon pack to avoid a few explicit imports and makes the initial route much larger.
Expected behavior: Measure the emitted graph, select a bounded registry or deferred picker, and enforce a predeclared transfer budget while retaining accessible controls.
See the original worked recipe for the acceptance path.
Evaluation and implementation scope
references/scenarios.json contains three not-run host-evaluation inputs, not completed evaluation results. The frontend engineering guide maps the separate executable fixture coverage and untested boundaries. The optional React fixture is not a Next.js, native-device, screen-reader or production-security certification.
Technical references
Use documentation matching installed versions. These are references to the underlying technology; upstream skill text, style databases and code are not repackaged as original instructions.