Variants must cover combinations that actually ship

What it is

A variant table is measured against combinations that already exist — or are about to merge — in the product, not against a designer’s imagined complete matrix. Checkout needs a primary button that is small + icon + loading. If the library has a “small” column and a “loading” column but no cell at their intersection, the call site will assemble a private fork. Production variant coverage asks whether a call site can be expressed inside the library, not how many cells Storybook displays.

Theoretical combinations that nobody uses may be absent. The cell that production is already passing cannot be absent, or the library will be bypassed.

Why it happens

A variant is a pre-declared legal combination. The call site passes values on several axes; the component picks an implementation for that tuple. When the intersection does not exist, the implementer has three moves: drop the requirement, write the styles on the page, or add a backdoor prop that serves only this page. The last two make the official variants an incomplete subset; the real look lives as a fork outside the library.

Coverage must be sampled from call sites, not from the Cartesian product of axes. The product fills the table with axes that never co-occur and looks complete; call-site logs reveal cells the mock never drew, such as icon and loading together at small size. Those are the missing cells, not the unused imaginary ones.

Where it stops holding

A new component with zero call sites has no production sample; cover the combinations already locked in design, then backfill after the first real integration. One-off combinations on experimental pages should not be promoted into the library — that swaps the coverage target from “recurring use” to “used once.” Platform-specific combinations (hover on desktop, none on mobile) must be covered per platform; a desktop matrix cannot judge a mobile library.

Applying it

• Extract a release’s call sites for the component from main, and list the axis tuples that actually occurred. Do not count cells in the design file.
• Promote combinations that appear twice or more into official variants; leave one-offs on the page until they repeat.
• Give every official variant a runnable example whose props can be found in production logs.
• How to check: take ten high-traffic call sites and confirm each can be expressed with public variants only, no page-level style overrides. Any site that needs a private fork is a coverage gap.

Related

• Same group: R1.02.2 A combinatorial explosion of variants signals the wrong abstraction · R1.02.3 Component boundaries follow responsibility, not pages
• Nearby: R1.03 Completeness of component states · R1.11 Component composability
• Search terms: production variant coverage · call site · variant matrix