Performance budgets
LAW — locked, CI-gatedPerformance budgets
Section titled “Performance budgets”This page is split, and the split is on the page: the performance law below is law; every quantified budget is labelled proposal, pending ratification, because that is what the constitution records.
principle. performance is not a property a surface has; it is a budget it spends, in public, with a method attached. “fast” with no hardware, percentile, or method named is a feeling, and feelings are not budgets.
rule — the law (law).
- zero frames cost at idle. event-driven only: no polling, no input hooks. a feature that costs measurable performance dies at review.
- flourishes and telemetry obey the same law: a surface that claims to be live is live by events, or it is honest about its freshness instead.
- every budget is classified, in writing, as enforced (a gate fails), monitored (measured, no gate yet), or aspirational (a target with no measurement — and it must say so). promoting a budget requires building its measurement first. existing polling anywhere in a build is re-justified against the law or replaced by events, and its summed idle cost is measured and published either way.
- budgets are measured on the reference machine and the CI runner, never only on the fastest desk in the building. performance information itself is opt-in density: default surfaces show none; a user who raises the level gets the numbers.
rule — quantified budgets (proposal, pending ratification).
- desktop: popover open-to-paint and open-to-interactive in the low tens of milliseconds, measured by the screenshot harness on the CI runner; input to next paint ≤ 50ms on the reference machine; idle CPU 0% sustained; frame cost during a fullscreen game: zero. size and idle working set per glass mode published in release notes with their method, with regression gates past a set percent.
- web: LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1 at field p75, enforced in CI with per-route asset ceilings.
worked example. a proposed widget wants to refresh its reading every second. under the law it does not get a timer: it subscribes to the event that changes the reading, costs zero frames between events, and renders its freshness honestly when events stop arriving. if the underlying source truly has no events, the widget’s design review is where that gets said out loud — with the summed idle cost measured and published, or the widget does not ship.
Canonical text: §11, performance law and budgets, in the design language document. Sources there: the gaps inventory, section 12; decisions 0004 and 0009.