Promote only after several real call sites exist

What it is

A name in the shared library is a public maintenance object. Promoting it in commits the system team to fix, version, and theme it for every caller. That promise is bought with multi-use promotion: several call sites that already exist, or are already scheduled to ship soon — not a mock on a board, not a sandbox demo page. A precious picker used on one settings screen is still a part of that screen.

“Real” means a production path a user can open. An imagined third use does not count.

Why it happens

Maintenance barely falls as call sites rise: docs, accessibility, the theme matrix, a deprecation notice — one job at one call site, still one job at a hundred, plus regression. Benefit does rise with N: sharing is what amortizes the fixed cost. At N = 1 the shared library is spending public headcount on a local widget, then stretching that widget’s life to “public object” scale. The evidence a proposer can most easily produce is “our page needs this”. That proves local pain, not a public duty. Asking for several call sites first turns “does this look like a primitive?” from a taste argument into a checklist you can open: URLs, repo paths, a branch about to merge.

The number is not magic. It filters the urge to promote before repetition has happened, so structure can show itself in reuse rather than be declared in the first draft.

Where it stops holding

Platform-mandated basics — checkbox, focus ring, semantic headings — should exist before the first product screen; their N comes from the platform contract, not from this product’s pages. Exploratory experiments, time-boxed campaigns, and features scheduled for deletion should not be promoted even at three sites, or a short-lived shape becomes a long contract. Two production sites plus a third written into the next iteration with a date may count as “N imminent”; if the third has not landed two iterations later, demote it back to a local widget. A legally or brand-mandated single entrance (a global consent banner) may be a legitimate public piece at N = 1, provided the whole product has only that one and it must be uniform.

Applying it

• Require the proposal template to list at least two live paths and one checkable upcoming path: page URLs or call sites in the repo, not “there will be similar places”.
• During review, open those paths and confirm they are the same job, not three different interactions sharing a similar title and being counted as three.
• Requests under the threshold may live as local widgets in the product repo, with a record “not promoted: insufficient call sites”.
• Check: take components admitted last quarter and count production call sites for each. If more than a third have only one real caller (demo and docs pages excluded), the gate is not running. Revisit “imminent third sites”: if they never appear, remove the piece from the library or mark it trial rather than letting it default to canon.

Related

• Same group: R1.06.1 Who may add a component must be named · R1.06.2 An ungoverned system decays into a component pile · R1.06.3 High contribution cost drives teams around the system · R1.06.5 Review the public API, not the implementation internals · R1.06.6 Maintenance is accepted with the component, not after the merge
• Adjacent: R1.02 Component libraries and variants · R1.17 Over-abstraction of components
• Search terms: multi-use promotion · call sites · promotion threshold