Un año de Tucu UI: lecciones de mantener un design system open source

Hace un año empecé a trabajar en Tucu UI, una librería de componentes React open source con variantes de layout estilo macOS. Es un proyecto personal que mantengo en mi tiempo libre, en paralelo a mi trabajo como Forward Deployed Engineer. En este post comparto un balance de lo que aprendí sobre diseño de APIs, documentación y versionado, y qué decisiones hoy reconsideraría.

No es un tutorial de instalación ni un changelog. Es una reflexión para quien esté evaluando algo parecido: ¿vale la pena crear tu propia librería de componentes en 2026, con tantas opciones ya disponibles?

Por qué crear una librería de componentes propia

La pregunta que más me hicieron este año fue simple: ¿por qué no usar algo que ya existe? Hay opciones sólidas, maduras, con comunidades enormes detrás. Mi respuesta es que Tucu UI no nació para competir con ellas, sino para resolver un problema concreto que yo tenía: quería un sistema de componentes que entendiera el layout como parte del diseño, no como un accesorio que se agrega después.

La mayoría de las librerías de componentes ofrecen botones, inputs, modales, cards. Pero el layout —cómo se organiza la aplicación, cómo se comporta el sidebar, cómo interactúan los paneles— suele quedar fuera de su alcance, y cada proyecto termina reinventándolo. En Tucu UI decidí encararlo al revés: el layout es parte central del diseño desde el inicio.

Además, mantener tu propia librería te obliga a tomar postura en cada decisión de API. No hay un "así lo hace todo el mundo" al que aferrarte: cada prop, cada convención de nombres, cada default es una decisión que hay que justificar, aunque sea frente a uno mismo. Es incómodo al principio, pero resultó ser uno de los mejores ejercicios de diseño de APIs que hice en años.

Variantes de layout y temas: el corazón de Tucu UI

Si hay una característica que define a Tucu UI son las variantes de layout inspiradas en macOS. La idea surgió de algo práctico: quería que las aplicaciones construidas con la librería se sintieran como aplicaciones de escritorio, con paneles, barras laterales colapsables y transiciones, pero sin salir del navegador.

Construir esas variantes no fue solo un tema visual. Un layout estilo macOS implica pensar en jerarquía de ventanas, en cómo se comportan los paneles cuando el espacio se reduce y en qué pasa con el contenido cuando el sidebar se colapsa. Cada variante terminó siendo casi un mini sistema dentro del sistema, con sus propias reglas de responsive y sus propios estados.

Con los temas pasó algo parecido. No quería que "tema" significara únicamente cambiar una paleta de colores, sino que también afectara el comportamiento de las variantes de layout: por ejemplo, que un tema pudiera decidir si el sidebar funciona como overlay o como panel fijo. Eso agregó complejidad a la arquitectura interna, pero a cambio ofrece más flexibilidad que la puramente estética.

Lo que aprendí es que las variantes de layout son la parte que genera más feedback y más discusión. Es la más visible, la que primero se nota al probar la librería, y también la que más rápido expone errores de diseño si algo no estaba bien pensado desde el principio.

Documentación y versionado: donde se nota el compromiso real

Si las variantes de layout son la parte vistosa, la documentación y el versionado son lo que sostiene el proyecto en el tiempo. Es fácil escribir un componente lindo; es bastante más difícil escribir la documentación que explica por qué existe, cómo se usa correctamente y qué pasa cuando se combina con otras piezas del sistema.

Con el tiempo entendí que la documentación de un design system no es un anexo: es parte del producto. Si alguien tiene que adivinar cómo funciona una prop, la librería falló, aunque el componente esté bien implementado por dentro. Por eso invertí en que la documentación de Tucu UI muestre ejemplos reales de las variantes de layout y de los temas en acción, no solo listas de props.

El versionado fue otra lección. Cambiar una API en una librería open source tiene un costo: alguien, en algún lugar, tiene esa versión instalada y confía en que no se le rompa nada de un día para el otro. Eso me llevó a ser más cuidadoso con los cambios que rompen compatibilidad, a documentar con claridad qué cambia entre versiones y a tomar semver no como una formalidad sino como una promesa hacia quien decide usar Tucu UI en su proyecto.

Lo que usan los demás (y lo que no)

Una de las cosas más interesantes de mantener una librería open source es ver qué parte termina usándose realmente, más allá del caso de uso que uno imaginó. Las variantes de layout estilo macOS son lo que más atención genera: son la seña de identidad de Tucu UI y lo que la diferencia de otras librerías. El theming, en cambio, se usa de forma más silenciosa: la gente lo configura una vez y no vuelve a tocarlo, lo cual, pensándolo bien, es señal de que está funcionando como debería.

Un balance sincero

Después de un año, sigo pensando que crear y mantener tu propia librería de componentes tiene sentido cuando hay un problema específico que las opciones existentes no resuelven del todo. En mi caso fue el layout como parte integral del diseño. Las variantes estilo macOS terminaron siendo el eje sobre el que se construyó el resto, y la documentación y el versionado, aunque menos vistosos, son lo que lo sostiene.

También hay límites que reconozco: es un proyecto que avanza al ritmo de mi tiempo libre, y algunas decisiones tempranas de API las reconsideraría hoy.

Qué me llevo

• Diseñar una API propia obliga a justificar cada decisión, y eso mejora el criterio de diseño más que usar librerías ajenas.
• Tratar el layout como parte del diseño, y no como un accesorio, condiciona toda la arquitectura de la librería.
• La documentación con ejemplos reales es parte del producto, no un anexo.
• Versionar con cuidado es una forma de respeto hacia quienes dependen de tu código.
• Conviene crear una librería propia por un problema concreto, no para tener "la propia".

Si estás trabajando en un design system o evaluando si construir uno, me interesa intercambiar experiencias: podés escribirme por LinkedIn. Y si querés ver en qué más estoy trabajando, en mi portfolio cuento otros proyectos: https://estebanburgos.com.ar/portfolio.