How component contracts can encode image sizing, motion limits, dependency rules and accessibility into everyday delivery.
Performance belongs in the component contract
A button contract covers states and accessibility; a media card contract should also cover dimensions, loading priority and maximum content. When these decisions live only in an audit report, every product squad has to rediscover them. Put safe defaults in the component itself. The practical review should record the route, device class, network assumption, cache state and consent state. Teams should keep a baseline trace and a short decision log, because otherwise a later improvement cannot be separated from traffic mix or infrastructure change. The safest implementation is usually the one that reduces hidden work and leaves a clear fallback. Review it at an intermediate viewport as well as desktop and mobile, then repeat the primary task with keyboard input and a cold cache. Capture the result in a form that another engineer can reproduce without access to the original conversation. Include observed evidence, rejected alternatives, operational risk and the signal that triggers rollback. After release, compare both fast and slow percentiles; a median improvement can conceal a worse experience for visitors on constrained devices. Revisit the decision when product behaviour, vendors or traffic distribution changes, because a sound budget is a maintained boundary rather than a one-time audit artifact.
Limit variants by purpose
Unlimited visual variants increase CSS, testing and rendering complexity. Define variants around real semantic needs rather than every historical exception. A small token set makes critical CSS easier to reason about and reduces accidental combinations that break at intermediate widths. The practical review should record the route, device class, network assumption, cache state and consent state. Teams should keep a baseline trace and a short decision log, because otherwise a later improvement cannot be separated from traffic mix or infrastructure change. The safest implementation is usually the one that reduces hidden work and leaves a clear fallback. Review it at an intermediate viewport as well as desktop and mobile, then repeat the primary task with keyboard input and a cold cache. Capture the result in a form that another engineer can reproduce without access to the original conversation. Include observed evidence, rejected alternatives, operational risk and the signal that triggers rollback. After release, compare both fast and slow percentiles; a median improvement can conceal a worse experience for visitors on constrained devices. Revisit the decision when product behaviour, vendors or traffic distribution changes, because a sound budget is a maintained boundary rather than a one-time audit artifact.
Treat motion as a budget
Animation can clarify state, but large entrance sequences and scroll listeners consume main-thread time and can conflict with reduced-motion preferences. Provide a small motion vocabulary, use transform and opacity carefully, and make reduced motion the tested path rather than an afterthought. The practical review should record the route, device class, network assumption, cache state and consent state. Teams should keep a baseline trace and a short decision log, because otherwise a later improvement cannot be separated from traffic mix or infrastructure change. The safest implementation is usually the one that reduces hidden work and leaves a clear fallback. Review it at an intermediate viewport as well as desktop and mobile, then repeat the primary task with keyboard input and a cold cache. Capture the result in a form that another engineer can reproduce without access to the original conversation. Include observed evidence, rejected alternatives, operational risk and the signal that triggers rollback. After release, compare both fast and slow percentiles; a median improvement can conceal a worse experience for visitors on constrained devices. Revisit the decision when product behaviour, vendors or traffic distribution changes, because a sound budget is a maintained boundary rather than a one-time audit artifact.
Keep dependencies visible
A component that silently imports a charting package changes the cost of every route that uses it. Document bundle impact, code-split heavy capabilities and expose a lightweight alternative. Storybook examples should display loading and empty states without fetching production services. The practical review should record the route, device class, network assumption, cache state and consent state. Teams should keep a baseline trace and a short decision log, because otherwise a later improvement cannot be separated from traffic mix or infrastructure change. The safest implementation is usually the one that reduces hidden work and leaves a clear fallback. Review it at an intermediate viewport as well as desktop and mobile, then repeat the primary task with keyboard input and a cold cache. Capture the result in a form that another engineer can reproduce without access to the original conversation. Include observed evidence, rejected alternatives, operational risk and the signal that triggers rollback. After release, compare both fast and slow percentiles; a median improvement can conceal a worse experience for visitors on constrained devices. Revisit the decision when product behaviour, vendors or traffic distribution changes, because a sound budget is a maintained boundary rather than a one-time audit artifact.
Test the assembled page
Components can pass isolation tests and still fail when ten instances compete. Build representative composition fixtures: a long listing, a media-heavy article and a form with validation. Run accessibility, visual and performance checks against those fixtures in CI. The practical review should record the route, device class, network assumption, cache state and consent state. Teams should keep a baseline trace and a short decision log, because otherwise a later improvement cannot be separated from traffic mix or infrastructure change. The safest implementation is usually the one that reduces hidden work and leaves a clear fallback. Review it at an intermediate viewport as well as desktop and mobile, then repeat the primary task with keyboard input and a cold cache. Capture the result in a form that another engineer can reproduce without access to the original conversation. Include observed evidence, rejected alternatives, operational risk and the signal that triggers rollback. After release, compare both fast and slow percentiles; a median improvement can conceal a worse experience for visitors on constrained devices. Revisit the decision when product behaviour, vendors or traffic distribution changes, because a sound budget is a maintained boundary rather than a one-time audit artifact.
Govern through evidence
Deprecate costly patterns with migration examples, not slogans. Publish before-and-after traces, explain trade-offs and give teams a supported path. A system earns adoption when the efficient option is also the easiest option. The practical review should record the route, device class, network assumption, cache state and consent state. Teams should keep a baseline trace and a short decision log, because otherwise a later improvement cannot be separated from traffic mix or infrastructure change. The safest implementation is usually the one that reduces hidden work and leaves a clear fallback. Review it at an intermediate viewport as well as desktop and mobile, then repeat the primary task with keyboard input and a cold cache. Capture the result in a form that another engineer can reproduce without access to the original conversation. Include observed evidence, rejected alternatives, operational risk and the signal that triggers rollback. After release, compare both fast and slow percentiles; a median improvement can conceal a worse experience for visitors on constrained devices. Revisit the decision when product behaviour, vendors or traffic distribution changes, because a sound budget is a maintained boundary rather than a one-time audit artifact.
Working checklist
- Name the route, audience and primary task.
- Record cold and warm states.
- Identify the earliest controllable cause.
- Ship a reversible change with an owner.
- Compare the same field population after release.