Tokens con intención

El mecanismo: la intención viaja en tres sitios

Un token llamado azul-500 solo dice un color. Uno llamado color.accion.primaria dice además para qué sirve. Pero el nombre es solo el primero de los tres sitios donde un token puede llevar su intención, y un agente aprovecha los tres:

{
  "color": {
    "accion": {
      "primaria": {
        "$value": "{color.azul.500}",
        "$type": "color",
        "$description": "Únicamente para la acción principal de la vista. Si hay dos, una de las dos no es primaria.",
        "$extensions": {
          "ida.uso": { "maxPorVista": 1, "prohibidoEn": ["texto-corrido"] }
        }
      }
    }
  }
}

1. El nombre (accion.primaria) permite elegir por significado.
2. La $description lleva el criterio en prosa: es lo que el agente lee cuando duda, y donde cabe la regla que no cabe en un nombre.
3. Las $extensions llevan la intención en datos que una máquina valida: cuántas veces, dónde no. Esto convierte la intención en guardrail comprobable.

La prueba de fuego: pídele a un agente “un botón secundario para esta tarjeta”. Con tokens sin intención elegirá por estética (y a veces acertará); con estos tres niveles, elige por contrato.

Cómo se construye, en tres pasos

1. Audita los nombres: lista tus tokens y marca cuáles nombran valor (gris-100, radius-4) en lugar de propósito. Esos son primitivos: no los borres, pero que nada los consuma directamente.
2. Escribe la $description de los 20 tokens más usados como una instrucción a un desconocido, no como una etiqueta (“Fondo de las superficies elevadas. Nunca para el fondo de página.”).
3. Mueve a $extensions lo que sea regla dura (límites de uso, pares prohibidos) para que la validación lo lea sin interpretar prosa.

La guía Tokens que hablan al agente recorre el proceso completo sobre el formato W3C DTCG; el término token semántico explica la capa de nombres en detalle.