# Diseño de APIs de Componentes: Predictibilidad y Flexibilidad

> Aprenda a diseñar APIs de componentes robustas y coherentes que faciliten el handoff entre diseño y desarrollo, reduciendo errores y acelerando la construcción de productos.

*Tags: ux, tecnica, diseño-ui, product-design, desarrollo*

---


> [!info] Definición Rápida
> El diseño de una **API de Componentes** consiste en definir un contrato claro de entrada (props) y comportamiento para los elementos de un sistema de diseño, con el objetivo de que sean fáciles de usar, predecibles y mantenibles tanto para diseñadores como para desarrolladores.


## ¿Qué Compone una Buena API de Componentes?

Un componente no es solo una pieza visual; es una unidad de lógica funcional. Una API bien diseñada debe responder de forma clara a estas tres premisas fundamentales:

1.  **¿Qué Datos Recibe? (Inputs/Props):** El conjunto de propiedades que definen el estado y el contenido del componente (ej. `label`, `icon`, `size`).
2.  **¿Qué Puede Hacer? (Eventos/Salidas):** Las acciones que puede disparar ante la interacción del usuario (ej. `onClick`, `onChange`, `onDismiss`).
3.  **¿Cómo se ve en Diferentes Escenarios? (Variantes Visuales):** Las múltiples apariencias que puede adoptar (ej. `primary`, `secondary`, `ghost`).

## Atributos de una API Exitosa y Escalable

### 1. Predictibilidad Total
Un componente debe comportarse siempre de la misma manera ante el mismo conjunto de datos. Si un `Button` tiene una propiedad `size="large"`, ésta debe producir un resultado idéntico en todas las pantallas y contextos donde se utilice dentro de la aplicación. La predictibilidad genera confianza tanto en el usuario final como en el equipo de desarrollo.

### 2. Simplicidad: Evitar el "Mega-Componente"
Es una tentación común intentar abarcar cada posible caso de uso mediante una infinidad de propiedades (props). Sin embargo, esto suele llevar a componentes inmanejables (los llamados "God Components").
- **Mala API:** Un componente `Card` que recibe `title`, `description`, `imageUrl`, `hasButton`, `buttonText`, `isFeatured`, `backgroundColor`, etc.
- **Buena API (Composición):** Un `Card` que actúa como un contenedor transparente y flexible (usando `children` o `slots`) para recibir otros componentes más pequeños, como `CardHeader`, `CardContent` y `CardFooter`. Este enfoque se conoce en ingeniería de software como el patrón de *Compound Components*.

### 3. Nombramiento Claro, Intuitivo y Consistente
Los nombres de las propiedades deben ser semánticos e indicar claramente su tipo de dato:
- **Booleanos (Sí/No):** Usa prefijos como `is`, `has` o `should` (ej. `isDisabled`, `isLoading`, `hasIcon`).
- **Enums (Opciones Finitas):** Para opciones que son mutuamente excluyentes (ej. `variant="primary | secondary | ghost"` o `size="small | medium | large"`).
- **Tipos de Datos Claros:** Si una propiedad recibe un texto, llámala `label` o `text`, no simplemente `data`.

## El Contrato Vital entre Figma y el Código

Uno de los mayores retos en el diseño de productos es lograr que un componente tenga el mismo "nombre" y la misma "configuración" tanto en la herramienta de diseño como en la implementación técnica (handoff).

- **En Figma:** Se utilizan las `Component Properties` (Boolean, Instance Swap, Text y Variant) para controlar la interfaz del componente en el lienzo.
- **En el Código (React, Vue, SwiftUI):** Se utilizan las `Props` (o argumentos) para definir el comportamiento del componente en la aplicación real.

Si ambas partes comparten la misma estructura de nombres (ej. ambos usan `variant="danger"`), la comunicación entre diseño e ingeniería fluye sin fricción, eliminando la necesidad de constantes aclaraciones o traducciones manuales.

## Cómo Documentar Correctamente la API

Cada componente fundamental de tu sistema de diseño debe contar con una tabla de referencia que detalle su interfaz pública:

| Propiedad | Tipo | Descripción | Valor por Defecto |
| :--- | :--- | :--- | :--- |
| **label** | `string` | El texto principal que se mostrará dentro del botón. | "Button" |
| **variant** | `enum` | Define el estilo visual del componente: `primary`, `secondary`, `ghost`. | `primary` |
| **size** | `enum` | Controla el tamaño del botón: `small`, `medium`, `large`. | `medium` |
| **isDisabled** | `boolean` | Si es true, el botón se muestra deshabilitado y no reacciona al click. | `false` |
| **icon** | `element` | Icono opcional que se muestra a la izquierda del texto. | `null` |

## Consejos de Mentor

- **No reinventes la rueda:** Observa cómo las librerías de componentes más populares (como **Radix UI** o **MUI**) nombran sus propiedades. Seguir estos estándares facilitará la adopción por parte de los desarrolladores.
- **Diseña para el cambio:** Pregúntate: "¿Si añado una nueva funcionalidad mañana, tendré que romper toda la estructura de este componente?". Un diseño modular basado en la composición es más resiliente al tiempo.
- **Prueba tu API con desarrolladores:** Antes de finalizar un componente complejo, siéntate con un ingeniero y revisa si la propuesta de API les resulta lógica y fácil de implementar.

## Recursos y Herramientas

- **Radix UI Documentation:** Un referente excelente sobre cómo diseñar APIs de componentes headless y accesibles.
- **Shopify Polaris Guidelines:** Guía detallada sobre la estructura y el uso de componentes de UI.
- **Storybook:** La mejor herramienta para visualizar, probar y documentar las APIs de tus componentes en un entorno vivo.
- **Libros:** *Thinking in React* (documentación oficial) y *Design Systems* de Alla Kholmatova.
---
[[aliasing-herencia-tokens]]
[[organizacion-props-componentes]]


---

Source: https://www.fernandoux.com/es/wiki/tecnicas/diseno-apis-componentes/