Designing Durable Component APIs

Why it exists

Design systems fail when developers don't adopt them. A primary driver of adoption is a superior developer experience, and the component API is the main entry point. Poorly designed, inconsistent properties create friction and discourage use, while predictable, intuitive APIs make the system a pleasure to work with.

The mental model

Embrace "dream-driven development." The best API is no API. Before writing any implementation code, put yourself in the user's shoes and write the code snippet showing how you WISH the component could be used. Start with this ideal state, free from technical constraints, to anchor your design around the best possible developer experience.

How it works

First, define the ideal API by writing a usage example. For instance, an animation library might have a single "magic" property that handles transitions automatically. This sets a high bar for user experience. Second, after defining this ideal, you gradually reintroduce necessary complexity, making deliberate trade-offs instead of letting limitations dictate the design from the start. For system health, every change must be systematic. When adding a property, review other components to ensure consistent naming. For example, if you use variant to control style variations on a Button, don't use type or mode on a Card. This consistency is what makes it a system.

When to use it

This approach is critical when building or refactoring any component in a shared design system. It's most important for foundational components like Buttons, Inputs, and Modals, as they set the pattern for all future components and have the widest impact on developers.

When not to use it

While the principle of consistency is always valuable, the full "dream-driven" process might be overkill for one-off, internal-only components not intended for wide consumption. In such cases, you might prioritize implementation speed, but you should still avoid introducing names or patterns that conflict with the established system.

One canonical example

Imagine your Button component has variant="solid" and variant="outline". You need to add a red "danger" version. Do you add a new variant, like variant="danger-solid"? Or do you add a new property, like color="danger", that combines with the existing variants? A systematic approach forces you to decide which pattern scales better. If other components will also need color variations, establishing a separate color property creates a more robust and predictable system than creating dozens of combinatorial variant names.