Las Variables de Figma llegaron en 2023 como la respuesta que tardó demasiado en llegar de la plataforma a los design tokens. La función es poderosa: colecciones nombradas de valores primitivos — colores, números, cadenas, booleanos — que puedes vincular a cualquier propiedad en cualquier componente. Cambia la variable y cada instancia se actualiza. Añade una colección de modo oscuro y cada vinculación de variable se intercambia automáticamente.
Para AI codegen, las Variables no son solo útiles. Son el mecanismo que convierte un archivo Figma de una maqueta pixel-perfect en una especificación que tu agente puede implementar correctamente. Cuando un color tiene un nombre — color/brand/primary, no #7F5CFE — el agente puede mapearlo a un token de código, implementar el modo oscuro correctamente y producir una salida que participa en tu sistema de diseño real.
El problema: la mayoría de los archivos Figma en uso activo hoy en día no tienen Variables configuradas. figmascope maneja ambos casos. Esta publicación explica cómo.
Qué son realmente las Variables
Una Variable de Figma es un escalar nombrado vinculado a una colección. Las colecciones organizan las variables por modo — "Light" y "Dark" son el ejemplo canónico. Cada variable en una colección puede tener valores diferentes por modo: color/surface/background es #FFFFFF en Light y #0D0D0D en Dark. El vínculo se propaga: cada relleno que referencia color/surface/background se actualiza cuando cambias de modo.
Las Variables pueden ser colores, números, cadenas o booleanos. En la práctica, los más impactantes son los colores y números — lo que cubre la mayor parte de la superficie de tokens en un sistema de diseño típico: paleta de colores, escala de espaciado, radios de borde, tamaños de fuente, valores de elevación.
Figma expone las Variables a través de su API REST como una colección localVariables. Cada variable tiene un ID, un nombre, un tipo y valores por modo. Las propiedades de componentes que referencian variables llevan un campo boundVariables con el ID de la variable. Estos son datos estructurados que viajan limpiamente a través del pipeline de extracción.
El camino feliz: las Variables están presentes
Cuando un archivo Figma tiene Variables, figmascope las lee desde la API y construye un tokens.json siguiendo una estructura compatible con el W3C Design Tokens Community Group. Cada token tiene un $value y un $type. Los tokens de color obtienen valores hex con alfa opcional. Los tokens de espaciado obtienen valores numéricos con una pista de unidad px. El nombre del token sigue la colección y la ruta de nombre de la variable:
{
"color": {
"brand": {
"primary": { "$value": "#7F5CFE", "$type": "color" }
},
"surface": {
"background": { "$value": "#FFFFFF", "$type": "color" }
}
},
"spacing": {
"4": { "$value": 4, "$type": "number" },
"8": { "$value": 8, "$type": "number" },
"16": { "$value": 16, "$type": "number" }
}
}Cuando se construye el IR por pantalla, cada relleno que tenía una referencia boundVariables obtiene el nombre del token en lugar del hex resuelto. El nodo lleva:
"fills": [{ "type": "SOLID", "tokenRef": "color/brand/primary" }]No #7F5CFE. El nombre del token. El agente lee esto y genera background-color: var(--color-brand-primary) o Color.brandPrimary o cualquier patrón de consumo de tokens que use el framework objetivo. Esa es la salida que quieres: código conectado a tu sistema de diseño, no código que se romperá en el momento en que un diseñador actualice un color.
El nombramiento semántico es la diferencia entre código que envejece bien y código que se desvía. Un valor hex en el código fuente es una responsabilidad; una referencia de token es un contrato. Las Variables son lo que hace que los archivos Figma sean capaces de expresar contratos, no solo píxeles.
La realidad: la mayoría de los archivos no tienen Variables
Las Variables requieren plan Professional de Figma o superior. Requieren un diseñador que las haya configurado — lo que significa crear colecciones, nombrar variables y vincularlas manualmente a cada propiedad de componente. En un archivo de sistema de diseño maduro y bien mantenido, esto está hecho. En el Figma de producto de una startup, el archivo de cliente de un freelancer o cualquier archivo que preceda a la función de Variables, típicamente no.
figmascope fue diseñado para ser útil también para esos archivos. Se degrada graciosamente: cuando faltan Variables, recurre a la inferencia de tokens basada en frecuencia.
El fallback: inferred-from-frequency
El algoritmo de inferencia funciona así:
- Recorre cada nodo hoja en cada frame exportado.
- Recopila todos los colores de relleno, valores de espaciado y radios de borde.
- Cuenta las ocurrencias de cada valor único.
- Los valores que aparecen por encima de un umbral de frecuencia se promueven a tokens inferidos.
- Cada token obtiene un nombre derivado del valor:
color.7f5cfe,spacing.16,radius.8.
El tokens.json de salida tiene una estructura similar a la ruta de Variables, pero los nombres son derivados del valor en lugar de semánticos:
{
"color": {
"7f5cfe": { "$value": "#7F5CFE", "$type": "color" },
"f6f2ea": { "$value": "#F6F2EA", "$type": "color" }
},
"spacing": {
"16": { "$value": 16, "$type": "number" },
"8": { "$value": 8, "$type": "number" }
}
}En el IR, los nodos que usan estos valores obtienen referencias de tokens: "tokenRef": "color.7f5cfe". No literales codificados directamente. Referencias — solo a tokens inferidos en lugar de nombrados.
El agente sigue generando código referenciado con tokens. var(--color-7f5cfe) no es tan legible como var(--color-brand-primary), pero sigue siendo un token — puedes hacer find-and-replace, puedes renombrarlo, puedes auditar su uso. Es un manejador nombrado sobre un valor, no un número mágico.
El campo tokensSource
Cada bundle de figmascope incluye un _meta.json que documenta qué hay en el bundle y cómo se produjo. El campo tokensSource tiene tres valores posibles:
figma-variables— Las Variables estaban presentes y se usaron. Los nombres de tokens son semánticos.inferred-from-frequency— No se encontraron Variables. Los tokens se infirieron de la frecuencia de valores. Los nombres son derivados del valor.none— No se pudieron extraer o inferir tokens. El IR usa valores resueltos directamente.
Esto importa porque le dice al agente consumidor (y al desarrollador que lee el bundle) exactamente cuánto confiar en los nombres de tokens. Un bundle figma-variables es la fuente de verdad para tu sistema de diseño. Un bundle inferred-from-frequency es un andamiaje estructural útil que necesita revisión de nombrado del diseñador antes de ser canónico. Un bundle none es un punto de partida con valores codificados directamente que necesitan tokenizarse después.
Los metadatos honestos están infravalorados. Las herramientas que infieren silenciosamente sin marcar la inferencia como tal crean falsa confianza. figmascope expone la cadena de inferencia explícitamente para que sepas con qué estás trabajando.
Por qué la inferencia por frecuencia es mejor que nada
La alternativa a la inferencia por frecuencia es producir valores literales resueltos en todas partes — #7F5CFE en cada nodo de relleno que usa ese color. Esto produce código más difícil de refactorizar, más difícil de auditar y más difícil de conectar a un sistema de diseño cuando finalmente se añade uno.
La inferencia por frecuencia, como mínimo, extrae el conjunto de valores que el diseño realmente usa. Si #7F5CFE aparece 47 veces en el diseño, eso es una señal: este es un color primario, no un acento. El nombre del token no lo sabe — es solo color.7f5cfe — pero los datos de frecuencia cuentan la historia. Un agente que recibe los tokens inferidos puede hacer suposiciones razonables sobre qué valores son primarios y cuáles son únicos.
Más prácticamente: la inferencia por frecuencia te da un tokens.json que tiene diff entre versiones. Si exportas el mismo archivo dos veces después de que un diseñador cambió un color recurrente, el diff muestra que el valor del token cambió. Sin inferencia, estarías persiguiendo cada cambio literal individual disperso a través de múltiples archivos IR.
Qué deberían hacer igualmente los diseñadores
La inferencia por frecuencia es una capa de compatibilidad, no un sustituto de las Variables. El camino correcto es que los diseñadores adopten Variables para todos los valores que participan en un sistema de diseño: colores de marca, escala neutral, escala de espaciado, radios de borde, elevación, tipografía. Una vez que estén en su lugar, el bundle de figmascope pasa de tokens de calidad de andamiaje a tokens de calidad de producción.
Las Variables también desbloquean la tematización en el bundle: múltiples valores de modo por token. Un archivo con modos Light/Dark produce un tokens.json con valores por modo que se alimenta directamente en propiedades CSS personalizadas con anulaciones de media query, u objetos de tema específicos de plataforma. Esto es imposible de inferir desde una única instantánea de diseño — requiere intención explícita del diseñador, expresada a través de Variables.
La ruta de actualización es incremental. Un equipo puede comenzar con tokens de calidad de inferencia hoy, adoptar Variables gradualmente a medida que madura el sistema de diseño, y obtener mejores bundles automáticamente a medida que lo hacen. El campo tokensSource rastrea dónde estás en esa progresión.
El pipeline de tokens completo
Para hacerlo concreto, aquí está el orden completo de resolución que figmascope usa para cada relleno en el IR:
- ¿El nodo tiene una referencia
boundVariables.fills? Si sí, resuelve al nombre de la variable y el valor de modo cero. Fuente del token:figma-variables. - ¿El valor resuelto está presente en los tokens de frecuencia inferidos (por encima del umbral)? Si sí, mapea al nombre del token inferido. Fuente del token:
inferred-from-frequency. - De lo contrario: usa el valor hex resuelto directamente. Sin referencia de token. Fuente del token:
none.
Los pasos se intentan en orden. La fuente de mayor calidad gana. El campo tokensSource en _meta.json refleja la ruta dominante para el bundle en su conjunto.
Esto significa que un archivo parcialmente con Variables — donde algunos componentes tienen vínculos y otros no — produce un bundle mixto. Tokens nombrados donde existen, tokens inferidos donde no. Ese es el comportamiento correcto: usa cada fragmento de información estructurada disponible, recurre graciosamente donde falta, y sé honesto sobre qué ruta tomó cada valor.
Exporta tu bundle desde la app de figmascope para ver qué tokensSource produce tu archivo. Luego usa el bundle con Claude Code o Cursor para generación de código precisa y referenciada con tokens.