Revisar cambios de tokens en Git

El color de acento cambió un martes, y nadie lo decidió. El pull request se titulaba «regenerar tokens tras corregir el espaciado»; el archivo de tokens mostraba cuarenta y una líneas modificadas, una de las cuales redirigía accent de brand-600 a secondary-500. Quien lo revisó vio un archivo generado y un build en verde, y lo aprobó. Tres semanas después, marketing preguntó por qué los botones de registro tenían un color distinto en las nuevas capturas. git log -p encontró la línea en cerca de un minuto — que es la amarga comedia de la historia: el historial era perfecto, y la revisión que ese historial existe para permitir tardó diez segundos que nadie invirtió.

Los design tokens pertenecen al control de versiones porque hacen que las decisiones de diseño se comporten como código: el historial registra quién cambió el color de acento, cuándo y — en el mensaje del commit — por qué; un pull request se convierte en un artefacto de revisión de diseño; y un cambio malo es un git revert en lugar de un proyecto de arqueología. Pero los beneficios solo llegan con disciplina de flujo de trabajo: diffs mantenidos pequeños y estables, una lista de verificación de revisión que lee las líneas de tokens como decisiones de diseño, y los cambios regenerados separados de las ediciones manuales.

Este es el capítulo de gobernanza de nuestra guía de design tokens: cómo se lee un diff de tokens, qué debería preguntarle quien revisa, y la etiqueta que mantiene revisable un archivo generado. Da por supuesto el patrón de proyecto donde el archivo de tokens vive en el repositorio y pasa por la misma puerta que el código.

¿Por qué los design tokens pertenecen al control de versiones?

El control de versiones le da a cualquier archivo tres propiedades — historial atribuido, cambio con puerta, un pasado restaurable — y los tokens son inusuales entre los artefactos de diseño por poder reunir las tres. Por lo demás, las decisiones de diseño tienen una procedencia notoriamente endeble: la respuesta a «¿por qué el color de acento es este azul?» suele vivir en un hilo de chat abandonado, una vieja presentación o la memoria de alguien. Una vez que la decisión es una línea en un archivo versionado, el mensaje del commit es un lugar donde la justificación queda permanentemente junto al cambio que explica — re-point accent to secondary for the promo quarter; revert after Q3 documenta una decisión de diseño de forma más duradera de lo que logra la mayoría de la documentación de diseño.

La reversión es la misma propiedad leída al revés. Un cambio de marca que hay que deshacer es un solo revert cuando tiene forma de token; sin el archivo es una cacería por las hojas de estilo de cada valor que cambió, semanas después de que alguien recuerde haberlo cambiado.

La razón intuitiva por la que la revisión funciona aquí, y no en la mayoría de los artefactos de diseño: la revisión depende de que un cambio sea lo bastante pequeño como para caber en tu cabeza. Un cambio en un archivo de diseño es una imagen — quien revisa ve el nuevo estado, no el delta. Un cambio de token es el delta: un puñado de líneas con nombre. Los tokens comprimen la capa de diseño a un tamaño que la revisión puede procesar de verdad, y todo lo demás en este artículo se apoya en esa compresión.

¿Cómo se lee un diff de tokens?

Aquí tienes un diff de seis líneas, recortado a sus líneas modificadas y anotado con las secciones en las que se sitúan — un paso de espaciado ajustado más estrecho, un acento redirigido, un rol semántico añadido:

@@ spacing @@
-"space-3":    { "$value": "16px", "$type": "dimension" }
+"space-3":    { "$value": "14px", "$type": "dimension" }
@@ semantic @@
-"accent":     { "$value": "{color.brand.600}",     "$type": "color" }
+"accent":     { "$value": "{color.secondary.500}", "$type": "color" }
+"text-promo": { "$value": "{color.neutral.900}",   "$type": "color" }
@@ semantic-dark @@
+"text-promo": { "$value": "{color.neutral.50}",    "$type": "color" }

Cada línea debería disparar una pregunta de revisión específica:

• space-3, 16px → 14px. Un primitivo — el cambio se propaga a cada consumidor. ¿Quién lee space-3? Si la respuesta es el padding de las tarjetas, los huecos de las listas y las filas de formulario, ¿el ajuste más estrecho se lee como se pretendía en todos ellos, o iba dirigido a una sola pantalla saturada? Un primitivo editado para arreglar un componente es un clásico olor a token; el arreglo dirigido vive en el componente, no en el paso compartido.
• accent, redirigido. Un semántico — dirigido, pero portante: qué componentes consumen accent, y ¿el texto existente sobre el acento sigue superando su umbral mínimo de contraste frente al nuevo relleno? Una línea en el diff, una re-verificación completa detrás. Más una pregunta de proceso: ¿es esta redirección lo que el título del PR dice que hace el PR?
• text-promo, añadido dos veces. Un nuevo rol: ¿es un trabajo real que algún segundo consumidor vaya a usar, o algo de una sola vez que pertenece más cerca de su componente? ¿El nombre sigue las convenciones? Aparece en ambas secciones de tema — bien; un semántico solo para modo claro es un bug de modo oscuro con retardo.

Fíjate en lo que quien revisa nunca preguntó: si el JSON se parsea. Las máquinas comprueban la sintaxis antes de que empiece la revisión; todo el trabajo de quien revisa es el conjunto de preguntas de diseño que ningún linter puede hacer.

Abre en Scale Composer el archivo del que provienen estas líneas — el archivo canónico de tokens tal como vive en un repositorio, con las secciones en orden estable, llevando los mismos nombres que muestra el diff.

¿Qué debería comprobar la revisión de un pull request de tokens?

Cuatro comprobaciones cubren la mayor parte de lo que importa:

1. Radio de impacto. ¿Qué capa cambió? Un cambio de primitivo se propaga a todo lo que lo referencia, directamente o mediante alias — una edición de una línea puede ser el cambio más grande de la versión. Una redirección de semántico es dirigida: los consumidores de ese único rol. Lee la capa primero; fija la profundidad que necesita el resto de la revisión.
2. Contraste, en cada línea de color. Cualquier relleno modificado o rol de texto redirigido implica re-verificar las combinaciones en las que participa — una línea aquí, porque la verificación de contraste es una disciplina en sí misma; la revisión es donde se agenda.
3. Consistencia de nombres. Contrasta los tokens nuevos con las convenciones del proyecto en el último momento barato: antes del merge, un renombrado es un comentario de revisión; después del merge, es un cambio rompedor para cada consumidor.
4. Sin huérfanos. Un token nuevo debería ser consumido por algo, o se publica como especulación que alguien tendrá que emparejar por nombre más tarde. Un token eliminado no debería estar referenciado por nada — un {reference} colgante es un fallo en la siguiente exportación, encontrado ahora o encontrado después.

¿Cómo mantienes legibles los diffs generados?

Los archivos generados tienen un modo de fallo especial en la revisión: si la herramienta reordena claves o reformatea en cada guardado, cada diff es una reescritura, y quienes revisan aprenden a ojear por encima — que es exactamente como se publicó el acento del martes. Tres disciplinas lo evitan:

• Serialización estable. La herramienta debe escribir el archivo de la misma forma cada vez. Scale Composer serializa canónicamente — orden estable de secciones, orden estable de claves; guardar, cargar y volver a guardar es un punto fijo probado — de modo que un cambio de un solo valor produce un diff de aproximadamente una línea, y cuarenta y una líneas modificadas significan cuarenta y una decisiones en lugar de ruido.
• Separa la regeneración de las ediciones manuales. Un commit que vuelve a derivar el sistema («re-derivar tras cambiar la semilla») y un commit que añade a mano una sección exigen modos de revisión distintos — el primero se revisa por sus parámetros, el segundo línea por línea. Mezclarlos entierra el juicio dentro del ruido.
• Mensajes de commit que enuncian la decisión. «ajustar space-3 a 14px — pasada de densidad en formularios» se lee como justificación de diseño un año después; «actualizar tokens» no se lee como nada.

Un límite es deliberado: Scale Composer no tiene una vista de diff. Hacer diffs es tarea de git — la tarea de la herramienta es mantener el archivo apto para diff, y por eso la serialización canónica es la funcionalidad y una interfaz de diff no lo es.

Pasa el próximo cambio por revisión

El flujo de trabajo se defiende solo la primera vez que un diff atrapa algo. Reajusta un valor en Scale Composer y expórtalo — ajusta más estrecho un paso de espaciado o redirige un rol, guarda sobre el archivo commiteado y lee lo que git diff te muestra: el cambio entero en unas pocas líneas estables, listo para las cuatro preguntas de quien revisa.