Performance is a design decision

Craft

03 Apr 2026

6 min read

Budgets agreed before the first commit, written into the same document as the design, and the three times we broke ours anyway.

Performance is usually treated as an engineering clean-up at the end, which guarantees two things: it will be someone else’s problem, and it will be fixed by removing whatever the design was built around.

So we set the numbers with the design, in the same document, signed off by the same people.

They are deliberately few, and they are absolute rather than relative. A percentage improvement is not a budget; it is an aspiration with arithmetic attached.

On a typical marketing site the agreement is:

The last line has killed more design ideas than the other three combined, and it is the one clients agree to fastest.

A budget you can exceed without noticing is not a budget. It is a preference.

Engineering handbook, section two

A hero video on a hotel project. It was the right idea and it cost 2.4MB, and we shipped it because the booking rate justified it. We wrote the exception down and the exceptions page has stayed one page long.

A map on a logistics dashboard, where the library was 190KB and every alternative was worse. We took the hit and removed a font weight to pay for it, which is the only honest way to break a budget: something else has to leave.

The third was our own site, for eight months, and nobody noticed until we ran the audit. That is the useful lesson — a budget only holds if something measures it on every deploy, and ours had quietly stopped.

Pl. 02  Build output, budget check on deploy

The check now runs on every pull request and it fails the build. Not a warning, not a dashboard someone might visit — a failure, on the branch, with the number that broke it. Warnings get acknowledged and forgotten within about three weeks.

We also put the numbers in the design files. When a component’s cost is written next to it, the conversation about whether to use it happens in the design review rather than in the sprint where it is too late to matter.

Agree the device, not just the number. ‘Under two seconds’ meant a developer’s laptop for the first year we did this, and every budget we hit was hit on hardware nobody in the audience owned.