Glosario

Token W3C DTCG

Estructura JSON estandarizada por el W3C Design Tokens Community Group para describir un valor de diseño (color, espacio, tipografía) junto con su tipo, sus alias y sus extensiones legibles por agentes.

En una analogía · Es la plantilla de un formulario oficial: todo el mundo rellena las mismas casillas con los mismos nombres, así cualquier oficina lo lee.

También conocido como: DTCG · W3C Design Token · Token DTCG

¿Qué es un token W3C DTCG?

El W3C Design Tokens Community Group (DTCG) publica desde 2021 un draft de especificación que define cómo serializar un design token en JSON. La versión vigente del format module introduce tres campos obligatorios o convencionales: $value, $type y $description. Una propiedad opcional, $extensions, permite añadir metadata propietaria sin romper la compatibilidad.

El formato sustituye al patrón anterior, donde cada herramienta (Style Dictionary, Theo, Specify) definía su propio dialecto. El DTCG normaliza el JSON para que sea consumible por cualquier build pipeline o por un agente sin reentrenamiento.

Estructura mínima

{
  "color": {
    "ink": {
      "graphite": {
        "$value": "#0E0E0E",
        "$type": "color",
        "$description": "Tinta principal. Cuerpo y display sobre fondo claro."
      }
    }
  }
}

Tres reglas duras:

  1. $value es el dato. Puede ser un literal o una referencia a otro token ("{color.ink.graphite}").
  2. $type declara la semántica del valor: color, dimension, fontFamily, duration, etc. Sin tipo, un parser no sabe si #FF0000 es un color o una cadena cualquiera.
  3. $extensions es el contrato propietario. Cualquier metadata adicional vive aquí bajo un namespace. Ejemplo:
"$extensions": {
  "ida.agentic": {
    "wcagContrast": "AAA",
    "allowedSurfaces": ["body", "display"],
    "agentReadable": true
  }
}

Qué cambia para diseñadores y agentes

Para un diseñador: nada visible. El token sigue resolviendo a #0E0E0E cuando llega al CSS.

Para un agente: todo. El campo $type le permite razonar sobre el token; $description le da contexto narrativo; $extensions le da las reglas operativas. Un agente que recibe el JSON anterior puede decidir aplicar el token solo a superficies declaradas, validar contraste antes de renderizar, o rechazar una composición que lo use en un destino prohibido.

Sin esa capa, el agente trata cada hex string como una cadena opaca. Con ella, el token se vuelve consultable.

Diferencia con Style Dictionary 3.x

Hasta la versión 3, Style Dictionary usaba un formato propio donde el valor era directo (color.ink.graphite: "#0E0E0E") y el tipo se inferia de la posición en el árbol. La versión 4 (publicada en 2024) acepta tokens DTCG nativos: style-dictionary lee el JSON con $value/$type/$extensions y emite la salida sin reescribir el árbol.

Si tu sistema sigue en Style Dictionary 3, la migración a 4 implica:

  • Renombrar value → $value, añadir $type por nodo terminal.
  • Eliminar la inferencia por posición (los category, type, item del modelo CTI).
  • Trasladar metadata custom a $extensions.<namespace>.

Ver también

Si estás migrando tu sistema a DTCG, la mini-formación de tokens W3C DTCG cubre el patrón completo en tres horas.

Lecturas de referencia

A seguir

Volver al glosario