Without guidelines, each team invents its own usage

What it is

A component library that ships parts without usage leaves a vacuum each team fills with its own story: “ghost buttons in every table,” “dialog primary always on the right.” The stories do not recognize each other, yet every screen imports the same package. Unguided library divergence is the visual system already in pieces while adoption numbers still look high — intent has fragmented, not installation.

The package ships something that will render. Guidelines ship how the product is supposed to do the job. Without the latter, the former is interpreted as several products.

Why it happens

Parts do not carry intent. Primary, secondary, and ghost are all clickable; which rung to pick depends on a team’s folk theory of emphasis. Folk theories come from the first page that shipped, from a designer’s hallway talk, from a habit copied off another product. They are consistent inside a team and inconsistent across teams, so the same list uses a primary for row actions on Growth, a link on Settings, and an icon in Admin. Scanning the product, no one can predict what an action will look like on the next screen.

Metrics that only count imports will score this as success: every page uses the library. The real failure is that call sites from one package are teaching three grammars. Newcomers have to ask a person, and the answer depends on whom they asked. The longer the vacuum lasts, the harder the folklore sets, and writing guidelines later starts a fight over whose version is canonical.

Where it stops holding

A single squad on a single product, where hallway agreement still covers every call site, gains little from written guidelines; the vacuum may not fork yet. An open-source library that deliberately leaves intent to consumers (headless parts) wants divergence, but the intro must say “no product usage included,” or it will be mistaken for a design system. Strong brand partitions (marketing site versus product admin allowed two grammars) are controlled forks, provided the partition is written down rather than drawn by each squad. Automation that catches structural misuse (wrong DOM) does not replace usage guidelines: the structure can be right while emphasis still disagrees.

Applying it

• Name a usage owner for every stable component. Hallway rules must become a linkable guideline within two iterations, or they count as vacuum.
• Sample call sites for the same component across teams. Tabulate emphasis, placement, and pairing; treat splits as guideline gaps.
• Onboard a new team with the usage pack first (which rung, paired with what), then the install instructions. Do not hand over only an npm URL.
• How to check: have two squads who have not talked each build a page with a main list and a dialog, given the package and no guidelines. If emphasis, button count, or navigation choice already fork, the vacuum is already assigning production meaning. Repeat after the guideline exists; the fork should collapse to the rung the guideline names.

Related

• Same group: R1.04.1 Guidelines must say when not to use the component · R1.04.2 Counterexamples prevent misuse better than canonical examples
• Nearby: R1.18 Adoption and compliance metrics · R1.06 Contribution process and governance
• Search terms: unguided library divergence · local folklore · usage vacuum