Design Tokens vs Guía de Estilo

El nuevo portal de marca se lanzó entre aplausos: cada color pintado como una muestra generosa, los códigos hex compuestos en los pies de foto, diagramas de espaciado, una página por componente. Al cabo de un año estaba silenciosamente equivocado. Un ajuste de contraste había desplazado el azul de marca en el código; el portal seguía mostrando el valor antiguo; y los diseñadores habían aprendido a usar el cuentagotas sobre la pantalla de producción más reciente en su lugar. La documentación más cuidada de la empresa se había convertido en la menos fiable.

Una guía de estilo y los design tokens documentan mitades distintas de un mismo sistema: la guía de estilo lleva la intención y el uso para las personas —cuándo se aplica cada nivel de encabezado, cómo suena la voz, qué aspecto tiene un «no hagas esto»— mientras que los tokens llevan los valores para las máquinas, como entradas con nombre que un paso de compilación lee directamente. Se componen por referencia: la guía moderna nombra tokens (accent, space-4) en lugar de incrustar sus valores, así que no puede quedar obsoleta como le pasó a aquel portal. Este artículo adopta la perspectiva de la arquitectura de la documentación; los fundamentos de los tokens viven en nuestra guía de design tokens. (Si los términos se difuminan: un sistema de diseño es el paraguas, y la guía de estilo y el archivo de tokens son dos de sus estratos —este texto trata de cómo esos dos se reparten el trabajo.)

¿Qué hace una guía de estilo que los tokens no pueden?

Una guía de estilo es un conjunto de estándares sobre cómo se diseñan y se escriben las cosas, y su contenido irremplazable es el criterio, no los números. Cuándo usar cada nivel de encabezado, y por qué saltarse uno hace daño. Qué debería transmitir la fotografía, mostrado como un buen ejemplo y uno malo, lado a lado. Por qué el color de acento se reserva para las acciones, y la justificación de accesibilidad detrás de qué combinaciones se permiten. Cómo suena la marca —con la frase que diría y la frase que no diría.

Nada de esto encaja en un esquema de tokens. Un token puede afirmar que text-primary es un casi-negro concreto; no puede explicar qué cuenta como texto primario, ni contener un ejemplo de «no hagas esto» —que está entre las formas más densas en información de la documentación de diseño y no tiene equivalente en tokens. Este es el verdadero trabajo de la guía de estilo, y la tokenización no lo toca. Lo único que muere es el otro hábito de la guía: cargar con valores.

¿Qué contienen los design tokens que una guía de estilo no puede?

Las respuestas exactas. brand-600 es un azul concreto —#2563eb, que es oklch(0.546 0.215 262.9)— almacenado una sola vez, en un archivo que Figma, una compilación de hojas de estilo y una app nativa leen sin una persona de por medio. Una guía solo puede mostrar una imagen de ese valor y esperar que cada lector lo extraiga fielmente; el token es el valor, sin ningún paso de renderizado que sobrevivir ni ningún lector que lo aproxime.

¿Cómo se volvieron «vivas» las guías de estilo, y por qué no bastó?

La historia transcurre en tres generaciones. La primera fue estática: manuales impresos, luego PDF y páginas web, con los valores pintados en muestras y pies de foto —copias del día en que se publicaron. La segunda, la guía de estilo viva, generaba sus páginas a partir del código de producción, así que las muestras enseñaban lo que de verdad se había publicado —pero seguía siendo de solo lectura: un espejo de los valores más que una fuente de ellos, cierto mientras lo mirabas, sin autoridad sobre el siguiente cambio. La tercera forma invierte la relación: la documentación referencia los tokens por su nombre, el archivo de tokens posee los valores, y los demás artefactos —incluidas las propias muestras de la guía— se renderizan a partir de él. Una guía construida así no puede mentir sobre los valores, porque no carga con ninguno.

¿Por qué se pudren los valores documentados?

Porque cada valor que un documento incrusta es una copia, y las copias mantenidas por manos distintas se separan con el tiempo —el mismo mecanismo de una sola frase que hay detrás de la mayoría de las historias de deriva entre diseño y código. Una guía que dice #2563EB es correcta hasta el primer reajuste en cualquier otro punto del sistema; una guía que dice brand-600 sigue siendo correcta a través de cada reajuste, porque enuncia una relación en lugar de una instantánea. La versión intuitiva: una copia puede quedar obsoleta, un puntero no. Pedirle al lector que consulte una cosa es el precio de no decirle nunca algo falso.

¿Qué aspecto tiene la misma documentación de un botón en ambos enfoques?

Con los valores incrustados, tal como lo escribió el portal de primera generación:

Los botones primarios usan el azul de marca (#2563EB) como fondo, con texto blanco, 16px de relleno lateral y un radio de esquina de 6px.

Con referencia a tokens:

Los botones primarios usan accent como fondo, con texto on-accent, relleno lateral space-3 y esquinas radius-sm. Usa uno por vista, para la acción principal de la página; cualquier otra cosa lleva un botón secundario. Los valores actuales viven en el archivo de tokens.

Ahora pasa un cambio de marca por ambos. La paleta se vuelve a derivar a partir de un color semilla turquesa: brand-600 conserva su nombre y almacena un valor nuevo, y accent —el rol que nombra la documentación del botón— sigue apuntando a él. El párrafo con referencia a tokens queda intacto y sigue siendo cierto. El párrafo con los valores incrustados ahora enuncia un hex falso —y sus otros tres valores incrustados (blanco, 16px, 6px) son responsabilidades aparte, cada una a la espera de su propio reajuste. Fíjate también en para qué ganó espacio la versión con tokens: liberada de cargar con valores, gasta su extensión en el uso —uno por vista— que es el contenido para el que existe una guía.

Abre en Scale Composer los roles que nombra esta documentación —la capa semántica con accent, on-accent y el resto de roles derivados junto a sus valores actuales y los umbrales de contraste con los que se comprueba cada combinación. Esta es la mitad del par a la que apunta una guía con referencia a tokens: reajusta el color semilla y los nombres se mantienen mientras los valores responden de otra forma.

¿Cómo se componen tokens, documentación y ejemplos?

Como un trío con una sola dirección de referencia. El archivo de tokens contiene los valores. La guía de estilo contiene la intención y el uso, nombrando tokens allí donde se pretende un valor. Los ejemplos en vivo —componentes renderizados, páginas de muestras, textos de espécimen— se generan a partir del archivo de tokens, así que incluso las imágenes son vistas de la fuente en lugar de rivales suyas. Cada artefacto hace el único trabajo para el que está estructuralmente preparado: la prosa transfiere criterio, los tokens transfieren valores, y los ejemplos renderizados transfieren la gestalt que ni la prosa ni el JSON pueden. A veces los equipos manejan el trío como un par —tokens más una guía que los referencia, con los ejemplos aplazados— y eso funciona; colapsar todo en un solo artefacto es la disposición que fracasa, sea cual sea el que se conserve.

Reescribe un párrafo de tu guía

El cambio es más fácil de juzgar sobre un solo párrafo. Toma una regla de tu guía actual que cargue con valores —la especificación del botón de arriba sirve de plantilla— y reescríbela para que nombre roles en lugar de incrustar números. Genera el conjunto de tokens al que tu guía haga referencia —dale como semilla tu color de marca, deja que los roles derivados se conviertan en los nombres a los que apunta tu documentación, y exporta el archivo para que los valores de la guía tengan un hogar que no sea la guía.