Las Variables de Figma se exportan como JSON DTCG, y ese JSON es el punto de entrega entre el archivo de diseño y el código. DTCG es el formato publicado por el W3C Design Tokens Community Group: un árbol de tokens con $value, $type y referencias escritas como {grupo.token}. El botón de exportar tarda segundos. Mantener intactos los alias, los modos y los tipos durante el resto del proceso es la parte que necesita un método.
En Atomize tratamos la exportación como una etapa de un flujo más largo: escaneamos el archivo de Figma, construimos Primitivos → Atoms, auditamos la cobertura y exportamos el mismo JSON DTCG para que el archivo y el repositorio describan el mismo conjunto de tokens. Las mismas preocupaciones aplican si exportas desde el panel de Variables o desde un plugin. Esta guía cubre qué contiene realmente el archivo, qué sobrevive al viaje, qué se rompe en silencio y cómo convertir el JSON en CSS, TypeScript o un preset de Tailwind sin editar valores a mano.
Para la arquitectura de tokens detrás del archivo, empieza por nuestra guía de tokens de diseño en Figma. Este artículo asume que la jerarquía ya existe y se enfoca en sacarla de Figma sin perder la cadena.
En resumen
- Figma exporta una colección de variables como JSON alineado con DTCG, con un archivo por modo cuando exportas la colección completa.
- Los alias sobreviven como referencias, no como valores copiados: esa es la razón por la que vale la pena automatizar la exportación.
- Los modos se convierten en archivos separados, así que claro y oscuro son dos documentos que comparten los nombres de los tokens.
- Los datos propios de Figma - IDs de variable, alcances, sintaxis de código - viajan dentro de
$extensions.com.figma. - Las variables booleanas y de texto no tienen un tipo DTCG propio y dependen de esas extensiones.
- Una exportación es una foto. Solo un pipeline la convierte en un contrato que se mantiene actualizado.
Qué contiene la exportación
Una colección de variables de Figma se exporta como un árbol anidado, no como una lista plana de nombres y valores. El anidamiento refleja la estructura de grupos dentro de la colección, y cada hoja lleva un $value y un $type. La descripción general de Variables de Figma documenta las mismas colecciones y modos que ves en el panel; la exportación los expone en dos niveles: un modo concreto, o todos los modos de la colección en un ZIP con un archivo JSON por modo.
Así se ve un token semántico de color después de exportar. El valor es una referencia a otro token, y la identidad propia de Figma vive en el bloque de extensiones:
{
"color": {
"background": {
"default": {
"$value": "{color.gray.50}",
"$type": "color",
"$description": "Fondo predeterminado de página",
"$extensions": {
"com.figma": {
"variableId": "VariableID:2259:43",
"codeSyntax": {
"WEB": "var(--color-background-default)"
}
}
}
}
}
}
}La referencia de $value es la cadena de alias saliendo de Figma en una forma que otra herramienta puede resolver. Esa es la diferencia entre una exportación y una captura de valores: background/default sigue apuntando a gray/50, así que un cambio en el primitivo llega a todos los consumidores del código.
Los modos se manejan fuera de ese árbol. Exporta una colección con modos Claro y Oscuro y obtendrás dos documentos cuyas rutas de token coinciden pero cuyos valores difieren. El nombre del archivo lleva el modo, algo que importa cuando el script de build tiene que decidir cuál se convierte en el tema predeterminado.
Qué sobrevive a la exportación y qué se rompe
La mayoría de los fallos de exportación no son errores de sintaxis. Son propiedades que nunca llegaron al archivo y se descubren semanas después, cuando un cambio de tema o un rebranding deja de funcionar. La tabla siguiente es la lista corta que conviene revisar antes de confirmar el JSON.
Qué conserva una exportación de variables de Figma
| Propiedad | Cómo sale de Figma | Qué revisar |
|---|---|---|
| Cadena de alias | Como referencia {ruta.del.token} | Que la ruta referenciada exista en la misma exportación |
| Modos | Un archivo JSON por modo | Que todos los modos contengan las mismas rutas |
| Alcances | Dentro de $extensions.com.figma | Que el build no descarte el bloque de extensiones |
| Descripciones | Como $description | Que el texto no sea el único registro de la intención |
| Tipos booleanos y de texto | Mediante extensiones de Figma | Que la herramienta de destino entienda el tipo personalizado |
| Estilos compuestos | No como variables | Que sombras, degradados y estilos de texto tengan su propia fuente |
La última fila sorprende a los equipos que esperan que un sistema de tokens completo salga de Figma en un solo archivo. Las variables contienen valores únicos. Una pila de sombras, un degradado o un estilo de texto completo es un compuesto, así que vive en un Estilo y necesita su propia ruta de exportación o un compuesto DTCG construido a mano. Si tu código espera un único tokens.json con todo, esa expectativa es lo primero que hay que corregir.
Los alcances merecen una segunda mirada porque son la propiedad más fácil de perder en silencio. Un alcance indica dónde puede aparecer una variable: un token de radio no debería aparecer en el selector de relleno. El JSON exportado conserva esa información bajo el espacio de nombres de Figma. Style Dictionary ignora las extensiones desconocidas por defecto, lo cual está bien para renderizar, pero significa que el alcance no se convierte automáticamente en una regla de lint en el código. Si la paridad de alcances importa, lee la extensión de forma explícita.
Los alias tienen un modo de fallo más sutil: se resuelven por ruta dentro del archivo exportado, pero Figma los resuelve por ID de variable. Exporta una colección que referencia una variable de otra colección y la referencia puede apuntar a una ruta que no está en el mismo documento. Verifica cada referencia {...} contra el conjunto de archivos, no solo contra el archivo que abriste.
Exportar variables paso a paso
El orden siguiente mantiene la exportación reproducible. Casi todo el trabajo ocurre antes de pulsar exportar, porque una colección limpia produce un archivo limpio.
- Normaliza la colección primero. Ejecuta una auditoría de cobertura para encontrar valores sin vincular y después una pasada de limpieza para variables huérfanas. Exportar una colección desordenada solo traslada el desorden al repositorio.
- Decide la estrategia de modos. Si Claro es el predeterminado, exporta todos los modos juntos y deja que el build elija el archivo por defecto. Exportar un solo modo a mano invita a un desajuste la próxima vez que alguien olvide el otro.
- Exporta desde el panel de Variables. Elige la colección y exporta un modo o todos. Renombra el contenido del ZIP para que coincida con los nombres de modo que espera tu build; no dejes los nombres generados por Figma como contrato.
- Inspecciona el JSON antes de confirmarlo. Comprueba que los alias resuelvan, que todos los modos tengan las mismas rutas y que el bloque de extensiones sobreviviera al formateador.
- Confirma la exportación con una versión o una entrada en el changelog. Un archivo de tokens sin registro de cuándo cambió es imposible de depurar contra una interfaz desplegada.
- Alimenta el build, no a cada desarrollador. El JSON debe entrar al repositorio por el mismo pipeline que produce CSS y TypeScript, para que nadie copie valores entre máquinas.
El paso tres es donde se detienen la mayoría de los flujos manuales. La exportación cae en una carpeta de descargas, alguien la renombra y la siguiente exportación la sobrescribe con una estructura ligeramente distinta. Automatizar los últimos tres pasos es lo que convierte el archivo en una fuente de verdad y no en una entrega única.
Convertir el JSON en código con Style Dictionary
Style Dictionary lee el árbol DTCG y genera archivos por plataforma, y su documentación de configuración cubre los grupos de transformación que se usan abajo. Una configuración mínima apunta al JSON exportado y define tres salidas: propiedades personalizadas de CSS para la web, un objeto TypeScript para consumidores tipados y un tema de Tailwind para clases utilitarias.
{
"source": ["tokens/*.json"],
"platforms": {
"css": {
"transformGroup": "css/advanced",
"buildPath": "dist/css/",
"files": [{ "destination": "tokens.css", "format": "css/variables" }]
},
"tailwind": {
"transformGroup": "js",
"buildPath": "dist/tailwind/",
"files": [{ "destination": "theme.js", "format": "javascript/es6" }]
},
"ts": {
"transformGroup": "js",
"buildPath": "dist/ts/",
"files": [{ "destination": "tokens.ts", "format": "typescript/es6-declarations" }]
}
}
}La salida CSS es la prueba visible de que la cadena sobrevivió. Los nombres semánticos permanecen, y sus valores apuntan a propiedades personalizadas primitivas en lugar de repetir códigos hex:
:root {
--color-gray-50: #f9fafb;
--color-gray-950: #030712;
--color-background-default: var(--color-gray-50);
--color-text-primary: var(--color-gray-950);
}
[data-theme="dark"] {
--color-background-default: var(--color-gray-950);
--color-text-primary: var(--color-gray-50);
}Si el CSS generado contiene un código hex donde debería haber un var(), el alias se aplanó en algún punto entre Figma y el build. Esa sola comprobación detecta más regresiones de exportación que cualquier validador de esquema, porque prueba la propiedad de la que depende el sistema de diseño.
El mismo archivo alimenta la conversación de diseño a código. Nuestra guía sobre paridad del sistema de diseño y sincronización de código cubre dónde termina la sincronización a nivel de tokens y dónde empieza la paridad de componentes. La exportación resuelve la primera mitad, no la segunda.
Preguntas reales sobre exportar variables
¿Figma exporta código?
Figma exporta valores de tokens, no código de aplicación. El JSON le da a una herramienta de build los nombres, tipos y referencias que necesita para generar variables CSS, constantes TypeScript o un preset de Tailwind. El marcado de los componentes sigue viniendo de fragmentos de Dev Mode, mapeos de Code Connect o una herramienta separada de diseño a código. Tratar la exportación de tokens como generación de código lleva a la decepción; tratarla como la capa de datos de esa generación es exacto.
¿Cómo exporto solo un modo?
Exporta a nivel de modo en lugar de a nivel de colección. Una exportación de un solo modo produce un documento JSON con los valores de ese modo. Una exportación de colección produce un ZIP con un archivo por modo. Para un sistema de temas, la exportación de colección suele ser el mejor valor por defecto porque mantiene ambos temas en el mismo commit.
¿Por qué se rompen los alias al importar el JSON en otro archivo?
Los alias se resuelven contra la identidad de la variable, y esa identidad la lleva la metadata de extensión de Figma. Cuando una referencia apunta a una variable que no existe en el archivo destino, o a una colección con otro nombre, el importador no tiene a qué vincularse. Importar en la misma librería que produjo la exportación funciona. Importar en un archivo no relacionado necesita una estructura de colecciones compatible, o los valores llegan como literales.
¿Puedo importar el JSON de vuelta en Figma?
Sí. Figma importa el mismo JSON alineado con DTCG en el panel de Variables. Importar en una colección vacía crea variables, mientras que importar en un modo existente actualiza valores. Ese viaje de ida y vuelta sirve para sembrar un archivo desde el repositorio o restaurar una colección tras una migración, pero no sustituye una sincronización real: sobrescribe valores y no fusiona decisiones de nombres tomadas después en Figma.
¿Debería editar a mano el JSON exportado?
Solo para una migración puntual. Las ediciones manuales crean una segunda fuente de verdad, y la siguiente exportación las elimina sin avisar. Si un token necesita otro nombre en código, corrige el nombre en Figma o añade una transformación en el build. Si falta un tipo compuesto en la exportación, modela el compuesto en el build en lugar de parchear el archivo generado.
Cuándo no exportar
No todo archivo de Figma necesita una exportación de tokens. Un prototipo sin consumidor de código, un layout de campaña de una sola vez o un archivo cuyos nombres aún cambian cada semana producirán un JSON que nadie usa. La exportación se gana su lugar cuando se cumplen tres condiciones: los nombres de token son estables, al menos un código consume los valores y más de una persona edita la librería de Figma.
También hay una etapa intermedia que vale nombrar. Un equipo puede exportar para revisión antes de conectar un pipeline: confirmar el JSON, compararlo entre versiones y dejar que diseño e ingeniería acuerden la forma. Ese es un uso legítimo. Lo que no funciona es exportar una vez, no conectar nada y asumir que el archivo ya está vinculado al código.
La misma regla aplica a las exportaciones parciales. Exportar solo la colección semántica mantiene el archivo pequeño, pero los valores primitivos a los que hace referencia tienen que venir de algún lado. Exporta ambas colecciones o acepta que el archivo semántico lleva valores resueltos en lugar de referencias.
Veredicto final - Exportación de Variables de Figma
Exporta las Variables de Figma como JSON DTCG, confirma el resultado y deja que una herramienta de build genere los archivos de plataforma. La exportación es confiable solo cuando los alias siguen resolviendo y todos los modos llegan en la misma versión. Revisa una cosa antes de publicar el pipeline: abre el CSS generado y confirma que los tokens semánticos contienen referencias var() en lugar de códigos hex. Si es así, la cadena sobrevivió a Figma.
