Design system

Entre 2023 y 2026 llevé el design system de un SaaS de reservas desde un archivo de estilos sueltos hasta una librería con tokens por contexto, slots y conexión con código. Este caso cuenta las tres etapas, qué decidí en cada una y qué haría distinto.

Contexto

La plataforma tiene muchos años y muchas pantallas. El design system tenía que sostener tanto el producto de gestión como el sitio de reservas que usan los clientes finales, y hacerlo con un equipo chico de diseño.

Punto de partida: el sistema heredado

Cuando entré, en marzo de 2023, el sistema llevaba varios años activo y lo usaban tres diseñadoras. Funcionaba, pero cada pantalla nueva dependía del cuidado de quien la armaba:

• Solo estilos de Figma, sin tokens (todavía no existían las variables).
• Todos los componentes en una misma página, repartidos en frames contenedores, con documentación escueta.
• Casi sin autolayout: apenas uno de cada cinco componentes lo usaba y el resto se ajustaba a mano. El archivo tenía más de 3.200 grupos donde debían ir frames.
• Muchas versiones custom de un mismo componente, mucho detach, y elementos de la interfaz que se repetían pero no existían como componente.
• Un set de íconos con tamaños, grosores y márgenes distintos entre sí.
• Ninguna sincronía con código.

Etapa 2: rebranding y primeros tokens (2024)

En 2024 la marca cambió de verde a morado. El pedido era cambiar solo los colores, pero mi lead vio la oportunidad de ordenar el sistema y me nombró Owner del design system en Figma.

Qué hice

• Armé el primer sistema de tokens de color: 117 primitivos y 197 semánticos.
• Audité todos los componentes, sumé los que faltaban y reconstruí todos los existentes con variantes y autolayout.
• Ordené el archivo con una página por componente y documenté su anatomía para que los devs pudieran crearlos y ajustarlos en código.
• Revisamos accesibilidad y contraste de todos los colores.

Lo que no salió bien

Era mi primer sistema de tokens y lo aprendí haciéndolo. Más de la mitad de los tokens semánticos nombraba un componente concreto: había tokens para el thumb de un toggle en Android o para el hover de un botón secundario. Funcionaba, pero cada componente nuevo pedía tokens nuevos y el sistema crecía sin control. Ese error fue el punto de partida de la siguiente etapa.

Etapa 3: tokens por contexto y conexión con código (2025 y 2026)

Con la modernización visual de la plataforma, rehice el sistema aplicando lo aprendido.

Tokens por contexto de uso, no por componente Pasé de 197 a 133 tokens semánticos de color, organizados por rol: surface, text, border, icon y overlay. Un botón primario ya no tiene sus propios tokens: usa surface/action-primary, igual que cualquier otro elemento con esa función. Los estados de las reservas (confirmada, pendiente, cancelada y el resto) pasaron a ser una familia coherente de tokens en lugar de colores sueltos.

Más que color Sumé tokens de espaciado, bordes y radios, una escala tipográfica completa y sombras. Por primera vez el sistema describía cómo se construye la interfaz, no solo de qué color es.

Componentes más genéricos Menos componentes y más flexibles: 64 sets con variantes optimizadas. En los que más se desarmaban (Dialog, Card, Sheet, Accordion) usé slots, para que el contenido cambie sin hacer detach. Ningún componente usa grupos: los únicos 13 del archivo están en páginas de exploración, contra más de 3.200 en el sistema heredado.

Conexión con código El dev owner del design system en código conectó los componentes a través de Code Connect, y yo amplié la documentación para el handoff: propiedades de cada componente, do’s and don’ts, y guías de contenido. Con esa base llegamos a generar pantallas en Figma y en código usando solo Claude Code y el MCP de Figma.

Íconos Partí de un set gratuito de la comunidad y ajusté cada ícono sobre una grilla geométrica, en forma y grosor de línea, hasta que respondieran a las reglas del sistema y a la nueva identidad de marca.

Un canal para pedir cambios Armé en Notion un formulario para que devs y diseñadores pidieran ajustes, variantes o componentes nuevos, en lugar de resolverlo con un detach. Cada solicitud se evaluaba y quien la había pedido recibía una respuesta: la solución propuesta o la justificación de por qué se descartaba.

Resultado

Comparando los tres archivos:

• Alcance: de 3 diseñadoras usando el sistema heredado a más de 8 diseñadores en la última etapa, además de devs que trabajaban con la versión en código.
• Tokens: de ninguno en el sistema heredado, a 314 solo de color en la versión de 2024, a un sistema que cubre color, espaciado, bordes, radios, tipografía y sombras, con un tercio menos de tokens semánticos de color.
• Construcción: de uno de cada cinco componentes con autolayout a todos, y de más de 3.200 grupos a ninguno dentro de los componentes.
• Handoff: de un archivo sin relación con el código a componentes conectados con Code Connect y pantallas generadas con IA sobre el sistema.

La tercera versión quedó muy avanzada, pero no terminada. Faltaba la etapa que más me interesaba: auditarlo, usarlo en pantallas reales y exigirlo al máximo para encontrar componentes faltantes y ajustes. Los equipos habían empezado a usarlo cuando la estructura y las prioridades de la empresa cambiaron. El equipo dedicado al sistema que se había planeado no llegó a armarse, y la prioridad pasó a ser la velocidad por sobre la consistencia.

Lo que me llevo

• Un token tiene que describir para qué sirve, no dónde se usa. Aprendí esto rompiéndolo primero.
• Los slots y los componentes genéricos reducen el detach más que cualquier regla escrita.
• Un design system necesita dueños y un lugar en las prioridades del negocio, además de buena construcción. Hoy lo planteo desde el principio.
• Si lo retomara, empezaría por lo que quedó pendiente: una auditoría contra las pantallas reales antes de sumar un solo componente más.