Documentar el sistema

Un sistema de tokens sin documentar obliga a adivinar. Quien lo usa no sabe qué token elegir, y quien lo mantiene no sabe por qué un valor es el que es. En los módulos anteriores has tomado muchas decisiones; en esta lección verás dónde se guarda cada una para que no se pierdan.

En esta página

• Dos cosas distintas que documentar
• La descripción de un token
• Qué tokens llevan descripción
• El registro de decisiones
• Dónde vive la documentación
• En Figma
• Lo que te llevas

Dos cosas distintas que documentar

Un sistema de tokens responde a dos preguntas, y cada una tiene su sitio:

La descripción viaja con el token: se ve en Figma y llega al código con la exportación. El registro guarda lo que no cabe en un token: las alternativas que descartaste y el motivo.

La descripción de un token

Lo que dice la fuente:

• DTCG define $description, una descripción en texto plano del propósito del token. Lo tienen también los grupos. Las herramientas pueden mostrarla junto a una muestra del token, como ayuda en un editor o como comentario en el código generado (Format Module: Description).
• Figma tiene un campo de descripción en la ventana de edición de cada variable, para explicar cómo se usa (Figma: Create and manage variables and collections).

Lo que comprobamos: la exportación de Figma escribe esa descripción como $description del token, al lado de su valor (exportación de Semantic color de DesignToken101, 6 de octubre de 2026):

"focus": {
  "$type": "color",
  "$value": { "colorSpace": "srgb", "hex": "#0EA075" },
  "$description": "Anillo de foco (2 px, border-width/200)"
}

Una descripción escrita una vez en Figma viaja con el token, así que cualquier herramienta que lea el archivo puede usarla: DTCG prevé, por ejemplo, que se convierta en un comentario del código generado.

Qué lleva

Una buena descripción dice para qué sirve el token, y dónde se usa si eso ayuda a elegir. No repite el valor, que ya está en el token, ni cuenta la historia de cómo llegó ahí.

Los dos últimos tipos son los más importantes. Un token sin uso o un valor directo parecen un error a quien no conoce el motivo. La descripción evita que alguien los "arregle" sin saberlo (Cuando un semántico no es alias).

Qué tokens llevan descripción

Lo que hacen los sistemas de referencia:

• Atlassian describe cada token de su lista pública con su uso, y anota la versión en la que se introdujo (Atlassian: Design tokens, All tokens).
• El SDS de Figma deja sin descripción sus variables primitivas, en el tokens.json de su repositorio (Simple Design System).

El registro de decisiones

El registro guarda lo que una descripción no puede contar: qué alternativas había, por qué elegiste una y cuándo. Sin él, la siguiente persona que mire el sistema repetirá la discusión, o cambiará algo que se decidió por un buen motivo.

En el ejercicio del módulo 7 escribiste un registro de decisiones de accesibilidad. El de todo el sistema tiene la misma forma, con una columna más para saber de dónde viene cada decisión:

Las tres filas son decisiones reales de DesignToken101 (D02, D01 y S35). El registro completo de esta web está en su repositorio, con todas las decisiones del curso y del sistema (docs/decisiones.md).

Tres reglas para que el registro siga siendo útil:

1. Una decisión por fila, con fecha. Si la cambias, no borres la fila: añade la nueva y anota en la vieja qué la sustituye. Así se ve la historia.
2. El motivo, no la descripción. "Interlineado únicamente en código" es la decisión; "Figma lo lee como píxeles" es el motivo.
3. Las alternativas descartadas, aunque sea una. Es lo primero que preguntará quien quiera cambiarla.

Dónde vive la documentación

Lo que dice la fuente: el curso de sistemas de diseño de Figma propone, para un equipo pequeño, documentar en el mismo sitio que el sistema o en herramientas como Storybook o Notion; una web propia permite más, pero cuesta construirla y mantenerla. El mismo curso documenta las decisiones del sistema con ejemplos visuales de los valores, como referencia para quien lo usa (Figma: Lesson 4, Document and manage your system).

En Figma

Para escribir o revisar las descripciones, abre la vista Variables. En cada fila, el icono de editar abre la ventana de la variable, donde está el campo de descripción (Figma: Create and manage variables and collections).

Recorre una colección entera de una vez, grupo a grupo. Así ves los tokens parecidos uno al lado del otro, y puedes escribir en qué se diferencian mientras los comparas.

Fuentes

• Design Tokens Format Module 2025.10: Description
• Figma: Create and manage variables and collections
• Figma: Lesson 4, Document and manage your system
• Atlassian: Design tokens, All tokens
• Simple Design System (SDS) de Figma
• Repositorio de DesignToken101: docs/decisiones.md