Token semántico

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

• Token primitivo
• Token W3C DTCG
• Cómo se implementa un MCP server para tu design system

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.