Tokens en Figma

Obtener el archivo

@luz-ds/tokens incluye todos los tokens en formato JSON de W3C Design Tokens (DTCG), en un solo archivo. pnpm tokens:build lo genera a partir de las mismas fuentes que el CSS, por lo que ambos siempre coinciden.

node_modules/@luz-ds/tokens/dist/luz-tokens.dtcg.json

• Desde un empaquetador o un script: import tokens from "@luz-ds/tokens/dtcg" (la exportación ./dtcg).
• Sin instalar nada: https://cdn.jsdelivr.net/npm/@luz-ds/tokens@0.3.0/dist/luz-tokens.dtcg.json. Descárgalo e importa el archivo descargado.

El archivo tiene dos grupos, uno para cada colección de Figma que quieras crear:

Un token semántico apunta a un token primitivo siempre que lo hace el CSS: --luz-divider es var(--luz-gray-20) en el modo claro, así que divider es un alias de {primitives.gray.20}. Un rol tipográfico es un alias de su fuente: font/body es {primitives.font.serif}. Las duraciones son duraciones DTCG y las funciones de aceleración, curvas de Bézier cúbicas. Las capas (z-index) y los anchos de maquetación se incluyen en @luz-ds/core, así que no están en el archivo.

Una regla para cada nombre

Quita --luz-. La primera palabra pasa a ser el grupo y el resto, el nombre; sepáralos con una barra.

Una excepción: --luz-surface también es el nombre de un grupo, así que en el archivo es surface/$root. Figma une los grupos anidados con barras, por lo que una herramienta que conserve el grupo superior escribirá semantic/surface/page: el resto del nombre no cambia.

Modos de Figma y modos de color

Cada modo de la colección semántica corresponde a un valor de data-theme en <html>. Así, un marco configurado como oscuro en Figma muestra lo mismo que la página con data-theme="dark".

Un tema propio, creado como se explica en esa página, no está en el archivo. Para tenerlo en Figma, añádelo como modo extra y copia sus valores de su archivo CSS. Este paso es opcional.

Importarlo

Hay dos formas. Ninguna se ha probado todavía con este archivo.

• Tokens Studio o Terrazzo: leen archivos DTCG, así que carga este tal cual. Los valores de oscuro y alto contraste están en $extensions.mode, una extensión de LUZ que no forma parte del estándar DTCG, así que comprueba que tu herramienta los convierte en modos.
• Figma, sin plugin: el panel Variables importa archivos DTCG, pero crea un modo por archivo, y un alias a otra colección necesita la extensión propia de Figma com.figma.aliasData. Por eso, primero hay que convertir este archivo, como se explica más abajo. Si lo importas tal cual, solo obtendrás los valores del modo claro.

Para convertir el archivo para importarlo con la función propia de Figma, usa un script breve o hazlo a mano:

1. Escribe el grupo primitives en un archivo propio e impórtalo como colección de primitivos de LUZ.
2. Para cada modo (claro, oscuro y alto contraste), escribe un archivo con el grupo semantic, donde el $value de cada token sea su valor en $extensions.mode para ese modo.
3. En esos archivos, asigna a cada alias de un token primitivo ({primitives.gray.90}), la extensión com.figma.aliasData que indica el nombre de la variable en los primitivos de LUZ, o escribe el color en lugar del alias.
4. Importa el archivo del modo claro para crear la colección de semántica de LUZ y, después, importa cada uno de los otros dos archivos con Import mode, con los nombres Oscuro y Alto contraste.

Es posible que los archivos preparados para cada modo se incluyan en el paquete más adelante, cuando se haya comprobado una importación en un archivo real de Figma.

El estándar y dónde se encuentran los modos

Ambos archivos siguen la especificación Design Tokens 2025.10, un informe final del Community Group del 28 de octubre de 2025. Es estable, pero no es un estándar del W3C ni forma parte del proceso de estándares del W3C.

• El módulo de formato describe tokens, grupos, tipos y alias, y no tiene modos: cada archivo de tokens contiene un valor por token. luz-tokens.dtcg.json usa este formato. El $value de un token semántico es su valor para el modo claro, y los otros dos modos están en $extensions.mode, una convención que leen Tokens Studio y Terrazzo. Es una extensión, no forma parte de la especificación.
• El módulo de resolución es donde la especificación sitúa los modos, como un modificador: un conjunto de contextos, cada uno con las fuentes de tokens que se aplican después de la base. luz-tokens.resolver.json (la exportación ./dtcg/resolver) usa este formato: el conjunto base es el archivo de tokens y el modificador mode contiene los contextos light, dark y high-contrast, cada uno con todo el grupo semántico de ese modo. El valor predeterminado es light, como en :root.

node_modules/@luz-ds/tokens/dist/luz-tokens.resolver.json

• Comprobado con los esquemas oficiales. Una prueba valida ambos archivos con los esquemas JSON que publica el Community Group para 2025.10 (copiados en el repositorio, sin necesidad de conexión) y comprueba que cada contexto da a cada token el valor que conserva el archivo de tokens para ese modo.
• No comprobado con una herramienta. Ninguna implementación de resolución ha cargado el archivo de resolución, y no se ha probado con Figma ni Tokens Studio. La validación confirma que el archivo está bien formado, no que una herramienta concreta lo entienda.
• Los dos temas incluidos en core no están en ninguno de los archivos, como se explica más arriba.

Límites conocidos

Según la ayuda de Figma sobre modos e importación (consultada el 9 de octubre de 2026) o informes de otras personas, y sin comprobarlo con este archivo:

• Importa los primitivos antes que los tokens semánticos que apuntan a ellos, si tu herramienta crea dos colecciones. De lo contrario, no se podrán resolver los alias.
• Se pierden las descripciones. La ayuda de Figma no las menciona y hay informes de que no se importan. La función de cada token se indica en la página de color.
• Se omiten los tamaños en rem. Figma solo admite dimensiones en px, y la escala tipográfica está en rem.
• Se omiten las listas de fuentes. Figma solo admite un nombre de fuente, no una lista. Configura las fuentes en los estilos de texto de Figma.
• Los modos requieren un plan de pago de Figma (Professional, Organization, Enterprise o Education), y el número de modos por colección depende del plan.

Mantén Figma y el código sincronizados

• Vuelve a importar cada vez que cambie la versión de @luz-ds/tokens. El archivo se regenera con cada versión.
• No cambies un valor solo en Figma: cambia el token en el código y Figma lo actualizará en la siguiente importación.
• Usa la misma regla para nombrar tus propias variables, para que diseñadores y desarrolladores utilicen los mismos términos.