Glosario

Token semántico

Token que expresa intención de uso (acción, peligro, superficie, énfasis) y resuelve a un token primitivo por referencia. Es la capa que traduce valores en decisiones y la que consumen componentes y agentes.

En una analogía · Es ponerle a un color el cargo que ocupa: no dices "azul 500", dices "color-de-acción", y mañana puedes cambiar quién ocupa el cargo.

También conocido como: semantic token · alias token · token de intención

Qué es un token semántico

El token semántico nombra la intención, no el valor: color.action.primary, color.feedback.error, surface.raised, space.inset.comfortable. Su $value es una referencia a un primitivo:

{
  "color": {
    "action": {
      "primary": {
        "$value": "{color.blue.500}",
        "$type": "color",
        "$description": "Acciones principales: botones primarios, links de avance."
      }
    }
  }
}

Es la capa donde vive el criterio del sistema. Un primitivo dice “existe este azul”; el semántico dice “este azul significa acción”.

La capa que consumen los agentes

Cuando un agente genera UI contra un design system, la pregunta que hace no es “¿qué colores hay?” sino “¿qué color uso para un botón destructivo?”. Esa pregunta solo tiene respuesta si la capa semántica existe y está bien nombrada. Por eso:

  • Un sistema con buena capa semántica es consultable: el agente mapea intención a token sin adivinar.
  • Un sistema solo-primitivos obliga al agente a decidir por estética, que es exactamente el tipo de decisión que no se le debe delegar.
  • Las $extensions del formato DTCG permiten enriquecer el semántico con reglas operativas (superficies permitidas, contraste mínimo) que el agente puede validar antes de aplicar.

Nomenclatura: el contrato

La convención más extendida es categoría.concepto.variante (color.action.primary, color.action.primary.hover). Tres reglas prácticas:

  1. El nombre debe sobrevivir a un rebrand. color.brand.principal sobrevive; color.azul-corporativo no.
  2. Cada nombre, una decisión. Si dos semánticos resuelven siempre al mismo primitivo y nadie sabe por qué hay dos, sobra uno.
  3. Los estados son variantes, no tokens nuevos. hover, pressed, disabled cuelgan del concepto, no inauguran categoría.

Ver también

La semana 4 de la cohorte reconstruye la capa semántica de tu sistema real con $extensions legibles por agentes. La versión condensada está en la mini-formación de tokens.

Lecturas de referencia

A seguir

Volver al glosario