Principles of Clean Component API Design

A component's API (its props, events, and slots) is an interface contract with other engineers. Poor API design causes bugs, frustration, and abandonment.

Rules for World-Class Component APIs:

1. Predictable Prop Naming: Align with HTML standards. Use disabled (not isDisabled), onClick (not handleClick or performAction), and children for content.
2. Use Enums / Union Types for Variants: Instead of multiple conflicting booleans (isPrimary, isSecondary, isDanger), use a single variant union: variant?: 'primary' | 'secondary' | 'danger'.
3. Sensible Defaults: Every optional prop should have a smart default so <Button>Click me</Button> renders beautifully without configuring 10 props.
4. Pass-Through Native Attributes: Always spread native props (e.g., ...rest onto the underlying <button> or <input>) so consumers can attach aria-* tags or test IDs.