Importar tokens existentes sin perder nada

Antes de confiar un archivo que te importa a cualquier herramienta de tokens, haz un experimento: importa el archivo, no cambies nada, expórtalo y compara el resultado con el original. La prueba completa lleva unos cinco minutos, y el diff es la carta de recomendación de la herramienta: muestra exactamente qué considera suyo la herramienta y qué reescribe en silencio.

Importar design tokens sin perder nada se reduce a una propiedad: una herramienta que se comporta bien es dueña de las secciones que genera y conserva todo lo demás, de modo que guardar→cargar→guardar es un punto fijo: el archivo que sale es el archivo que entró, salvo donde pediste un cambio. Una herramienta con esa propiedad puede adoptarse de forma incremental; una sin ella obliga a una migración de todo o nada. Este artículo cubre la mecánica de archivo de la importación y la reexportación; los fundamentos más amplios viven en nuestra guía de design tokens.

¿Por qué da miedo importar tokens?

Porque un archivo de tokens real rara vez es solo lo que generó una herramienta. Dale a un archivo un año en producción y acumulará trabajo hecho a mano: tokens de componente que alguien añadió para una excepción genuina, bloques $extensions que llevan metadatos de plataforma, los tiempos de animación de un colega de los que ningún generador tiene modelo alguno. Esa acumulación es el archivo haciendo su trabajo: una sola fuente, que crece con el sistema.

El escenario que da miedo es una herramienta ingenua encontrándose con ese archivo. La importación ingenua lee las partes que la herramienta entiende; la exportación ingenua regenera el archivo entero a partir de lo que leyó. Importar → exportar → la mitad del archivo desaparecida: la sección de animación, las extensiones, las excepciones añadidas a mano; todo lo que la herramienta no modeló, borrado por omisión más que por intención. Los equipos que pasan por esto una vez aprenden a mantener la herramienta lejos del archivo real y a gestionar los tokens a mano, lo que renuncia en silencio a casi todo aquello para lo que servía la herramienta.

¿Qué es el contrato de ida y vuelta?

Tres cláusulas. Primera, la propiedad es por secciones: la herramienta declara qué partes del archivo genera —las rampas de color, la escala tipográfica, las capas semánticas— y trata todo lo demás como territorio ajeno. Segunda, la conservación es literal: las secciones ajenas pasan sin cambios, no “reserializadas pero equivalentes”. Tercera, la salida es canónica: la herramienta escribe sus propias secciones en una única forma y orden estables, de modo que dos exportaciones difieren solo donde difieren las decisiones y los diffs siguen siendo revisables.

El experimento inicial comprueba las tres a la vez. Guardar→cargar→guardar debería ser un punto fijo —un estado que la operación asigna a sí mismo, en el sentido tomado de las matemáticas (punto fijo)— y la ida y vuelta de Scale Composer está probada exactamente así: un archivo importado se reexporta con las secciones no tocadas intactas, y el orden canónico mantiene mínimo cada diff posterior.

¿Cómo se ve una sección conservada tras un ciclo real?

Toma un archivo con una sección generada y otra añadida a mano:

{
  "color": {
    "brand": {
      "600": { "$type": "color", "$value": "#2563eb" }
    }
  },
  "motion": {
    "duration-fast": { "$type": "duration", "$value": "150ms" },
    "duration-slow": { "$type": "duration", "$value": "400ms" }
  }
}

La sección color es territorio del generador; motion es el trabajo hecho a mano de un colega: una herramienta de color y escalas no tiene concepto de duraciones. Importa el archivo, vuelve a derivar la paleta a partir de un nuevo color semilla y exporta. Las entradas de color.brand cambian: brand-600 conserva su nombre y guarda un nuevo valor en lugar del antiguo #2563eb —oklch(0.546 0.215 262.9)— con la rampa vuelta a derivar a su alrededor, y el diff contiene esas líneas y nada más. motion regresa sin cambios, con ambos tiempos intactos, todavía en su lugar.

Ejecuta este ciclo sobre un archivo importado en Scale Composer: carga un archivo DTCG que lleve secciones que la herramienta no genera, ajusta el color semilla y exporta: las secciones de color se vuelven a derivar mientras las secciones añadidas a mano pasan sin tocarse.

¿Qué deberías auditar antes de confiar tu archivo a una herramienta?

Cuatro comprobaciones, ordenadas por lo que detectan:

1. La ida y vuelta vacía. Importa, no cambies nada, exporta, compara. Las diferencias aceptables viven solo en las secciones que la herramienta genera (reserialización canónica); un diff que toque cualquier otra cosa es la herramienta diciéndote qué acabará comiéndose.
2. La supervivencia de $extensions. El hogar que el formato DTCG designa para los metadatos específicos de herramienta y de plataforma es precisamente el contenido que un importador descuidado descarta. Comprueba que el tuyo pasó intacto.
3. Comentarios: sinceramente, no hay ninguno que perder. DTCG es JSON, y JSON no tiene sintaxis de comentarios; las notas que importan van en los campos $description, que forman parte del formato y sobreviven a cualquier herramienta conforme. Si tu flujo de trabajo ha estado guardando anotaciones en algún sitio frágil, la importación es un buen momento para migrarlas allí.
4. La estabilidad del orden. Exporta dos veces y luego exporta tras un cambio trivial. Si el orden de las claves se baraja entre ejecuciones, cada diff futuro enterrará el cambio real bajo otros fantasma, y revisar los cambios de tokens se convertirá en arqueología mientras viva el archivo.

¿Cómo hace la conservación que la adopción sea incremental?

Porque una herramienta que conserva no exige el archivo entero. Un equipo puede entregarle primero las secciones de color —importar, volver a derivar, exportar, revisar un diff que solo toca el color— mientras el espaciado y la tipografía siguen gestionándose a mano en el mismo archivo. El trimestre siguiente, el espaciado. La herramienta se va integrando en el archivo sección por sección, cada paso un pequeño cambio revisable en lugar de un evento de migración.

Este es el rédito práctico de la propiedad de punto fijo, y la razón intuitiva por la que importa: la confianza se construye acotando el radio de impacto. Una herramienta que solo puede reescribirlo todo pide confianza total el primer día; una herramienta que conserva pide confianza solo sobre las secciones que le entregas, y las secciones que aún no se ha ganado nunca estuvieron en riesgo. “Cambiar de herramienta de tokens” deja de ser una decisión y se convierte en una serie de experimentos baratos y reversibles.

Haz la prueba antes de necesitar confiar en ella

La auditoría no es trabajo hipotético: son cinco minutos y un diff. Haz la prueba de guardar→cargar→guardar en Scale Composer: importa un archivo de tokens, expórtalo sin tocarlo y compara; luego haz un cambio deliberado y confirma que el diff es exactamente ese cambio y nada más.