Design tokens: la guía práctica

Los design tokens son decisiones de diseño almacenadas como datos: valores con nombre para color, tipografía, espaciado y radio que viven en un único archivo y se exportan a cada herramienta que los necesita: CSS, Tailwind, Figma, código nativo. Son la capa que mantiene honesto a un sistema de diseño: cuando los archivos de diseño y las hojas de estilo leen la misma fuente, no pueden desviarse entre sí. Este hub reúne nuestras guías sobre el formato, la nomenclatura y el flujo de trabajo; la versión en una sola pantalla es una fuente de tokens renderizada como cuatro exportaciones.

La idea en un solo movimiento

Un token sustituye un valor por una referencia. En vez de que #2563eb aparezca en cuarenta hojas de estilo y treinta rellenos de Figma, brand-600 aparece en todas partes y se resuelve al valor en un único lugar. La ventaja intuitiva es que un nombre lleva intención donde un valor no puede: #2563eb no dice nada sobre cuándo usarlo, brand-600 sí lo dice; y un cambio hecho detrás de un nombre se hace una vez, se revisa una vez y se confía en él allá donde aparezca el nombre. Toda pregunta difícil en el trabajo con tokens —nomenclatura, capas, temas, migración— es una variación de hacer ese mismo movimiento a escala, y las guías de aquí las abordan una por una. Qué son los design tokens es la introducción de nivel básico; design tokens frente a variables CSS desenreda la distinción que la terminología difumina: las propiedades personalizadas son una exportación de un archivo de tokens, no la cosa en sí.

El formato que ganó

El formato DTCG —el JSON del grupo comunitario del W3C— es lo más parecido a un estándar que tienen los tokens: $value y $type por token, referencias entre tokens, tipos compuestos para tipografía y sombras. Nuestras guías cubren cómo leerlo, cómo escribirlo y la disciplina de ida y vuelta que permite que las herramientas editen un archivo de tokens sin perder lo que las personas añadieron: el formato DTCG explicado recorre un archivo real línea a línea, importar tokens existentes cubre la ida y vuelta en sí, y Style Dictionary frente a exportación directa sopesa cuándo un pipeline de transformación se gana su lugar frente a escribir las exportaciones directamente.

Nomenclatura y capas: donde los sistemas de tokens triunfan o fracasan

La mayoría de los sistemas de tokens fracasan socialmente antes que técnicamente: nombres que nadie puede predecir, capas que nadie respeta. La decisión que lo sostiene todo es la división en capas primitiva, semántica y de componente: las primitivas guardan valores (brand-600), las semánticas guardan roles (text-primary), los componentes consumen los roles, porque esa indirección es lo que permite que un cambio de marca o de tema reapunte los roles sin tocar un solo componente. Las convenciones de nomenclatura hacen legibles las capas, y cinco antipatrones de tokens cataloga las formas en que se erosionan en la práctica. A partir de ahí toman el relevo las guías de flujo de trabajo: una única fuente de verdad describe el ciclo de principio a fin, revisar los cambios de tokens en git hace las decisiones de diseño comparables como cualquier otro código, y cómo consumen los tokens los desarrolladores en la práctica es la prueba de realidad desde el lado receptor. Para las organizaciones que aún mantienen una guía de estilo en PDF, design tokens frente a guía de estilo expone lo que cada una puede hacer y la otra no.

Donde los tokens se encuentran con el resto del sistema

Los tokens transportan los valores que deciden otros sistemas: la matemática de escalas de las escalas tipográficas y el espaciado, los roles derivados de las escalas de color, los pares de tema del modo oscuro. La capa de tokens es donde todo eso pasa a ser entregable, y por eso este hub se lee mejor después de los demás y es referenciado por todos ellos. Es también la capa que escribe Scale Composer: cada decisión de escala tomada allí —color, tipografía, espaciado, rejilla— aterriza en un único archivo DTCG, listo para las exportaciones que describe este hub.

Guías de este hub

• ¿Qué son los design tokens?

  ¿Qué son los design tokens? Decisiones de diseño con nombre —brand-600 contiene un azul exacto— compuestas mediante referencias y exportadas a CSS, Figma y código nativo.

• Cinco antipatrones de tokens

  Mejores prácticas de design tokens enseñadas a través del fracaso: cinco antipatrones — proliferación, salto de capas, vías de escape, nombres por apariencia y archivos de solo escritura.

• Cómo consumen los tokens los desarrolladores en la práctica

  La entrega de design tokens desde la silla del desarrollador: propiedades personalizadas CSS, temas de Tailwind, Figma Variables — y por qué el archivo de tokens debe tratarse como una API.

• Convenciones de nomenclatura de design tokens

  Convenciones de nomenclatura de design tokens: la anatomía category-concept-variant-state, cinco reglas que sobreviven a los cambios de marca y las microdecisiones que hay que zanjar una vez.

• Design Tokens vs Guía de Estilo

  Design tokens vs guía de estilo: la guía lleva la intención y el uso para las personas, los tokens llevan los valores para las máquinas — y cómo se componen ambos sin deriva.

• Design tokens vs variables CSS: ¿cuál es la diferencia?

  Design tokens vs variables CSS: los tokens son la fuente neutral respecto a herramientas, las propiedades personalizadas una exportación generada. Cómo se relacionan y cuándo bastan las variables.

• El formato de tokens DTCG explicado

  El formato DTCG explicado: $value y $type en cada token, grupos, referencias y tipos compuestos, además de lo que contiene un archivo de design tokens generado de verdad.

• Importar tokens existentes sin perder nada

  Cómo importar design tokens sin perder el trabajo hecho a mano: el contrato de ida y vuelta, una prueba de punto fijo de cinco minutos y qué auditar antes de confiar en una herramienta.

• Primitivo, semántico, de componente: las tres capas de tokens

  Los design tokens semánticos se sitúan entre los primitivos y los componentes. Cómo la arquitectura de tres capas convierte rediseños, temas y excepciones en cambios de una sola capa.

• Revisar cambios de tokens en Git

  Control de versiones de design tokens: por qué los cambios de tokens pertenecen a git, cómo leer un diff de tokens de seis líneas, y la lista de verificación de revisión que atrapa los cambios de diseño silenciosos.

• Style Dictionary vs exportación directa

  Style Dictionary vs exportación directa: qué te aporta un pipeline de transformación de tokens, cuándo te bastan las exportaciones integradas y cómo un archivo DTCG estándar mantiene abiertos ambos caminos.

• Una única fuente de verdad: el flujo de trabajo de tokens

  Fuente única de verdad de los design tokens: el flujo de trabajo de tokens en cinco pasos — decidir, exportar, commit, consumir, cambiar — y el fallo que reintroduce cada paso omitido.

Siente la fuente única

El argumento a favor de los tokens se comprime en una sola interacción: cambia un parámetro de escala y observa cómo se actualiza cada exportación: DTCG, propiedades personalizadas de CSS, tema de Tailwind y Variables de Figma moviéndose juntos, porque los cuatro se leen desde las mismas decisiones. Esa simultaneidad es lo que compra una capa de tokens; todo lo demás es implementación.