Saltar al contenido

Tokens

Primero los semánticos

Qué capas de tokens existen, cuál debe usar un agente al generar diseños o código y cómo escribir esa regla para que se pueda comprobar.

Última revisión:

Un sistema de tokens suele tener dos o tres capas: valores, intenciones y, a veces, decisiones de componente. Un agente que elige mal la capa produce código que se rompe al cambiar de tema. Esta página propone una regla sencilla y comprobable.

En esta página

Las capas

CapaQué nombraEjemploLo usa el agente
PrimitivoQué valor escolor.blue.600, space.400No
SemánticoPara qué se usacolor.action.primary, space.inset.mdSí
ComponenteUna decisión de un componentebutton.primary.backgroundSolo dentro de ese componente

DesignToken101 explica las capas y cómo se relacionan con alias (DesignToken101: Las capas). En DTCG, un alias se escribe con llaves y siempre apunta al $value del token de destino: "$value": "{color.blue.600}" (Format Module: Curly brace syntax).

La regla para el agente

Recomendación

Escribe la regla en las guidelines y en el archivo de instrucciones del repositorio, con estas palabras o parecidas:

  • Usa solo tokens semánticos o de componente. Nunca primitivos.
  • Nunca escribas un valor literal de color, espaciado, radio o tipografía.
  • Si ningún token semántico encaja, no uses un primitivo: dilo y propone el token que falta.

El tercer punto es el más importante. Sin él, un agente que no encuentra el token adecuado elige el valor más parecido, y el sistema crece con excepciones que nadie decidió.

En Figma, la regla se refuerza ocultando los primitivos al publicar, para que no aparezcan al aplicar variables. Figma permite ocultar una variable al publicar, o una colección entera si su nombre empieza por _ o . (Figma: Hide styles, components, and variables when publishing). DesignToken101 oculta sus primitivos variable por variable (DesignToken101: La colección completa).

Cómo se comprueba

Una regla con "nunca" se puede comprobar con un script, sin leer el código a mano:

  • Buscar valores hexadecimales, rgb( o px fuera de la carpeta de tokens.
  • Buscar referencias a primitivos (--ds-color-blue-) fuera de la carpeta de tokens.

En el capítulo 7 usamos estas búsquedas para puntuar lo que genera un agente.

Los tokens obsoletos

DTCG permite marcar un token como obsoleto con $deprecated: true, false o un texto que explica el motivo (Format Module: Deprecated). El texto es lo que el agente necesita para saber qué usar en su lugar:

tokens/semantic.tokens.json (fragmento)

{
  "color": {
    "$type": "color",
    "brand": {
      "$value": "{color.blue.600}",
      "$deprecated": "Usa color.action.primary. Se elimina en 2.0.0."
    }
  }
}

Nota

No hemos comprobado si Figma exporta o importa $deprecated en las variables. Si tus tokens salen de Figma, puede que tengas que añadirlo en el repositorio.

En resumen

  • El agente usa tokens semánticos o de componente, nunca primitivos ni valores literales.
  • Si no hay token adecuado, el agente lo dice; no elige el valor más parecido.
  • $deprecated con un texto dice qué usar en lugar del token obsoleto.

Fuentes