Migrar tokens de diseño personalizados a Figma Variables significa reemplazar JSON, mapas SCSS y propiedades CSS personalizadas con una única fuente de verdad que exporta directamente a formato DTCG — y esa migración es la inversión de mayor retorno que un equipo de sistema de diseño puede hacer en 2026. Los archivos de tokens personalizados se desincronizan de producción en el momento en que se editan manualmente; Figma Variables permanece vinculado al lienzo, propaga cambios a través de cadenas de alias automáticamente y produce JSON DTCG que Style Dictionary y los generadores de código consumen sin capas de traducción intermedias. El W3C Design Tokens Community Group mantiene la especificación DTCG que hace que este pipeline sea interoperable entre herramientas.
Flujos relacionados: Guía de Figma Design Tokens para arquitectura de Variables y exportación DTCG, plugins de flujo de tokens para configuración de pipeline, y encontrar valores sin tokenizar para auditar lo que estás migrando.
En resumen
- Audita tu inventario de tokens personalizados antes de tocar Figma — los códigos hexadecimales sin tokenizar y los números mágicos son tu línea base de migración.
- Mapea primero las primitivas (valores crudos) y después la semántica (cadenas de alias) — invertir este orden crea tokens duplicados.
- Usa JSON DTCG como formato puente de migración — desacopla los datos internos de Figma de tu pipeline de código.
- Los tokens de animación (duración, easing) van en una colección separada — mezclarlos con color/espaciado crea conflictos de modo.
- Ejecuta una auditoría de cobertura después de la migración — Atomize escanea valores que no se tokenizaron durante la transición.
Por qué los archivos de tokens personalizados fallan a escala
Los archivos de tokens personalizados — objetos JSON, mapas de variables SCSS, propiedades CSS mantenidas manualmente — fallan en el momento en que dos equipos los tocan. Un desarrollador actualiza blue/500 en el mapa SCSS pero olvida la exportación JSON; un diseñador cambia el hexadecimal en Figma sin actualizar el repositorio de código; la reunión de handoff consume 20 minutos conciliando qué valor es el autoritativo. Esto no es un problema de herramientas — es un problema de fuente única de verdad. Figma Variables lo resuelve haciendo del archivo del lienzo la fuente: un diseñador cambia un valor de variable en Figma, la exportación DTCG lo recoge y el pipeline de código se reconstruye sin pasos de sincronización manual.
La migración no tiene costo cero. Los equipos con más de 200 tokens personalizados distribuidos en múltiples archivos, frameworks y plataformas necesitan una secuencia de migración deliberada. El resto de esta guía presenta esa secuencia — auditar, mapear, exportar, verificar — con pasos concretos para cada fase. El centro de ayuda de Figma documenta las capacidades de Variables que forman el estado objetivo.
Fase 1: Audita tu inventario de tokens personalizados
Antes de crear una sola variable en Figma, inventaría cada fuente de tokens en tu base de código. Los tokens de diseño se esconden en más lugares de lo que los equipos imaginan: propiedades CSS personalizadas en :root, mapas de variables SCSS, archivos de configuración de Tailwind, archivos JSON de temas y llamadas var() en línea dentro de estilos de componentes. Cada fuente debe ser localizada, extraída y listada antes de que comience la migración — omitir una fuente significa que ese token permanece sin tokenizar después de la migración.
Ejecuta una auditoría automatizada primero. El escáner de encontrar valores sin tokenizar de Atomize detecta códigos hexadecimales crudos, valores de espaciado y tamaños de fuente dentro de archivos Figma — valores que los diseñadores colocaron sin crear una variable. Para los tokens del lado del código, busca en tu repositorio declaraciones de propiedades CSS personalizadas, asignaciones SCSS $variable y claves de temas JSON. Lista cada token en una hoja de cálculo con columnas: nombre del token, valor actual, archivo de origen y si tiene un equivalente en Figma.
Lugares comunes donde se esconden los tokens
- Bloques
:root { }en archivos CSS globales — a menudo la mayor fuente única de tokens theme.extendde Tailwind entailwind.config.js— colores, espaciado, tamaños de fuente, radios de borde- Parciales SCSS
$_variables.scss— verifica mapas anidados con patrones de accesomap-get() - Archivos JSON de temas (
tokens.json,theme.json) — a menudo sincronizados manualmente con el diseño, siempre desincronizados - Propiedades CSS personalizadas a nivel de componente —
var(--button-bg, #3B82F6)con valores predeterminados hardcodeados - Keyframes de animación con valores
mshardcodeados — estos se convierten en tokens de duración en la migración
Fase 2: Mapea primitivas, luego semántica
El error de migración más común es mapear tokens semánticos antes que las primitivas. Un token semántico como color/text/primary referencia una primitiva como color/gray/950 — no puedes crear la cadena de alias hasta que la primitiva exista. Comienza con tokens de valor crudo: cada color hexadecimal único, valor de espaciado en píxeles, tamaño de fuente, radio de borde y duración en tu inventario. Crea una variable Figma por valor único, no por uso — si #030712 aparece en 14 lugares en tu SCSS y CSS, creas una variable gray/950, no 14.
Crea las primitivas dentro de una colección de variables Figma dedicada. Nombra la colección primitives y organiza por categoría usando grupos separados por barras: gray/50, gray/100, blue/500, space/4, space/8, font/size/14, font/size/16, radius/sm, radius/md, duration/fast, duration/normal. El separador de barra crea la jerarquía de grupos que Figma usa para el alcance — mantener los tokens de color, espaciado, tipografía y animación en grupos separados previene conflictos de modo más adelante.
/* Colección de primitivas — valores crudos, sin alias */
gray/50 → #F8FAFC
gray/950 → #030712
blue/500 → #3B82F6
space/4 = 4px
space/8 = 8px
font/size/14 = 14px
radius/md = 8px
duration/fast = 150ms
easing/default = cubic-bezier(0.4, 0, 0.2, 1)Una vez que las primitivas existen, crea una segunda colección llamada semantic y asigna cada token semántico como alias de su primitiva. color/text/primary apunta a gray/950 de la colección de primitivas. color/background/default apunta a gray/50. space/component/gap apunta a space/4. Esta arquitectura basada en alias es lo que hace que Figma Variables sea fundamentalmente diferente de los archivos planos de tokens personalizados: cambiar una primitiva se propaga a través de cada alias semántico automáticamente.
/* Colección semántica — alias a primitivas */
color/text/primary → {gray/950}
color/background/default → {gray/50}
color/interactive/default → {blue/500}
space/component/gap → {space/4}
radius/button → {radius/md}
duration/transition → {duration/fast}Fase 3: Exporta a DTCG y conecta el pipeline de código
JSON DTCG (Design Tokens Community Group) es el formato puente de migración. Desacopla la representación interna de variables de Figma de cualquier pipeline de código que consuma los tokens — propiedades CSS personalizadas, constantes TypeScript, presets de Tailwind o formatos específicos de plataforma. Exporta tanto las colecciones de primitivas como las semánticas como JSON DTCG. La exportación contiene $type, $value y referencias de alias que las herramientas downstream resuelven en valores finales de plataforma.
{
"color": {
"text": {
"primary": {
"$type": "color",
"$value": "{color.gray.950}"
}
},
"background": {
"default": {
"$type": "color",
"$value": "{color.gray.50}"
}
}
},
"duration": {
"transition": {
"$type": "duration",
"$value": "{duration.fast}"
}
}
}Conecta Style Dictionary para consumir la salida JSON DTCG. Style Dictionary resuelve referencias de alias, transforma valores a formatos específicos de plataforma y genera propiedades CSS personalizadas, constantes TypeScript, variables SCSS o XML de Android en un solo paso de build. La decisión clave de configuración: apunta Style Dictionary a la ruta del archivo JSON DTCG como su fuente de entrada, no a un archivo de tokens mantenido manualmente. A partir de este momento, la exportación DTCG desde Figma es la fuente de verdad de los tokens — los archivos personalizados mantenidos manualmente se archivan.
{
"source": ["tokens/primitives.json", "tokens/semantic.json"],
"platforms": {
"css": {
"transformGroup": "css",
"buildPath": "dist/css/",
"files": [{
"destination": "variables.css",
"format": "css/variables"
}]
}
}
}Fase 4: Verifica — audita lo que no se migró
Una migración nunca está completa en el primer intento. Se escapan valores — un color de borde en un componente profundamente anidado, un valor de espaciado en un auto-layout gap, un tamaño de fuente dentro de un estilo de texto que no se vinculó a una variable. Ejecuta una auditoría de cobertura después de la migración para detectar cada valor en el archivo Figma que aún carece de un enlace a variable.
La auditoría de cobertura de Atomize escanea el archivo completo y reporta rellenos, trazos, valores de espaciado, tamaños de fuente y radios de borde sin tokenizar — agrupados por página y componente. Ejecuta este escaneo inmediatamente después de completar el mapeo de variables. Cada resultado es una brecha de migración: un valor que existía en tu inventario de tokens personalizados pero que se omitió durante la transición a Figma Variables. Vincula esos valores restantes a la variable primitiva o semántica apropiada.
Tokens de animación y duración — una colección separada
Los tokens de animación — valores de duración, curvas de easing y tiempos de retardo — requieren su propia colección en Figma Variables. Mezclar tokens de duración en la colección de primitivas con colores y espaciado crea conflictos de modo: un cambio a modo oscuro no debería cambiar los tiempos de animación, pero si comparten una colección, Figma los obliga a compartir modos. Crea una colección dedicada motion con grupos para duration, easing y delay.
| Tipo de token | Tipo Figma | Valor de ejemplo | Colección |
|---|---|---|---|
| Duración | Number | 150ms → 150 | motion |
| Curva de easing | String | cubic-bezier(0.4, 0, 0.2, 1) | motion |
| Retardo | Number | 300ms → 300 | motion |
| Keyframe de opacidad | Number | 0 → 1 fade | primitives (opacity) |
Figma Variables soporta tipos number y string de forma nativa — los valores de duración se convierten en variables numéricas (la unidad se aplica en el momento de exportación mediante transformaciones de Style Dictionary), y las curvas de easing se convierten en variables de string. La especificación de tokens de movimiento de Material Design 3 proporciona un modelo de referencia útil para nombrar tokens de duración y easing de manera consistente en un sistema de diseño.
Coexistencia con código legacy durante la migración
Las bases de código grandes no pueden migrar a tokens exportados por DTCG de la noche a la mañana. Durante la transición, ejecuta ambos pipelines en paralelo: el nuevo pipeline DTCG → Style Dictionary envía la salida a dist/tokens/v2/, mientras que el pipeline legacy de tokens personalizados continúa enviando a las rutas existentes. Los componentes adoptan las nuevas variables de token incrementalmente — un componente a la vez, verificado por pruebas de regresión visual. El período paralelo generalmente dura de 2 a 4 semanas para una base de código mediana, después del cual se elimina el pipeline legacy.
La paridad de nombres de tokens es la restricción crítica durante la coexistencia. Si el sistema legacy usa --color-primary y la exportación DTCG produce --color-interactive-default, cada migración de componente requiere un shim de nombres. Diseña los nombres de variables DTCG para que coincidan con la convención de nombres legacy cuando sea posible, o acepta que un find-and-replace único en todo el árbol de componentes es parte del costo de migración.
Errores comunes de migración
| Error | Síntoma | Solución |
|---|---|---|
| Semántica antes que primitivas | No se pueden crear referencias de alias — las variables no existen aún | Construye primero la colección de primitivas; la semántica referencia primitivas mediante alias |
| Una sola colección para todo | Los cambios de modo oscuro modifican los tiempos de animación | Separa las colecciones por comportamiento de modo: colores, espaciado, motion, tipografía |
| Omitir la auditoría de cobertura | Los valores sin tokenizar persisten en componentes anidados durante meses | Ejecuta el escáner de auditoría de Atomize inmediatamente después de la migración; corrige cada resultado |
| Editar manualmente el JSON DTCG después de la exportación | El JSON se desincroniza de Figma — el problema exacto que la migración debía resolver | Trata Figma como la fuente de verdad; el JSON DTCG es salida de build, nunca se edita manualmente |
| Sin pruebas de regresión visual | Componentes rotos descubiertos en producción | Ejecuta pruebas de regresión visual (Chromatic, Percy o capturas de Playwright) antes de mergear la rama de migración de tokens |
Veredicto final - Migración de Tokens
Migrar tokens de diseño personalizados a Figma Variables es la mayor mejora de fiabilidad que un equipo de sistema de diseño puede implementar en 2026. La secuencia auditar → mapear → exportar → verificar toma de 1 a 2 semanas para un inventario de tokens mediano (200–500 tokens) y se amortiza en reuniones de sincronización eliminadas y handoffs sin desviación en el primer mes. La parte difícil no son las herramientas — Figma Variables y DTCG son maduros — sino la disciplina de auditar a fondo, mapear primitivas antes que semántica y ejecutar un escaneo de cobertura para detectar cada valor omitido. Los equipos que se saltan el paso de auditoría dejan valores sin tokenizar; los equipos que lo ejecutan completan una migración total.
