Design Philosophy

Our goal for Paprika is to create components that are stable, usable, clear and delightful.

Ideally, we will minimize the complexity for the end-user (the application developer who consumes Paprika components). This means that we will favour absorbing complexity into a Paprika component, rather than exposing a more complex API.

Controlled vs Uncontrolled

We do not have a rule for components to always be controlled or uncontrolled — this decision will be made case-by-case based the type of component and the most convenient and practical API we can achieve for the consumer. In some cases, the best choice will be to support both patterns, as a hybrid component, even though this will certainly increase the internal complexity of the component.

Naming Conventions ↗️

We try to follow consistent API patterns among our components to make it easier to consume, it allows knowledge about one component to be transferrable to many other components. It also makes design decisions easier for contributors. Naming things is hard, and leveraging a naming decision for all components makes it easier — it's one less decision to make.

Please read the Naming Conventions for a complete reference.

Composition

Generally, fewer props are better. Components with a long list of props tend to be hard to understand and difficult to use. When many props are needed, try to split them among subcomponents; this will result in a more intuitive API and impose a lower cognitive load on the consumer. It is also a more scalable pattern to follow.

This approach should allow us to avoid passing an object as a prop. When developing a feature, it is convenient and common to supply application data to a component's prop with an object. But when creating reusable components this pattern can degrade the developer experience. We believe it's easier to understand a component if it is modelled with an HTML-like structure, rather than as JSON data.