Budgets
What a page weighs, measured from the build.
Why not Lighthouse here
Lighthouse needs a deployed URL and a headless Chrome, and it reports different numbers on different machines and different days. That makes it a poor gate for an edit loop and a good one for CI against a preview deployment, which is where it lands (M7).
What belongs in the edit loop is the part that is exactly computable: how many bytes a page ships to a phone. Because every image's sizes is known and its variants are generated by this build, the variant a 360px screen would select is derivable rather than sampled. The number is the same on every machine, and it needs no browser and no network.
The two measure different things and both are worth having. This one answers "is the page too heavy"; Lighthouse answers "does it feel slow".
What is counted
For each page, at the viewport in mobile_viewport and 2x pixel density:
| Counted | |
|---|---|
| HTML | The built file |
| CSS | The site's own `site.css` |
| Fonts | Every subset face the page preloads or uses |
| Images | For each `
|
The shared base.css is not counted: it is one cached file across every FivePaths site, and charging it to each page would hide the numbers that vary.
Setting them
{
"mobile_viewport": 360,
"page": { "transfer_kb": 350, "html_kb": 60 },
"fonts": { "files": 4, "kb": 200 },
"site_css": { "lines": 150 }
}
.cms/budgets.json. Without one the defaults above apply and cms check says so. Blowing page.transfer_kb or a font budget is an error and blocks; html_kb and site_css.lines are warnings, because both are usually telling you something about the content rather than about a defect.
Reading the report
Weight on a 360px screen, 2x route html css fonts images total budget /api/ 102.8 16.2 0 0 119 350 /modules/ 21.3 16.2 0 0 37.5 350
A row over budget is printed in red and fails the check. The failure names the breakdown and the largest image, because "the page is too big" is not actionable and "the page is too big and live-map-rail is 80 KB of it" is.
The site.css line budget
A number rather than a rule, for the reason MARKUP.md gives: a convention everyone agrees with and nobody measures drifts within a release. site.css holds only what one site alone has, so a growing number means a component is due to move into the shared sheet.
gtfs.media currently reports 610 lines against a budget of 150, which is a fair description of a site whose departure board, route pills, module catalogue, stack diagram, and pylon cabinet all live in its own sheet. Some of that is genuinely site-specific and some is a component waiting to be shared. The budget's job is to keep the question open.
Raising a budget
Edit the number, and say why in the commit. A budget nobody may change is ignored within a month; a budget that changes without an argument is not a budget. The commit message is the argument.