El formato de tokens DTCG explicado

DTCG es el formato JSON de intercambio para design tokens definido por el Design Tokens Community Group. Cada token es un objeto que lleva un $value y un $type; el anidamiento crea grupos; cadenas como {color.brand.600} referencian otros tokens; y los tipos compuestos agrupan propiedades relacionadas: un token de tipografía lleva familia, tamaño, peso e interlineado como un único valor. Un archivo en este formato se lee igual para cualquier herramienta que lo soporte, que es la razón de ser del formato.

Este artículo recorre la anatomía con ejemplos reales, nombra los tipos que vale la pena conocer y luego va más allá del mínimo de la especificación: lo que contiene de verdad un archivo de tokens generado completo, y la disciplina que mantiene sano un archivo cuando lo editan tanto herramientas como personas. Es el capítulo de formato de nuestra guía de design tokens.

¿Qué aspecto tiene un archivo DTCG?

Un ejemplo recortado pero estructuralmente fiel:

{
  "color": {
    "$description": "Palette generated from one blue seed.",
    "brand": {
      "600": {
        "$value": "#2563eb",
        "$type": "color",
        "$description": "Core brand step — oklch(0.546 0.215 262.9)"
      }
    }
  },
  "semantic": {
    "accent": { "$value": "{color.brand.600}", "$type": "color" }
  },
  "type": {
    "body-md": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Inter",
        "fontSize": "16px",
        "fontWeight": 400,
        "lineHeight": "24px"
      }
    }
  }
}

Cinco mecanismos sostienen la mayor parte del formato:

• $value — lo que almacena el token. La única propiedad obligatoria.
• $type — cómo interpretar el valor: ¿es "16px" una dimensión o una cadena? El tipo responde preguntas que el JSON en crudo no puede.
• Grupos por anidamiento. Los objetos simples agrupan tokens, y la ruta se convierte en el nombre: color.brand.600. Los grupos pueden llevar un $type que sus tokens heredan, y por eso los archivos reales suelen definirlo una vez por sección.
• $description — documentación que viaja con el token, hacia la documentación generada y las exportaciones, en lugar de vivir en una wiki que se desincroniza.
• Referencias. Un $value de "{color.brand.600}" convierte un token en un alias de otro: el mecanismo con el que se construye la capa semántica.

La pieza restante es $extensions: un contenedor con espacio de nombres para datos específicos de cada herramienta, de modo que una herramienta pueda anotar tokens sin colisionar con la especificación ni con otras herramientas.

¿Qué tipos de token importan en la práctica?

Los tipos primitivos con los que te encontrarás de verdad: color, dimension (longitudes como 23px o 1.5rem), fontFamily, fontWeight, number y duration. Encima de estos se sitúan los tipos compuestos, donde el valor de un token es un objeto de subvalores relacionados: typography (el ejemplo de arriba), shadow (color, desplazamientos, desenfoque, expansión), border y transition.

Los compuestos existen porque algunos estilos solo son correctos como un conjunto. Un body-md que llevara un tamaño pero no su interlineado dejaría la mitad del estilo a lo que el contexto herede por casualidad; el compuesto hace del conjunto la unidad de reutilización. En términos de volumen, la mayoría de los archivos están dominados por tokens color y dimension, con un puñado de compuestos cargando con el trabajo tipográfico pesado.

¿Por qué importa un formato estándar?

Por el problema del intercambio. Antes de un formato compartido, cada herramienta de diseño y cada pipeline de build inventaba su propio dialecto de JSON, y mover tokens entre dos cualesquiera de ellos significaba un adaptador; con N herramientas, eso se acerca a N² adaptadores, cada uno un lugar donde los valores pueden traducirse mal. Un estándar colapsa los adaptadores: escribe el archivo una vez y cualquier herramienta conforme puede consumirlo.

Conviene decir su estado con honestidad: la especificación del formato DTCG es un borrador de un grupo comunitario del W3C, todavía no un estándar terminado. Las herramientas han convergido en gran medida hacia ella antes de la estandarización formal —un patrón común en formatos que resuelven un problema acuciante—, pero los detalles aún pueden cambiar, y por eso este artículo está marcado como uno a revisar con el tiempo.

¿Qué contiene un archivo de tokens generado de verdad?

Los ejemplos de la especificación son deliberadamente mínimos: tres tokens y un grupo. Un archivo que describe un design system real es una experiencia de lectura distinta, y el orden de sus secciones te cuenta la arquitectura del sistema. La exportación de Scale Composer es el ejemplo trabajado aquí; de arriba abajo lleva:

• $description — una línea que dice qué es el archivo y de dónde viene.
• meta — datos a nivel de archivo, incluida la unidad en la que se expresa el sistema (px o rem).
• scale — los tres parámetros compartidos (base, ratio, notas por intervalo) de los que derivan tanto la tipografía como el espaciado.
• Anclas del sistema — el pequeño conjunto de valores fijos a los que se ancla el resto del sistema.
• color — las rampas generadas, hex junto a OKLCH.
• spacing — los pasos con nombre.
• typography — el conjunto compuesto de roles, de caption a display.
• semantic y semantic-dark — los mapeos de rol a valor, uno por tema, ambos generados a partir de las mismas semillas.
• layout — breakpoints y anchos de contenedor.
• $metadata — registro interno al final.

Leído en orden, eso es: primero los parámetros, luego la materia prima, luego el significado, luego el significado por tema, luego la estructura a nivel de página. Un lector que conoce el orden de las secciones puede responder «¿dónde viviría X?» sin buscar. Abre un archivo generado en la vista de exportación de Scale Composer: las secciones exactamente en este orden, con los valores en vivo: cambia un parámetro de la escala y observa cómo se regeneran las secciones derivadas.

¿Qué ocurre cuando herramientas y personas editan el mismo archivo?

Esta es la pregunta de formato que la especificación no puede responder por ti, porque tiene que ver con el flujo de trabajo. Un archivo de tokens en uso real tiene dos clases de autor: un generador que es dueño de las secciones que deriva, y personas que añaden lo que el generador desconoce por completo: un grupo de componentes, $extensions específicas del proyecto, una rampa extra importada de otro sitio.

La regla que mantiene esto a salvo: una herramienta debería preservar lo que no le pertenece. Cuando un generador reescribe un archivo, las secciones que no creó deben pasar intactas. La ruta de importación de Scale Composer sostiene esto como una propiedad probada: carga un archivo DTCG existente, ajústalo, vuelve a exportarlo y el viaje de ida y vuelta deja intactas las secciones que no genera; guardar, cargar y volver a guardar produce el mismo archivo. La consecuencia es práctica más que teórica: tus secciones añadidas a mano sobreviven a la regeneración, así que adoptar un generador no significa entregarle el archivo entero. Sin la regla, la primera regeneración borra trabajo en silencio, y el borrado silencioso en un archivo tan central sale caro de notar tarde.

Lee tu propia exportación

Los formatos dejan de intimidar la primera vez que lees un archivo que es tuyo. Carga un archivo DTCG existente en Scale Composer, o exporta uno nuevo — recorre las secciones contrastándolas con la lista de arriba, encuentra dónde se hereda $type de un grupo, sigue una {reference} hasta su destino, luego vuelve a exportar y haz diff: las secciones que no tocaste vuelven sin cambios.