Una única fuente de verdad: el flujo de trabajo de tokens

Los design tokens le dan a un producto una única fuente de verdad cuando un archivo de tokens canónico es el lugar donde vive cada decisión de diseño, y cada consumidor —hojas de estilo, tema de utilidades, variables de la herramienta de diseño— se genera a partir de él. Mantener eso cierto es un bucle de cinco pasos: decidir en la herramienta de diseño, exportar el archivo canónico junto con sus formatos de consumo, hacer commit para que el pull request sea la puerta de revisión, consumir los formatos generados en el código y los archivos de diseño, y encaminar cada cambio posterior de vuelta por el paso uno.

La expresión single source of truth —fuente única de verdad— viene del diseño de sistemas de información: almacena cada dato exactamente una vez y deriva cualquier otra aparición de él, de modo que la coherencia entre copias se mantiene por estructura y no por diligencia. Este artículo traslada ese principio al flujo de trabajo cotidiano de los tokens: el bucle, el fallo que previene cada paso, quién posee qué, y un cambio rastreado de principio a fin. Es el capítulo sobre el flujo de trabajo de nuestra guía de design tokens.

¿Cuáles son los cinco pasos del flujo de trabajo de tokens?

1. Decidir — en la herramienta de diseño. Parámetros de escala, colores semilla, roles semánticos: Scale Composer es la superficie donde se toman esas decisiones y sus consecuencias se ven — un cambio de color semilla vuelve a derivar las rampas y los roles para ambos temas mientras miras.
2. Exportar — el archivo canónico DTCG junto con los formatos de consumo generados a partir de él: propiedades personalizadas de CSS, un bloque @theme de Tailwind v4, Figma Variables con hex al lado. Un conjunto de decisiones, varias representaciones.
3. Commit — el archivo de tokens aterriza en el repositorio, y el pull request se convierte en la revisión de diseño: historial, justificación en los mensajes de commit, capacidad de revertir.
4. Consumir — el código referencia las propiedades personalizadas o el tema; los diseñadores enlazan las variables de Figma. Nadie, en ninguno de los dos lados, escribe un valor en crudo.
5. Cambiar — la siguiente edición empieza de nuevo en el paso uno: la herramienta reimporta su propio archivo, el ajuste se hace contra la verdad actual, y el bucle se repite. La preservación en ida y vuelta hace que esto sea seguro — las secciones que la herramienta no genera sobreviven a la reimportación intactas, una propiedad probada y no una esperanza.

Dibujado en una pizarra, el flujo de trabajo es un círculo, no una tubería — y el círculo es la clave. Una tubería termina, y aquello en lo que termina empieza a acumular ediciones manuales.

¿Qué fallo previene cada paso?

Omite un paso y un fallo específico y predecible aparece en su lugar:

• Omite la exportación y copia a mano en su lugar. Los valores reescritos a mano en CSS o Figma son segundas fuentes desde el momento en que aterrizan. La deriva — el archivo de diseño y el build discrepando sobre valores que se supone que son idénticos — es la enfermedad que los tokens existen para curar, y copiar a mano la reintroduce en el primer plazo de entrega.
• Omite el commit. El archivo vive en el estado de la herramienta o en un solo portátil: sin revisión, sin historial, sin poder revertir, y «¿qué versión es la real?» vuelve como una pregunta con varias respuestas.
• Omite el bucle de cambio. Las ediciones ocurren aguas abajo en su lugar — alguien parchea directamente el CSS generado. Ahora el archivo canónico es ficción: la siguiente exportación honesta sobrescribe el parche en silencio, así que la gente deja de exportar, y la fuente de verdad pasa a ser de solo escritura, y luego se abandona. La disciplina de reimportación es lo que mantiene el bucle cerrado — porque la herramienta relee su propio archivo, pasar por él nunca es más lento que rodearlo.

Consumir tiene su propio fallo, más silencioso — referenciar valores exportados copiándolos en lugar de por nombre — pero eso es disciplina de enlace en el punto de uso, no un bucle roto.

El resumen intuitivo: una única fuente de verdad no es algo que un equipo configura una vez — es una propiedad que tiene que sobrevivir a cada cambio hecho después, y cada fallo de arriba es el mismo suceso, una segunda fuente brotando donde se omitió un paso. El bucle está diseñado para que en cada paso la acción más barata sea también la correcta: regenerar le gana a reescribir, hacer commit le gana a enviar un archivo por correo, reimportar le gana a volver a decidir. Los flujos de trabajo perduran cuando el camino perezoso y el camino correcto son el mismo camino.

Mira una sola fuente alimentando a cada consumidor en Scale Composer — las secciones del archivo canónico a un lado, y los mismos nombres representados como exportaciones de CSS, Tailwind y Figma al lado.

¿Quién posee cada paso?

El bucle se reparte limpiamente entre los roles. El diseñador posee decidir — ahí viven los juicios de valor. Exportar y commit son el apretón de manos donde una decisión privada se convierte en propiedad compartida y revisable. Los ingenieros poseen consumir en el código; los diseñadores lo poseen en el archivo de diseño. Cambiar pertenece a quien lo haya necesitado — encaminado por la misma puerta que el de todos los demás.

Un marco útil — y es un marco, no un hecho técnico: el archivo de tokens es la API entre diseño e ingeniería, y recompensa las mismas disciplinas que recibe una API. Versionado, mediante commits. Revisado, mediante pull requests. Documentado, mediante campos $description que viajan con los tokens. Deprecado con un periodo de gracia en lugar de roto de la noche a la mañana. El marco también predice la sociología: los desacuerdos sobre un valor dejan de ser guerras territoriales de diseño contra ingeniería («el archivo dice 22, el build dice 20») y se convierten en una propuesta de cambio contra un único artefacto que ambos lados leen.

En un equipo de dos personas — o de una — el bucle es el mismo con menos traspasos. Lo que compran los pasos ahí no es coordinación sino memoria: el historial de commits es el registro de diseño.

¿Cómo se retira un token sin romper a los consumidores?

Con una transición, exactamente como haría una API. Renombrar o eliminar un token es un cambio disruptivo para todos los consumidores del nombre antiguo, así que el nombre antiguo hace de alias del nuevo durante una versión — "accent-strong": { "$value": "{semantic.accent}" } mantiene resolviendo las referencias obsoletas mientras se anuncia el cambio — y la eliminación ocurre después de que los consumidores hayan migrado, verificado buscando el nombre antiguo en lugar de confiando en la suerte. Borrar de golpe significa que la ruptura se descubre en el siguiente build si tienes suerte, y en visuales ya publicados si no.

¿Cómo se ve un cambio a través del bucle?

Rastrea uno real: la marca vuelve a sembrar su color de acento pasándolo de azul — #2563eb, que es oklch(0.546 0.215 262.9) — a un índigo más profundo.

1. Decidir. El diseñador carga el design-tokens.json del proyecto en Scale Composer — el archivo commiteado, no una copia obsoleta — y reemplaza el color semilla de marca. La rampa se vuelve a derivar en torno al nuevo tono; los roles semánticos siguen apuntando a los mismos pasos; el modo claro y el oscuro se derivan de nuevo, ambos, a partir de la única decisión.
2. Exportar. El archivo canónico junto con los formatos de CSS, Tailwind y Figma. Cambiado: los valores de la rampa y las resoluciones de rol. Sin cambiar: nombres, tipografía, espaciado — todo lo que el cambio no tocó pasa por la ida y vuelta intacto.
3. Commit. El PR dice «resembrar el acento a índigo — refresco de marca del Q4». El revisor ve un diff de solo valores, confirma que los emparejamientos sobre el acento siguen superando sus mínimos de contraste, hace la pregunta del radio de impacto, y aprueba. El mensaje de commit es la entrada del registro de diseño.
4. Consumir. Al hacer merge, --accent se resuelve al nuevo valor en todos los lugares donde se referencia — sin cambios en el código de los componentes. El archivo de diseño actualiza sus variables a partir de la nueva exportación, y las pantallas enlazadas se resuelven de nuevo sin rediseño.
5. Cambiar. Dos semanas después, el paso de hover necesita un pequeño ajuste. La edición empieza cargando el mismo archivo — que aún coincide con lo que se publicó, porque nada esquivó el bucle.

Lo que vio cada rol: el diseñador hizo una edición, el revisor leyó un diff legible, el ingeniero publicó cero cambios de código, y el producto se desplazó en un único movimiento coordinado. Trabajo del tamaño de una decisión para un cambio del tamaño de una decisión — para eso sirve el bucle.

Ejecuta el bucle una vez tú mismo

El bucle es más persuasivo en el paso cinco, cuando la herramienta te devuelve tus propias decisiones intactas. Cambia un color semilla y observa cómo se propaga — cada exportación se vuelve a representar a partir de la misma fuente, y las secciones que tu cambio no tocó regresan exactamente como entraron.