Documenting component anti-patterns and don'ts

WHAT THIS TESTS This evaluates whether you think about documentation as behavior change. Telling people the right way is weak; showing the wrong way with consequences and enforcing it is strong.

A GOOD ANSWER COVERS Name a concrete anti-pattern. A classic one is reaching into a component's internals with CSS overrides or className injection, which couples the consumer to private structure and breaks on the next release. Another is using a Modal for a non-blocking status message, stealing focus and trapping keyboard users. Document each as a paired Do and Don't block with runnable code and a screenshot, then explain the why in one sentence: it breaks focus management, fails contrast, or guarantees future breakage. Move beyond prose by enforcing where possible, an ESLint rule banning a deprecated prop, a development-mode console warning when an invalid prop combination is passed, or TypeScript types that make the wrong combination unrepresentable.

COMMON WRONG ANSWERS Writing only happy-path examples. Burying a warning in a wall of text. Saying do not do this without explaining the consequence, so developers ignore it. Documenting a don't that the API actually permits with no guardrail.

LIKELY FOLLOW-UPS How do you keep don'ts current as the API evolves. How do you measure whether the guidance reduced misuse. When is an anti-pattern better fixed by changing the API than by documenting around it.

ONE CONCRETE EXAMPLE For an icon-only Button, the Don't shows it with no aria-label and notes screen readers announce nothing. The Do adds an aria-label, and a runtime warning fires in development when an icon-only button lacks an accessible name, turning the documented don't into an enforced guardrail.