Component API Decisions
The choices you make when defining a component's props determine how long that component stays useful.
A component has two lives: the life it lives when it is first built, and the life it lives after it has been used in fifteen different contexts by four different people. The first life is short and controlled. The second life is where component API decisions either hold up or fall apart.
The composition versus configuration axis
Every component API decision sits somewhere on an axis between composition and configuration. Configuration-heavy components expose a prop for every variation: variant, size, colour, icon, disabled, loading, iconPosition. Composition-heavy components expose children and let the caller assemble the content.
Configuration components are easier to document and harder to extend. Composition components are harder to document and more resilient to unanticipated use cases. The correct position on this axis depends on the component: a Button should lean toward configuration because its variations are predictable. A Card should lean toward composition because its content is not.
Avoid boolean props that should be enums
A button with isLarge and isSmall boolean props has an undefined state when both are true. A button with a size prop of 'sm' | 'md' | 'lg' does not. Convert any boolean prop that governs a property with more than two states to an enum. This is not a cosmetic preference — it is a correctness constraint.
The slot pattern for content injection
When a component needs to accept content in a specific structural position — a leading icon in an input, a footer in a card, a label in a form field — the slot pattern is more maintainable than either passing the content as a prop or requiring a specific child structure. The slot is a named, optional content area with a documented contract.
When to break a component in two
If a component's props list has grown beyond twelve items, it is almost certainly doing more than one thing. The signal to split is when you find yourself writing conditional logic in the component that activates entire branches of functionality based on a prop. That branch is a second component. The original component should compose them.
Splitting components is easier early than late. The cost of splitting a component that has been used in forty places is much higher than the cost of splitting one that has been used in three. Audit component complexity early and split before the usage surface is wide.