A performance budget sets a hard limit on how heavy a page is allowed to get, usually expressed in kilobytes of JavaScript, CSS or images, or in a timing target like how long the largest visible element takes to render. Without one, a page grows the way any shared project grows: a tracking script here, a webfont there, a carousel library nobody remembers approving, until the thing that shipped fast in January is sluggish by June. The budget is the number that says stop.
What a budget actually limits
Most budgets work on one of two axes. The first is size: a cap on the total weight of JavaScript, or images, or fonts, measured in kilobytes after compression. The second is timing: a target for a specific moment in the load, most commonly Largest Contentful Paint (LCP), the point at which the biggest visible element on the page (usually a hero image or heading) has finished rendering. A design team might set a JavaScript budget of 170KB and an LCP target of 2.5 seconds on a mid-range mobile connection, and treat both as non-negotiable.
The two axes matter for different reasons. A size budget catches bloat before it happens, because it forces a conversation the moment a new dependency would push the total over. A timing budget catches the combined effect of everything already on the page, including things a size budget alone would miss, like a large but perfectly optimised image that still arrives too late on a slow connection. Neither one replaces the other. A page can pass its JavaScript budget and still miss its LCP target because of a render-blocking font or a slow server response.
You can run both kinds of check against a real page using the performance budget calculator, which takes the figures you give it and shows where they sit against the limits you set. It works from the numbers you enter, so a stale asset list or an optimistic estimate will produce a result that looks fine and isn't. Treat what it gives you as a starting point for a conversation.
Why pages drift past their budget without anyone deciding they should
Nobody sits down and decides to make a page slow. It happens one small, individually reasonable decision at a time. A marketing team adds a chat widget. A designer wants a custom typeface with four weights. A developer pulls in a 40KB utility library to solve a problem that needed six lines of code. Each addition is defensible on its own, and each one is invisible to whoever approved the last one, because nobody was tracking the running total.
This is the actual case for having a budget at all: it isn't there to make the page fast on day one, it's there to stop the slow accumulation that nobody would choose if they saw it happening all at once. A budget makes the running total visible, so the fourth analytics script has to justify itself against a number.
It also changes who has to have the conversation. Without a budget, performance is treated as an engineering concern, raised (if at all) after launch when someone notices the page is slow. With a budget, it's a shared constraint from the brief onward, on the same footing as the brand guidelines or the content requirements. A design system that specifies a webfont with five weights and a budget that allows for one and a half is a conflict that surfaces before build.
Common mistakes
Setting the budget after the design is already approved
A budget agreed once the visual design is signed off has no teeth, because every stakeholder has already emotionally committed to the hero video and the parallax section. The budget needs to be part of the brief.
Measuring the wrong connection
A page that loads acceptably on office wifi can be genuinely unusable on a mid-range phone over a patchy mobile connection, and that gap is exactly where most real users of a public-facing site sit. A budget checked only against a fast desktop connection is checking the easiest case.
Treating the budget as a target to hit exactly
Some teams read a 200KB JavaScript budget as an instruction to use all 200KB. A budget is a ceiling. Coming in under it isn't wasted allowance, it's headroom for the feature that will inevitably need adding in six months.
Ignoring third-party weight
Analytics, chat widgets, ad tags and consent banners are frequently the heaviest thing on a page, and they're also the easiest to forget because nobody on the design or build team chose them directly. A budget that only counts the assets the team controls is measuring half the page.
Setting one budget for every page on the site
A product page carrying a gallery and a size guide has a different job to do than a contact page, and a single site-wide limit either starves the pages that need more or lets the simple ones get away with far more than they should. Budgets work better set per template, against what that template is actually for.
Putting a budget to work
Start with the timing target, because that's the number a visitor actually experiences. Pick a figure for LCP that reflects a realistic connection speed for the site's actual audience. Work backwards from there to a size budget for JavaScript, CSS and images, since those are the assets most directly under a design and build team's control.
- Set the budget before the visual design is finalised, so it's a constraint the design works within.
- Split the budget by template or page type, since a homepage and a checkout page carry very different jobs.
- Include third-party scripts in the total, even the ones added by another team, because the visitor's connection doesn't distinguish between first-party and third-party weight.
- Revisit the budget at each redesign.
- Check new features against the running total before they're built.
Where the numbers land matters more than getting the exact methodology right. Use the performance budget calculator to see how a proposed set of assets sits against a target you set, and to make the trade-off visible to whoever is deciding whether the extra carousel library is worth the hit. It works from the figures supplied, so it can only be as accurate as what goes into it, and it won't catch problems that live outside those figures, like a slow server or an unoptimised image pipeline further up the chain. Treat the result as a way of framing the conversation.
Related reference material, including the underlying units a budget is often expressed in, sits in the Design Glossary, and the wider set of build and measurement tools is listed on the tools page.