Counterexamples prevent misuse better than canonical examples

What it is

A canonical example shows a path that works. Readers can still take the neighboring path that looks almost the same. A counterexample draws that neighboring path and marks it wrong: two primary buttons in a row, danger paint on every table row, a dialog’s main action labeled “click here.” The constraint lives in the contrast, not in a fair-weather sentence.

The issue is what actually stops misuse — a concrete failure image is sharper than a correct one — not whether an exclusion rule was written into the contract. An exclusion can be a sentence. A counterexample is that sentence grown into a recognizable failure.

Why it happens

People analogize by similarity. A positive example offers too many similarities: one primary button on the page invites another beside it. A counterexample cuts the analogy by showing the “similar but illegal” edge. The reader about to submit the same layout can recognize it: not “primary buttons are allowed,” but “two primaries are this picture already marked red.”

Positives also saturate. Five correct uses in the docs read as rewrites of one sentence — no news for people who already know, not sharp enough for people who do not. One counterexample aimed at a high-frequency misuse is denser: it gives the error, the replacement, and the one decision that separates them. Docs without counterexamples are opened after the misuse has already landed, and even then the reader can only hold them against a positive that “looks close enough.”

Where it stops holding

A new component with almost no call sites and no observed misuse will produce scarecrow counterexamples; wait for the first real miss and then file it. A counterexample that mocks the error without a replacement leaves the reader nowhere to retreat — deterrence without guidance. Legal variants whose visual difference is tiny (two allowed compact densities) should not be drawn as counterexamples, or an allowed choice is branded wrong. Stale counterexamples (the API changed, that misuse is no longer possible) teach outdated fear and must be deleted with the API.

Applying it

• Mine design review and code review for rejected uses of the component. Turn each high-frequency miss into a counterexample with a correct replacement.
• Place counterexample and positive side by side, labeled at the decision that differs (count, tone, structure). Do not caption it merely “bad.”
• Put the highest-frequency counterexample on the first screen of the component docs, not under a trailing FAQ.
• How to check: give a new author the positives only and see whether they produce a known misuse; then show the counterexample and see whether they correct it before submit. If the misuse still ships after seeing the counterexample, the contrast did not hit the decision.

Related

• Same group: R1.04.1 Guidelines must say when not to use the component · R1.04.3 Without guidelines, each team invents its own usage
• Nearby: R1.12 Usage guidelines and anti-example docs · R1.17 Over-generic component abstraction
• Search terms: counterexample constraint · don't example · misuse pattern