El design system que se mantiene: componentes, tokens y docs vivos
Todo design system nace sincronizado y se desalinea con el tiempo, porque componente, token y documentación evolucionan a velocidades distintas. Un agente con acceso a Figma, al repositorio y a la doc audita ese desalineamiento continuamente, antes de que se convierta en bug visual en producción.
Toda empresa que crece crea, en algún momento, un manual: el color oficial de la marca, la fuente, el espaciado entre los elementos. El día en que ese manual nace, todo coincide, el documento, el producto, el material impreso, todos con el mismo azul, la misma fuente. Solo que el tiempo pasa, alguien cambia el azul en el producto a un tono más oscuro sin avisarle a nadie, el manual sigue con el azul antiguo, y seis meses después nadie sabe cuál es el azul real de la marca. Cada pieza se convirtió en su propia fuente de verdad, y discrepan entre sí sin que nadie lo haya decidido a propósito.
El equipo financiero define la meta de margen bruto del trimestre en una planilla modelo, 42%. El dashboard de BI que la dirección revisa todos los días fue configurado con esa meta hace dos trimestres, y nadie actualizó el parámetro. El slide que va al directorio, por su parte, fue copiado de una versión anterior de la presentación y todavía trae 38%. Tres lugares, tres números para la misma meta, y la reunión de directorio recién descubre la divergencia cuando alguien pregunta, en vivo, cuál número es el correcto.
El despacho actualiza la cláusula estándar de ajuste del contrato de prestación de servicios después de perder una disputa sobre índice de corrección. La plantilla maestra en el sistema de gestión documental fue corregida. Solo que el precedente guardado en la base de investigación interna todavía cita la cláusula antigua como referencia, y un contrato firmado hace dos meses, generado a partir de una copia local de la plantilla, también quedó atrás. La divergencia solo aparece cuando un cliente se queja de una cláusula que el despacho ya daba por superada.
La guía de marca define el azul oficial en hexadecimal, y el equipo actualiza ese valor después de un reposicionamiento visual. El CSS del sitio recibe la actualización la semana siguiente. Solo que el material impreso que el distribuidor usa, un catálogo todavía en stock, se imprimió con el azul antiguo, y el slide institucional que comercial usa en reuniones tampoco fue actualizado. La marca hablando tres idiomas distintos al mismo tiempo, sin que nadie lo haya decidido.
La matriz de cargos y salarios define el rango del nivel pleno de ingeniería. La plantilla de carta de oferta que usa reclutamiento fue actualizada con el rango nuevo. Solo que la página de carreras en el sitio todavía muestra el rango antiguo, publicado hace un año, y un gerente recién llegado, sin saber de la actualización, le ofrece al candidato el valor que recuerda de una conversación antigua. Tres rangos distintos para el mismo cargo, circulando al mismo tiempo dentro de la propia empresa.
El PRD de una función nueva define el criterio de aceptación con precisión. La función entra en producción, pero con un ajuste de último momento que nadie documentó de vuelta en el PRD. El changelog que soporte usa para responderle al cliente todavía describe el comportamiento original, el que existía antes del ajuste. Quien descubre la divergencia primero es el cliente, en el ticket de soporte, no el equipo interno.
La tabla de precios oficial en el CRM tiene el valor actualizado después del ajuste anual. La planilla de precios en PDF que un vendedor más antiguo guarda en su computadora todavía tiene el valor del año pasado, y ni siquiera sabe que existe una versión nueva. Cierra un negocio con ese precio antiguo, de buena fe. La discrepancia solo aparece cuando finanzas concilia el contrato firmado con la tabla vigente.
El SOP (procedimiento operativo estándar) de atención de nivel 2 se actualiza después de una revisión de proceso. El material de capacitación nuevo entra en la trilla del próximo mes, pero el equipo que ya trabaja en la operación sigue con el hábito antiguo, porque nadie avisó que el procedimiento cambió. Tres versiones de la forma correcta de hacer las cosas conviviendo en la misma operación, y el SLA se rompe silenciosamente.
La política de retención de datos se actualiza para coincidir con una exigencia nueva de la LGPD. El sistema que efectivamente aplica esa retención, borrando dato después de un plazo, sigue configurado con el plazo antiguo, porque el cambio de política no se convirtió en ticket de TI. El auditor revisa el sistema, encuentra el plazo viejo, y el control que parecía listo en el papel falla en la práctica.
La documentación de la API describe un campo como opcional después de una decisión de simplificar el contrato. El endpoint en producción, por descuido del deploy, sigue exigiendo ese campo como obligatorio. El SDK que los clientes usan para integrar se generó a partir de la documentación nueva, así que ni siquiera lo envía, y la llamada falla en producción para el cliente que siguió la documentación al pie de la letra.
Martes por la mañana, abres Figma para dibujar una pantalla nueva y usas el componente Botón Primario de la biblioteca. Está con el azul nuevo que el equipo aprobó la semana pasada. Solo que cuando el desarrollador implementa la pantalla, el componente de producción todavía usa el token antiguo, porque nadie actualizó el valor en el código después del cambio en Figma. Y la documentación del design system, esa guía que cualquier persona nueva del equipo consulta, todavía muestra una captura de pantalla de hace tres meses, con el azul aún más antiguo. Tres lugares, tres versiones de la misma verdad. Nadie hizo trampa, nadie fue descuidado a propósito: cada lugar simplemente evolucionó a su propia velocidad, y el desalineamiento solo aparece cuando alguien nota que el botón tiene un color en un lugar y otro color en otro.
El plan estratégico anual define la meta de expansión a tres nuevos mercados para fin de año. El sistema de OKR donde el equipo sigue el progreso semana a semana fue configurado con esa meta a principio de año. Solo que el informe trimestral que va al directorio se actualizó una vez, cuando la meta bajó a dos mercados, y el OKR nunca recibió esa corrección. La reunión de revisión se convierte en una discusión sobre qué documento es el correcto, en vez de una discusión sobre la estrategia en sí.
Oye, déjame contarte la escena más molesta, y más común, de cualquier equipo que trabaja con design system. Corriges el azul del botón en Figma un martes por la mañana, sientes ese alivio de resuelto, y tres meses después descubres que el producto en producción tiene otro azul, y la documentación un tercero todavía. Nadie mintió. Nadie fue descuidado a propósito. Cada lugar simplemente siguió su propio ritmo, sin nadie de guardia para mantener a los tres tomados de la mano. Esta lección trata sobre ese desalineamiento que nace solo, y sobre cómo poner un agente a vigilarlo antes de que se convierta en un bug que tu cliente ve antes que tú.
La idea central de esta lección. Todo design system nace sincronizado: el componente de Figma, el token de diseño y la documentación escrita coinciden entre sí el día en que creas el sistema. El problema es que los tres evolucionan a velocidades distintas, y nadie tiene tiempo de mantener a los tres actualizados al mismo tiempo. Es la entropía del design system: con el tiempo, cada pieza se desalinea de la otra, silenciosamente, hasta que un bug visual en producción expone la divergencia a tu cliente. La salida no es confiar en la memoria de alguien para mantener todo igual. Es tener una fuente única de verdad para el token, nombre, valor y uso, y un agente con acceso al repositorio de código, al archivo de diseño y a la documentación, auditando continuamente si los tres todavía coinciden. No evitas el desalineamiento, es inevitable. Pasas a detectarlo antes de que el cliente lo detecte por ti.
01La entropía del design system: sincroniza una vez, se desalinea siempre
Piensa en una fundación recién construida, nivelada con precisión de milímetro el día del vaciado de concreto. Nadie espera que siga perfectamente nivelada para siempre sin mantenimiento, el suelo se acomoda, la estructura se asienta, y por eso existe la inspección periódica de obra. Un design system funciona igual. El día en que creas el componente, el token y la documentación, los tres nacen coincidiendo. Pero cada uno vive en un lugar distinto, con un dueño distinto y un ritmo distinto de actualización: el diseñador toca Figma cuando rediseña una pantalla, el desarrollador toca el código cuando entrega un sprint, y la documentación, pobrecita, solo se recuerda cuando alguien necesita consultarla y no la encuentra.
Nadie decide desalinearse. Es el resultado natural de tres relojes corriendo a velocidades distintas. Y lo peor es que el desalineamiento no avisa: queda invisible hasta el día en que alguien nota que el botón de un lugar no es el mismo botón de otro, y ese día normalmente ya es tarde, porque el cliente que lo notó primero fue quien estaba usando el producto, no quien estaba manteniendo el sistema.
02El token como fuente única de verdad
Aquí está la pieza que resuelve el problema desde la raíz, en vez de remendar el síntoma. Un token de diseño es el nombre dado a un valor visual, "color-primario", "espacio-estandar", "radio-de-borde-card", junto con el valor exacto que carga y dónde debe usarse. La idea central es simple de enunciar y difícil de mantener sin ayuda: el token vive en un único lugar, y Figma, código y documentación jalan de ese lugar en vez de que cada uno guarde su propio número por separado.
Piénsalo así: así como un negocio necesita una ficha estructurada que la máquina pueda leer sin inventar, tu design system necesita un contrato estructurado, nombre, valor, uso, que cualquier herramienta pueda consultar sin adivinar. Mientras el token siga siendo esa fuente única, cambiar el azul se convierte en un evento único, en un solo lugar, que se propaga. El día en que cada pieza vuelve a guardar su propio número, reabres la puerta a la entropía de la sección anterior.
Para el cuadro. Token no es "el color bonito que elegiste". Es el contrato: un nombre estable ("color-primario"), un valor exacto (el hexadecimal, el píxel, la escala), y una regla de uso (dónde debe aparecer). Si Figma, código y documentación coinciden en leer ese contrato del mismo lugar, no tienen cómo discrepar entre sí. Si cada uno guarda su propia copia del valor, la discrepancia es solo cuestión de tiempo.
03El agente audita continuamente, no necesitas esperar que aparezca el bug
Con el contrato definido, falta la parte que nadie tiene tiempo de hacer manualmente todos los meses: revisar si las tres puntas, Figma, repositorio de código y documentación, todavía coinciden con el token. Es exactamente aquí donde un agente con acceso a las tres fuentes se vuelve práctico de verdad. Lee el valor del token en el archivo de diseño, lee el valor equivalente usado en el código del componente en producción, lee lo que afirma la documentación, y compara los tres. Cuando encuentra divergencia, señala exactamente dónde: "Figma dice una cosa, el código dice otra, la doc está desactualizada desde hace X tiempo".
Fíjate en el giro que esto representa. Antes, descubrías el desalineamiento de la forma más cara posible: un cliente notando que un botón está distinto, o un bug visual reportado en producción. Ahora, la auditoría ocurre antes de eso, de forma rutinaria, en un ciclo que tú defines, semanal, en cada deploy, lo que tenga sentido para tu equipo. El agente no decide solo cuál valor es el correcto, no sabe si el azul nuevo de Figma es intencional o un error de quien lo tocó. Solo te muestra la divergencia para que decidas: actualizar el código al valor nuevo, o revertir Figma al valor antiguo. La decisión sigue siendo tuya. El trabajo de vigilar los tres relojes, ese te lo quita de encima.
04El mapa: mantener es rutina, no evento único
Cierra el razonamiento de esta lección con una idea que vale más que cualquier herramienta específica: mantener un design system alineado no es un proyecto que termina, es una rutina que continúa. No "resuelves" la entropía de una vez por todas, instalas una forma barata de detectarla temprano, siempre. El token estructurado es la pieza que le da al agente algo objetivo para comparar, sin eso estaría adivinando igual que la IA que lee un sitio sin schema. Y la auditoría continua es lo que cambia "descubrirlo por el cliente" por "descubrirlo antes que el cliente".
Esto también cierra con lo que viste en las lecciones anteriores de esta trilla: la investigación viva alimenta la decisión con corpus real, el prototipo probado con usuario sintético reduce el riesgo antes del humano real, y ahora el design system mantenido garantiza que la buena decisión que tomaste sigue valiendo dentro de seis meses, y no se convierte en una excepción olvidada en un rincón del producto.
Ahora construye
Elige tres componentes centrales de tu tarea real, los que aparecen en casi toda pantalla: por ejemplo botón primario, campo de input, y card. Para cada uno, verifica si el nombre y el valor del token coinciden en los tres lugares:
- En Figma: abre el componente en la biblioteca y mira el nombre y el valor del token de color (o espaciado, o radio de borde) que usa.
- En el código: pídele a una IA con acceso al repositorio que localice el componente equivalente y muestre qué token (o valor crudo, si no usa ningún token) referencia.
- En la documentación: verifica si la guía del design system, si existe, describe el mismo nombre y el mismo valor que viste en los dos lugares anteriores.
Anota, para cada uno de los tres componentes: ¿coincidió en los tres lugares, o encontraste divergencia? Si encontraste, esa es tu primera lista de pendientes de mantenimiento, y es exactamente el tipo de verificación que un agente puede correr rutinariamente, en vez de que tú repitas este ejercicio manual todos los meses.
Practica
1. ¿Por qué un design system se desalinea con el tiempo aunque nadie haya sido descuidado a propósito?
2. ¿Qué hace que un token de diseño funcione como fuente única de verdad, en vez de otra copia suelta del mismo valor?
3. ¿Cuál es el papel correcto de un agente con acceso a Figma, al repositorio de código y a la documentación, en el mantenimiento de un design system?
4. ¿Cuál es el costo real de descubrir el desalineamiento del design system solo cuando se convierte en bug visual en producción, en vez de detectarlo por auditoría continua?
¿Listo? Cerremos juntos el mensaje de esta lección. Todo design system nace sincronizado y se desalinea con el tiempo, porque Figma, código y documentación evolucionan a velocidades distintas, y nadie tiene tiempo de mantener a los tres tomados de la mano manualmente. La salida no es vigilancia heroica de una sola persona, es un token que funciona como fuente única de verdad, nombre, valor, uso, y un agente con acceso a las tres puntas auditando continuamente si todavía coinciden. Cambias "descubrir el bug por el cliente" por "descubrirlo en la rutina de auditoría, antes de que llegue allá". Mantener un design system no es un proyecto que termina, es un hábito que instalas una vez y repites siempre. Siguiente.
Gracias por el feedback. Esto ayuda a afinar la próxima lección.