Saltar al contenido

Tokens

Descripciones en DTCG

Cómo usar $description en DTCG para que la intención de cada token viaje con él, de Figma al código, y cómo escribir una descripción que un agente pueda aplicar.

Última revisión:

El nombre de un token dice para qué sirve en general. La descripción dice cuándo usarlo y cuándo no. Es la documentación más barata que puedes escribir para un agente, porque viaja con el token a cualquier herramienta que lea DTCG.

En esta página

Qué es $description

DTCG define $description como una descripción en texto plano, opcional, que explica el propósito del token. Las herramientas pueden usarla de distintas formas: un editor puede mostrarla como ayuda emergente y una herramienta de transformación, como comentario en el código generado (Format Module: Description).

De Figma a DTCG

La descripción de una variable se escribe en Figma con Edit variable (Figma: Add descriptions). DesignToken101 comprobó que la exportación de Figma a DTCG la escribe como $description del token (DesignToken101: Documentar el sistema):

Exportación de Figma (fragmento)

"primary": {
  "$type": "color",
  "$value": { "colorSpace": "srgb", "components": [0.11, 0.39, 0.85], "hex": "#1C64D9" },
  "$description": "Fondo de la acción principal. Máximo una por vista."
}

Así, la misma frase está en Figma, en el JSON del repositorio y, si la herramienta de transformación la conserva, como comentario en el CSS que lee el agente.

Cómo escribir una descripción

Recomendación

Una descripción de token tiene dos partes: para qué sirve y la restricción principal. Una frase cada una. Sin el valor, que ya está en $value.

TokenDescripción débilDescripción útil para un agente
color.action.primaryAzul principalFondo de la acción principal. Máximo una por vista.
color.text.subtleTexto grisTexto secundario: metadatos y ayudas. No para texto que haya que leer para completar una tarea.
color.feedback.errorRojo de errorMensajes y bordes de error. No para botones destructivos: usa color.action.danger.
space.inset.md16 pxRelleno interior de tarjetas y paneles.

Las descripciones útiles se parecen a las reglas de la documentación: dicen cuándo, cuándo no y qué usar en su lugar.

Qué tokens describir

DesignToken101 hace obligatoria la descripción en los semánticos y opcional en los primitivos (DesignToken101: Documentar el sistema). Para un agente tiene sentido: los semánticos son los que debe usar, así que son los que necesitan instrucciones.

En resumen

  • $description explica el propósito del token y viaja con él entre herramientas.
  • Figma exporta la descripción de la variable como $description.
  • Una descripción útil dice para qué sirve el token y su restricción principal.

Fuentes