Why component APIs drift faster than expected
A component API usually starts simple and then accumulates escape hatches under deadline pressure. Each new prop seems reasonable in isolation, but together they blur what the component actually owns.
The problem gets worse when teams generate or scaffold component code with AI. The model is often happy to add another prop instead of asking whether the abstraction should split.
The checklist worth applying early
A good API review asks whether the component still has one job and whether the consumer can understand the ownership rules without reading the implementation.
- Do the props describe one coherent responsibility or several unrelated modes?
- Are variants naming visual differences clearly instead of hiding behavior changes?
- Do callbacks express user intent rather than low-level implementation details?
- Is state ownership obvious between the component and its parent?
- Would a second component be clearer than another prop branch?
Signs the abstraction should split
If a component needs many mutually exclusive props, conditional callback expectations, or large sections of render logic that only matter in one variant, it is probably becoming two components.
Another sign is when the docs for using the component start sounding like exceptions to exceptions. The API should narrow decisions, not multiply them.
A calmer design rule
Aim for component APIs that help consumers make fewer decisions with more confidence. That often means smaller, sharper abstractions instead of all-purpose building blocks.
A restrained API ages better because it leaves room for composition before complexity becomes permanent.