High coverage is not the same as correct use

What it is

Coverage asks “does a system tag appear here”. Correct use asks “is this tag’s prop combination, slot content, and interaction path one the system allows”. The first can approach 100% while the second is poor: a button used as a link, a dialog used as a page, two props that must not be on together both on, a marketing block stuffed into an empty-state slot. High coverage only proves the call site chose a system name, not that the usage behind the name holds.

Coverage is a set membership: tag ∈ system. Correct use is a predicate: this call satisfies the component’s legal configuration. Neither quantity implies the other.

Why it happens

Scanners stop at the name by default. Recognising <Button> records a coverage hit, cheaply. Judging correct use means reading props, reading the subtree, sometimes running to watch keyboard and focus. That is another analysis, two orders of magnitude more expensive, so reports often carry coverage only. Consumers learn fast: if the tag is the system’s, the metric passes. Misuse is then fed by coverage — the more the metric stares at “used or not”, the more unfit duties get forced into existing tags, because picking the right name or opening a new component does not raise coverage, and forcing it does.

A legal configuration is a finite table: which props exclude which, which slots must have content, which paths are forbidden. Coverage has no such table, so it cannot tell “used a button” from “used a button correctly”. Treating coverage as health treats the name as quality.

Where it stops holding

Early components with no legal-configuration table yet can report coverage alone, labelled “usage not measured”. Visually indistinguishable legal variants (the same primary action, different brand tables) must not be scored as misuse. Content decided only at runtime (a subtree injected into a slot later) will false-flag a static predicate; add a pass in runnable examples or integration tests rather than dropping usage checks. When coverage is zero, correct use has no object; call sites first, right-or-wrong second.

Applying it

• Write a legal-configuration table for high-frequency components: exclusive props, required slots, forbidden paths. Run that table on top of coverage and emit a “covered but illegal” list.
• Split the report into two columns: coverage, and legal rate (legal calls / all system calls). Never ship coverage alone.
• Turn the most common illegal combinations into inspector rules that go red in the editor; do not wait for a quarterly report.
• How to check: take the flow with the highest coverage and hand-label every call legal or illegal against the table. If the illegal share is hidden under a pretty coverage number, the metric is lying. Then deliberately write a forbidden combination (button as link, exclusive props both on): coverage should still count 1, legal should count 0 — if both columns move together, the scanner is still stopped at the name.

Related

• Same group: R1.18.1 Adoption is counted at call sites, not by teams · R1.18.3 Metrics exist to locate gaps, not to score consumers · R1.18.4 The distribution of bypasses shows what the system is missing
• Adjacent: R1.04 Usage guidelines · R1.12 Usage guidelines and anti-example docs
• Search terms: coverage is not correct use · misuse under coverage · legal configuration