Design tokens que entiende un agente: formato DTCG y capas semánticas
Un design token legible por agentes usa el formato DTCG: $value, $type y referencias entre capas. Cómo escribirlos y por qué evitan que la IA invente colores.
{color.accion.primaria}, sabe qué usar sin adivinar un hex.¿Qué es un token y por qué se vuelve importante con agentes?
Un token es la unidad más pequeña de un sistema de diseño: un color, un tamaño, una sombra o una duración de animación, con nombre. Los equipos de diseño los usan desde hace años para mantener consistencia. Con agentes, el token cumple una función nueva: es la forma en la que la IA sabe qué color usar sin que tú se lo repitas en cada prompt.
Si el agente no tiene tokens, rellena el hueco con valores que parecen razonables. Eso produce colores y espaciados que nadie aprobó, y complica la paridad de tokens entre diseño y código. El problema no es que la IA sea “mala con colores”, sino que le diste una descripción sin fuente de verdad.
¿Qué formato usar?
El Design Tokens Community Group publicó en octubre de 2025 la versión estable 2025.10 de su especificación. Es un grupo de la W3C, pero el documento no es un Estándar W3C. Las reglas básicas del formato son:
- Cada token es un objeto con
$value(obligatorio). $typeindica el tipo (color,dimension,fontFamily,duration,number…). Es opcional en cada token, porque el tipo puede venir de otra parte: si el token es un alias, hereda el tipo del token al que apunta, y si no, del grupo padre más cercano que lo declare.- Las herramientas no deben adivinar el tipo mirando el valor: si el tipo no se puede determinar por ninguna de esas vías, el token es inválido.
- Un alias usa llaves:
{color.azul.500}. - Un grupo no tiene
$value; solo organiza.
Un archivo mínimo se ve así:
{
"color": {
"azul": {
"500": { "$type": "color", "$value": "#1F4FD8" }
},
"accion": {
"primaria": { "$type": "color", "$value": "{color.azul.500}" }
}
}
}
No necesitas memorizar la especificación. Lo importante es que el archivo sea JSON válido y que el tipo de cada token quede explícito, en el propio token o en su grupo, para que cualquier herramienta, y cualquier agente, lo lea igual.
La especificación define tipos simples (color, dimensión, familia tipográfica, peso, duración, curva Bézier, número) y tipos compuestos (sombra, borde, transición, degradado, tipografía). También admite espacios de color modernos como Display P3 y Oklch.
Antes de depender de una herramienta, comprueba qué versión del formato soporta. Style Dictionary, por ejemplo, tiene soporte de primera clase para el formato DTCG desde su versión 4, pero su documentación indica que la versión 2025.10 aún no está soportada del todo y que eso está previsto para la versión 5. Figma, Adobe, Sketch, Penpot, Tokens Studio y Zeplin figuran entre los adoptantes del formato según las preguntas frecuentes del grupo.
¿Cómo se organizan las capas?
La forma más útil para agentes es separar dos capas:
| Capa | Qué guarda | Ejemplo | Quién la cambia |
|---|---|---|---|
| Primitiva | Valores crudos | azul.500 = #1F4FD8 | Diseño de marca, pocas veces |
| Semántica | Roles de uso | accion.primaria = {azul.500} | Diseño de producto |
El agente debe usar siempre la capa semántica en el código de componentes. Si necesita cambiar el tema oscuro, cambia qué primitivo apunta cada rol, no cada componente. Para más contexto sobre cómo se organizan las capas en general, lee arquitectura de tokens.
¿Cómo lo lee un agente?
El agente lee el archivo al inicio de la tarea, si tú se lo indicas. Dos cosas ayudan:
- Un archivo de instrucciones en el repo que diga dónde están los tokens y que los use. Lo que escribes en CLAUDE.md o AGENTS.md entra en el contexto cada vez.
- Un paso de build, como Style Dictionary, que convierta los tokens a variables CSS, por ejemplo
--color-accion-primaria. El agente escribe CSS con esas variables y el resultado queda en un solo lugar.
Esto es ingeniería de contexto aplicada a diseño: no le pides al agente que recuerde los colores, le das el archivo donde están.
¿Cuándo NO conviene un archivo de tokens?
- Cuando el producto es un prototipo de un día. Mantener tokens tiene costo; si vas a tirar el código, usa valores directos y no pierdas tiempo.
- Cuando el equipo no está de acuerdo con los nombres. Un archivo con nombres que nadie usa es peor que ninguno, porque el agente lo usará igual.
- Cuando cambias los valores directamente en el código y no en el archivo. Entonces hay dos fuentes de verdad y el agente elegirá la que vea primero.
Ejemplo
Ejemplo ilustrativo: un equipo tiene el botón primario con #1F4FD8 escrito en 14 archivos. Crea tokens.json con la capa primitiva y la semántica, y genera tokens.css con Style Dictionary. Luego cambia accion.primaria para apuntar a otro azul y corre el build. Los 14 archivos cambian sin tocarlos. Después le pide al agente que cree un botón secundario; el agente usa --color-accion-secundaria porque lo encontró en el CSS generado.
El cambio real no es el color. Es que el agente ya no tiene que decidir cuál azul usar.
Errores comunes
- Poner valores directos en los componentes y tokens solo “de referencia”.
- Nombrar tokens por su color (
azul-claro) en vez de por su rol (fondo-suave). Cuando cambie la marca, el nombre miente. - Dejar un token sin tipo ni grupo que lo declare y esperar que la herramienta lo adivine. Según la especificación, ese token es inválido.
- Usar alias circulares (A apunta a B y B a A). La especificación obliga a las herramientas a reportarlos como error.
- Dejar que el agente cree tokens nuevos sin revisarlos. Pide que proponga el cambio en el archivo y tú lo apruebas.