Diseño con sistema: de las decisiones visuales al código reutilizable

Un sistema de diseño empieza antes de los componentes. Empieza con decisiones: cuáles son los colores, qué escala tipográfica usamos, cuánto espaciado existe entre elementos, qué radio de borde tienen los botones.

Esas decisiones se convierten en tokens — variables con nombre semántico.

En lugar de `color: #1a1a2e`, escribimos `color: var(--pz-color-brand-primary)`. En lugar de `margin: 16px`, escribimos `margin: var(--pz-space-4)`. En lugar de `font-size: 0.875rem`, escribimos `font-size: var(--pz-text-sm)`.

El cambio parece solo cosmético hasta que el cliente quiere ajustar el color primario. En un sistema sin tokens, eso implica buscar cada lugar donde ese hex específico aparece. En un sistema con tokens, cambiás el valor de la variable y todos los componentes que la usan se actualizan.

Multiplicá eso por cada decisión de diseño que existe en un sitio — hay decenas — y la diferencia de mantenibilidad es enorme.

Un componente bien diseñado tiene una interfaz clara: qué datos acepta (props), qué variantes existen, qué comportamiento tiene en cada estado (cargando, vacío, error, con contenido).

Esa interfaz es un contrato. El componente garantiza que si le pasás esos datos, produce ese resultado visual. Nada más.

En Pegasuz, cada componente tiene variantes explícitas en lugar de combinaciones de props arbitrarias. Una tarjeta (`Card`) puede ser `variant="primary"` o `variant="outlined"`, no `:hasBorder="true" :hasBackground="false" :emphasis="2"`. Las variantes son los casos de uso real que identificamos — no una API genérica que cubre todos los casos posibles.

Esto tiene consecuencias en el diseño de componentes: cuando alguien pide una variante nueva, no modifica el componente de forma ad-hoc. Analiza si la variante pertenece al contrato o si es un componente nuevo.

Cuando construimos para múltiples clientes, hay una tensión entre reutilización y personalización. El botón primary de la inmobiliaria tiene que verse diferente al de la empresa de gas. Pero la lógica del botón es la misma: estados hover, focus, loading, disabled.

La solución es separar lo que varía de lo que no varía.

Lo que no varía: la estructura HTML, los estados de interacción, la accesibilidad. Eso va en el componente.

Lo que varía: los colores, los radios de borde, los espaciados específicos. Eso va en los tokens del tema.

Cada cliente tiene su propio archivo de tokens CSS que sobreescribe los valores base. El componente de botón es el mismo en todos. Los tokens que consume cambian por cliente.

Construir con sistema tiene un costo inicial real. Definir los tokens toma tiempo. Diseñar los componentes con contratos claros es más lento que copiar y pegar. Documentar las variantes agrega trabajo al proceso.

El retorno viene en la acumulación.

El segundo sitio que construís sobre el mismo sistema tarda menos que el primero. El tercero tarda menos que el segundo. El décimo es notablemente más rápido que si cada uno hubiese empezado desde cero, porque la mayoría de los problemas ya están resueltos.

Más importante: cuando encontrás un bug o mejorás un componente, la corrección se propaga. No tenés que perseguir el mismo problema en diez lugares.

Los sistemas de diseño son un trabajo continuo. Tenemos tokens bien definidos para color, tipografía y espaciado. Tenemos componentes con contratos claros para las estructuras más usadas.

Pero hay áreas donde todavía tomamos decisiones caso a caso: animaciones complejas específicas de un cliente, layouts muy particulares para un tipo de contenido puntual, variantes que solo aplican a un sitio.

La pregunta que guía cuándo generalizar: ¿esto va a aparecer en otro proyecto? Si la respuesta es probable sí, se invierte en la abstracción. Si es claramente no, se resuelve puntualmente.

La generalización prematura es tan costosa como la ausencia de sistema. El punto de equilibrio es el que encontrás en la práctica.