Arquitectura de variables en Figma: cómo construir un sistema de tokens que sobreviva a producción

La mayoría de los equipos que usan variables de Figma están construyendo sobre un modelo mental de estilos, y ese es el problema. Variables sin arquitectura son simplemente estilos con más clics.

Los equipos que lo hacen bien tratan las variables de Figma como una capa real de design tokens: estructurada, con alias, con alcance (scoping) y exportable. Los que lo hacen mal están a una petición de modo oscuro de una reconstrucción completa. Esta es la arquitectura que sobrevive a producción.

Las variables no son estilos, son la capa de tokens

Los estilos de Figma son presets. Defines un color, un estilo de texto, un efecto, y lo aplicas directamente a una capa. Eso funciona para un archivo de una sola marca, un solo modo y sin requisitos de handoff a desarrollo. Deja de funcionar en cuanto algo cambia.

Las variables de Figma son tokens. Una variable guarda un valor, pero también puede guardar una referencia a otra variable. Esa cadena de referencias, y la capacidad de cambiar conjuntos enteros de valores resueltos mediante modos, es lo que hace que las variables sean arquitectónicamente distintas de los estilos. La diferencia no es cosmética. Es la diferencia entre un sistema de presets y un sistema de tokens.

La arquitectura de tokens de tres capas

Primitivos, semánticos, de componente. Todo sistema de variables que funciona tiene estas tres capas. Saltarse la capa semántica es el error arquitectónico más común en los archivos de Figma hoy.

Las tres capas corresponden a tres trabajos: los primitivos guardan valores en bruto, los tokens semánticos llevan significado y los tokens de componente se limitan a una sola familia de componentes. Cada capa habla solo con la capa inferior. Sin saltos, sin atajos.

Las tres capas no son opcionales según el tamaño del proyecto. Un sistema pequeño con cinco componentes sigue necesitando las tres capas, o la primera petición de tema lo hace saltar por los aires.

Capa uno: primitivos

Los primitivos son los valores en bruto. blue-500, gray-900, space-4, radius-md. Son la paleta, la escala, el cimiento. Nunca se aplican directamente a una capa de componente.

El trabajo de un primitivo es existir, ser referenciado desde arriba y no estorbar. Si un diseñador busca blue-500 para aplicarlo a un botón, la arquitectura ya está rota. Los primitivos pertenecen a la colección de primitivos y a ningún otro sitio.

La convención de nombres importa aquí. Los primitivos deben basarse en escala o paleta, nunca en semántica. blue-500 es correcto. button-blue como primitivo es un error de categoría que causa dolor a escala.

Capa dos: semántica

Los tokens semánticos llevan significado. surface, surface-elevated, text-primary, text-muted, border-default, border-focus. Responden a "¿para qué sirve este color?" en lugar de "¿qué color es este?"

Los tokens semánticos son alias de primitivos. Es la única relación que tienen. El alias de semántico a semántico crea ambigüedad sobre dónde vive el valor y vuelve poco fiables las sobrescrituras de modo.

Esta capa es donde viven tus modos claro, oscuro y de marca. Un token semántico se resuelve a un primitivo distinto según el modo activo, que es como funciona realmente el theming. El primitivo blue-500 no cambia. El token semántico text-link cambia a qué se resuelve según el modo.

Capa tres: componente

Los tokens de componente se limitan a una sola familia de componentes. button-bg, button-text, button-border, card-surface, card-border, input-bg. Son alias de tokens semánticos, nunca de primitivos.

El trabajo de un token de componente es la especificidad sin acoplamiento. button-bg se resuelve a surface-action, que se resuelve a blue-500. Cuando cambia la marca, actualizas la capa semántica y el botón se actualiza con ella. El token de componente queda intacto.

Una objeción habitual es que esto parece tokens extra sin motivo. El motivo es que button-bg y surface-action pueden divergir. En algún momento, una decisión de producto exige que el botón use una superficie ligeramente distinta. Los tokens de componente te dan el punto de sobrescritura sin tocar el sistema semántico.

Modos frente a colecciones: el árbol de decisión

Los modos cambian valores dentro de una colección. Las colecciones separan responsabilidades. Son dos cosas distintas, y confundirlas es el origen de la mayor parte de la confusión arquitectónica en las configuraciones de variables de Figma.

La regla es: una colección por responsabilidad, modos para las variantes de la misma responsabilidad. El color es una responsabilidad. El espaciado es una responsabilidad. Claro y oscuro no son responsabilidades separadas. Son modos de la misma responsabilidad de color.

Cuándo usar un modo y cuándo una colección nueva:

• ¿Otro valor de la misma cosa? Modo.
• ¿Una cosa totalmente distinta? Colección.
• ¿Cambiar entre claro y oscuro? Modo dentro de la colección de color.
• ¿Cambiar entre espaciado compacto y cómodo? Modo dentro de la colección de espaciado.
• ¿Añadir una marca? Modo dentro de la capa semántica, no una colección nueva.

Las cuatro reglas de scoping

El scoping de variables controla dónde se puede aplicar una variable en Figma. Hacerlo mal significa que los diseñadores pueden coger primitivos por accidente en lugar de tokens semánticos, y la disciplina arquitectónica se derrumba en el punto de uso.

Las cuatro reglas no son negociables:

1. Limita el scope de los primitivos a ninguno. Los primitivos no deben poder aplicarse en ningún sitio. Son valores internos, no tokens de cara al consumidor. Ocúltalos del desplegable de aplicar por completo.
2. Limita los tokens semánticos a su tipo. Un token semántico de color se limita a rellenos y trazos. Un token de espaciado se limita a campos de gap, padding y tamaño. Mantén el scope ajustado.
3. Limita los tokens de componente a su familia. Un token de botón no debería poder aplicarse a una tarjeta. Si el scope es demasiado amplio, el límite del componente no significa nada.
4. Nunca expongas primitivos a los consumidores. Si un diseñador o desarrollador aplica un primitivo a una capa, el sistema ha fallado en la capa de scoping. Es un fallo de proceso, no un fallo del usuario.

La cadena de alias que hace posibles los temas

Un tema que funciona es una cadena de alias: el componente referencia al semántico, el semántico referencia al primitivo, el primitivo guarda el valor. La longitud de la cadena es tres, siempre tres.

Una cadena de dos (componente a primitivo) se salta la capa de traducción y hace imposibles los modos sin sobrescrituras manuales en cada token de componente. Una cadena de cuatro crea ambigüedad sobre qué capa semántica lleva el modo, y auditarla se convierte en un ejercicio de depuración en lugar de una simple consulta.

button-bg → surface-action → blue-500 → #0066FF

Copy

Esa cadena sobrevive al modo oscuro actualizando surface-action para que apunte a blue-300 en el modo oscuro de la colección semántica. El token button-bg se actualiza automáticamente. El primitivo blue-500 sigue resolviéndose a #0066FF. Nada más necesita cambiar.

Modos claro, oscuro y de marca

Los tres modos que necesitan la mayoría de los sistemas de variables son claro, oscuro y de marca. Solo la capa semántica los lleva. Nunca la capa primitiva.

Aplicar modos a los primitivos es un error de categoría. blue-500 es siempre #0066FF. Es un primitivo. No tiene variante clara u oscura porque no lleva significado. El token semántico text-link tiene variante clara y oscura porque lleva un significado que se resuelve de forma distinta en contextos distintos.

Los modos de marca funcionan igual. Una segunda marca no necesita una segunda paleta primitiva a menos que use valores en bruto realmente distintos. La mayoría de las veces, un modo de marca en la capa semántica que apunte a otro subconjunto de primitivos existentes es la decisión correcta. Dos colecciones primitivas completas para dos marcas suele ser excesivo. Para ver cómo las decisiones de color previas moldean esto, vale la pena leer el artículo sobre sistemas de color para modo oscuro antes de fijar la estructura de tu capa semántica.

Variables numéricas, de cadena y booleanas

Las variables de Figma no son solo colores. Las variables numéricas controlan espaciado, tamaños y radios. Las variables de cadena controlan el texto dentro de los archivos de diseño. Las variables booleanas controlan la visibilidad de capas, lo que se corresponde directamente con las props de los componentes.

Esta es la parte del sistema de variables que la mayoría de los equipos no usa, y es la que cierra la brecha entre diseño y código de forma más espectacular. Una escala de espaciado definida como variables numéricas y aplicada a los gaps de auto-layout significa que un cambio de espaciado en la variable actualiza cada componente que use ese token. Eso es lo que hace un sistema de tokens de verdad.

Las variables de cadena con modos de idioma permiten a los diseñadores cambiar un archivo entre inglés y árabe y ver cómo se rompe el layout en tiempo real. Las variables booleanas que se mapean a props de componente implican que el componente de Figma y el componente de código tienen una relación de props uno a uno, lo que hace que el handoff a desarrollo sea revisable en lugar de interpretable.

Handoff al código: el patrón que funciona

Un sistema de variables es tan bueno como su exportación. El patrón de handoff que funciona es Tokens Studio o la API REST de variables de Figma, más un pipeline de transformación, más un script de importación del lado del código.

Tokens Studio exporta las colecciones de variables a un formato JSON estructurado compatible con Style Dictionary. Style Dictionary transforma ese JSON en la salida que necesite el código: propiedades personalizadas de CSS, color sets de Swift, archivos de recursos de Kotlin, configuración de Tailwind. El paso de transformación es donde se normalizan las convenciones de nombres y se limpia cualquier nomenclatura específica de Figma que no encaje con las convenciones del código.

El pipeline debe ejecutarse en cada actualización de variables, no a mano. Una GitHub Action que se dispare con un push de Tokens Studio o un webhook de Figma que salte con los cambios de variables mantiene sincronizados los tokens del lado del código sin que nadie tenga que acordarse de exportar. Es el patrón que ejecutan Stripe y Atlassian a escala, y es alcanzable en cualquier código que tenga un paso de build. Para las decisiones de formato de los tokens de color en esa salida, vale la pena leer sobre color OKLCH antes de fijar los valores de tus propiedades personalizadas de CSS.

---

¿Quieres un sistema de variables en Figma que sobreviva a modos, marcas y handoff a desarrollo sin reescrituras? Brainy diseña arquitecturas de tokens listas para producción en Figma con el modelo de tres capas, la cadena de alias y el pipeline de exportación que encaja limpiamente en tu código. Contrata a Brainy

---

Siete errores comunes que rompen los sistemas de variables

La mayoría de estos errores comparten una causa raíz: tratar el panel de variables como un panel de estilos mejorado en lugar de como una capa arquitectónica. El cambio de modelo mental es la solución. Todo lo demás se deriva de ahí.

La auditoría del sistema de variables

Haz esta auditoría a cualquier sistema de variables de Figma y detectarás la deuda arquitectónica antes de que llegue a producción.

Estructura

• Tres colecciones como mínimo: primitivos, semántica, componente (o nombres equivalentes)
• Cada colección tiene una única responsabilidad clara
• Ninguna colección mezcla tipos (color y espaciado en la misma colección es un fallo)

Cadena de alias

• Cada token de componente es alias de un token semántico, no de un primitivo
• Cada token semántico es alias de un primitivo, no de otro token semántico
• Ningún token guarda un valor en bruto salvo los primitivos
• La longitud de la cadena de alias es exactamente tres para todos los tokens de color

Modos

• Claro y oscuro son modos en la colección semántica, no colecciones separadas
• Las variantes de marca son modos en la colección semántica, no archivos separados
• La colección de primitivos no tiene modos

Scoping

• Las variables primitivas tienen scope ninguno (no se pueden aplicar en ningún sitio)
• Las variables semánticas tienen scope según su tipo (color a rellenos/trazos, espaciado a campos de layout)
• Las variables de componente tienen scope de su familia de componentes

Handoff

• Las variables son exportables mediante Tokens Studio o la API REST
• Existe un pipeline de transformación y está automatizado
• Los tokens del lado del código coinciden con la convención de nombres de las variables de Figma, con excepciones documentadas

Si fallan más de tres de estos puntos, el sistema necesita una reconstrucción, no un parche. Una paleta de colores de marca cubre las decisiones de color previas que alimentan la capa primitiva, si ahí es donde la auditoría revela más deuda.

FAQ

¿Cuál es la diferencia entre las variables de Figma y los estilos de Figma?

Los estilos son presets que se aplican directamente a las capas. Las variables son tokens que pueden referenciarse entre sí y cambiar valores mediante modos. Las variables pueden hacer todo lo que hacen los estilos, además de theming y handoff a desarrollo mediante exportación. Para un sistema de diseño nuevo, las variables son la elección correcta. Para un archivo existente con un sistema de estilos maduro, vale la pena escribir un plan de migración antes de cambiar.

¿Cuántas colecciones debería tener un sistema de variables de Figma?

De tres a cinco para la mayoría de los sistemas: primitivos, semántica, componente y, opcionalmente, colecciones separadas de espaciado y tipografía si esas escalas son lo bastante complejas como para merecer sus propias reglas de scoping. Más de cinco colecciones suele ser señal de que las responsabilidades no se están agrupando bien.

¿Pueden las variables de Figma reemplazar a Tokens Studio?

Para crear y editar dentro de Figma, sí. El panel nativo de variables cubre la mayor parte de lo que hacía Tokens Studio antes de que llegara la API de variables. Para exportar y transformar, Tokens Studio sigue aportando valor porque tiene un pipeline maduro hacia Style Dictionary y gestiona casos límite que la exportación nativa no cubre. Las dos herramientas son complementarias ahora mismo, no competidoras.

¿Qué pasa si hago alias de un token semántico a otro token semántico?

La resolución de modos se vuelve ambigua. Si text-secondary es alias de text-primary y cambias a modo oscuro, Figma resuelve la cadena y puede que no aplique la sobrescritura del modo oscuro donde esperas. El alias de semántico a semántico también hace casi imposible auditar el sistema a escala. La regla es estricta: los tokens semánticos solo son alias de primitivos.

¿Cómo gestiono una tercera marca sin reconstruir el sistema?

Añade un tercer modo a la colección semántica. La colección de primitivos se comparte entre marcas a menos que las marcas usen valores en bruto realmente distintos. Un modo de marca en la capa semántica que apunte a un subconjunto distinto de primitivos es la arquitectura correcta. Si las marcas son tan diferentes que sus paletas primitivas no se solapan, dos colecciones de primitivos con una estructura semántica compartida es el plan B.

¿Es necesario el modelo de tres capas en proyectos pequeños?

Sí, pero el tamaño de cada capa se reduce. Un proyecto pequeño puede tener quince primitivos, ocho tokens semánticos y dos tokens de componente por componente. La arquitectura sigue siendo de tres capas. La tentación de saltarse la semántica en proyectos pequeños es la razón por la que tantos proyectos pequeños se convierten en deuda arquitectónica en cuanto aparece un segundo diseñador o una petición de modo oscuro. Para ver cómo encaja la arquitectura de tokens en la decisión del stack completo, el artículo Framer vs Webflow vs Next.js aporta contexto.

El cambio que las variables de Figma realmente desbloquean

Un sistema de variables real en Figma es lo más cerca que han estado diseño y desarrollo de una única fuente de verdad. No un documento de handoff. No un enlace de Zeplin. Una capa de tokens viva, exportable y estructurada que ambos lados leen de las mismas definiciones.

Los equipos que tratan las variables como arquitectura están recortando a la mitad la deuda de su sistema de diseño, no porque las variables sean magia, sino porque la disciplina arquitectónica que exige un buen sistema de variables también obliga a tomar las decisiones que los sistemas de diseño llevaban tiempo aplazando. ¿Qué significa este token? ¿A qué puede hacer alias? ¿Quién es el dueño del primitivo? Esas preguntas tienen respuesta ahora, y las respuestas viven en el archivo.

Variables sin arquitectura son simplemente estilos con más clics. Variables con el modelo de tres capas, la cadena de alias, las reglas de scoping y el pipeline de exportación son un sistema de diseño que puede sobrevivir a una segunda marca, a un modo oscuro y a un desarrollador que nunca ha abierto Figma.

Construye la arquitectura, no solo los tokens.