UI Performance Budget

Put a number on how heavy and how slow each screen is allowed to get.

moderate Front-End Performance

What it adds

Per-route limits on script, stylesheet, image and font weight, first render, and interaction delay, checked automatically before a change ships.

What your agent is told to do

1
Measure the app's current numbers per route first and set the budget slightly under them. A budget invented from a best-practice article that the app already exceeds is ignored on the day it lands.
2
Budget each route separately. The marketing page, the sign-in screen, and the main editor have nothing in common, and one global number either strangles the editor or lets the landing page rot.
3
Cover both weight and behaviour: bytes shipped by category, time to first meaningful render, and the delay between a click and a visible response.
4
Run the check on every proposed change and report the delta against the base branch, so the person making the change sees the cost while they can still do something about it.
5
Do not fail the build on noise. Set a tolerance that absorbs normal variance and fail only on a sustained or substantial regression, because a check that cries wolf gets bypassed and then removed.

Edge cases it handles

A single budget for the whole app is the failure mode to avoid — set limits per route so the heaviest screen does not define the ceiling for the lightest.
Small variations between runs are normal, so the check must distinguish a genuine regression from measurement noise or it will block work at random.
Both a cold first visit and a warm repeat visit need budgets. Testing only the cached case hides everything that makes a first impression slow.
Numbers gathered on a fast laptop over office broadband describe nobody; target a mid-range device on a constrained connection and state which.
Bundle weight specifically is owned by Bundle-Aware Component Imports, which prevents the regression; this entry measures and enforces the ceiling. Point the budget at the same numbers rather than measuring bundles a second way.
A budget that is exceeded needs a defined route to a deliberate exception, recorded with a reason, or the only options are to bypass the check or abandon the change.
Third-party scripts must be counted in the budget, since they are frequently the largest single item and the easiest to add without noticing.

Definition of done

Each route has its own documented budget for weight, render time, and interaction delay.
Budgets were derived from current measurements rather than generic targets.
Every proposed change is checked and its delta reported against the base branch.
Cold and cached loads are both measured.
Measurement targets a stated device class and network profile.
Only sustained or substantial regressions fail the check.
Exceeding a budget deliberately is possible and leaves a recorded reason.
The feature matches the existing design system.
No existing functionality is broken.

Related features

Visual Asset Optimization Pipeline

Bundle-Aware Component Imports

Layout Shift Guard

How it works

1

Copy the link

Grab the Markdown instruction URL for this feature.
2

Give it to your AI

Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
3

It inspects, then implements

Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.