# Component API Design: Predictability and Flexibility

> Learn to design robust and consistent component APIs that facilitate handoff between design and development, reducing errors and accelerating product construction.

*Tags: ux, technique, ui-design, product-design, development*

---


> [!info] Quick Definition
> Designing a **Component API** consists of defining a clear entry contract (props) and behavior for elements in a design system, with the goal that they are easy to use, predictable, and maintainable for both designers and developers.


## What Makes a Good Component API?

A component is not just a visual piece; it is a unit of functional logic. A well-designed API must clearly answer these three fundamental premises:

1.  **What Data Does It Receive? (Inputs/Props):** The set of properties that define the component's state and content (e.g., `label`, `icon`, `size`).
2.  **What Can It Do? (Events/Outputs):** The actions it can trigger upon user interaction (e.g., `onClick`, `onChange`, `onDismiss`).
3.  **How Does It Look in Different Scenarios? (Visual Variants):** The multiple appearances it can adopt (e.g., `primary`, `secondary`, `ghost`).

## Attributes of a Successful and Scalable API

### 1. Total Predictability
A component should always behave the same way given the same set of data. If a `Button` has a `size="large"` property, it must produce an identical result on all screens and contexts where it is used within the application. Predictability builds trust for both the end user and the development team.

### 2. Simplicity: Avoiding the "Mega-Component"
It is a common temptation to try to cover every possible use case with an infinite number of properties (props). However, this often leads to unmanageable components (so-called "God Components").
- **Bad API:** A `Card` component that receives `title`, `description`, `imageUrl`, `hasButton`, `buttonText`, `isFeatured`, `backgroundColor`, etc.
- **Good API (Composition):** A `Card` that acts as a transparent and flexible container (using `children` or `slots`) to receive other smaller components, such as `CardHeader`, `CardContent`, and `CardFooter`. This approach is known in software engineering as the *Compound Components* pattern.

### 3. Clear, Intuitive, and Consistent Naming
Property names should be semantic and clearly indicate their data type:
- **Booleans (Yes/No):** Use prefixes like `is`, `has`, or `should` (e.g., `isDisabled`, `isLoading`, `hasIcon`).
- **Enums (Finite Options):** For options that are mutually exclusive (e.g., `variant="primary | secondary | ghost"` or `size="small | medium | large"`).
- **Clear Data Types:** If a property receives text, call it `label` or `text`, not just `data`.

## The Vital Contract between Figma and Code

One of the greatest challenges in product design is ensuring a component has the same "name" and "configuration" in both the design tool and the technical implementation (handoff).

- **In Figma:** `Component Properties` (Boolean, Instance Swap, Text, and Variant) are used to control the component's interface on the canvas.
- **In Code (React, Vue, SwiftUI):** `Props` (or arguments) are used to define the component's behavior in the real application.

If both parties share the same naming structure (e.g., both use `variant="danger"`), communication between design and engineering flows without friction, eliminating the need for constant clarification or manual translation.

## How to Correctly Document the API

Every fundamental component of your design system should have a reference table detailing its public interface:

| Property | Type | Description | Default Value |
| :--- | :--- | :--- | :--- |
| **label** | `string` | The main text shown inside the button. | "Button" |
| **variant** | `enum` | Defines the visual style of the component: `primary`, `secondary`, `ghost`. | `primary` |
| **size** | `enum` | Controls the size of the button: `small`, `medium`, `large`. | `medium` |
| **isDisabled** | `boolean` | If true, the button is shown disabled and does not react to clicks. | `false` |
| **icon** | `element` | Optional icon shown to the left of the text. | `null` |

## Mentor's Tips

- **Don't reinvent the wheel:** Look at how popular component libraries (like **Radix UI** or **MUI**) name their properties. Following these standards will facilitate adoption by developers.
- **Design for change:** Ask yourself: "If I add a new feature tomorrow, will I have to break this entire component's structure?". A modular design based on composition is more resilient to time.
- **Test your API with developers:** Before finalizing a complex component, sit down with an engineer and review if the proposed API is logical and easy for them to implement.

## Useful Resources and Tools

- **Radix UI Documentation:** An excellent reference on how to design headless and accessible component APIs.
- **Shopify Polaris Guidelines:** Detailed guide on UI component structure and usage.
- **Storybook:** The best tool to visualize, test, and document your component APIs in a live environment.
- **Books:** *Thinking in React* (official documentation) and *Design Systems* by Alla Kholmatova.
---
[[token-aliasing-inheritance]]
[[component-props-organization]]


---

Source: https://www.fernandoux.com/en/wiki/techniques/component-api-design/