FICHAS QUE PERDURAN

La mayoría de los sistemas de tokens de diseño quedan obsoletos en un plazo de dos años porque codificaban los valores visuales del momento en lugar de la intención semántica que había detrás de ellos. Un token llamado «blue-500» queda vinculado para siempre a un valor de azul; un token llamado «accent-primary» sobrevive a cualquier cambio de color, ya que el siguiente diseñador lo asigna al equivalente en azul que utilice el nuevo sistema.

La única regla que distingue a los sistemas de tokens que perduran de los que desaparecen: nombra los tokens según su finalidad, no según su apariencia. «accent-primary», «surface-base», «text-secondary», «danger-bg». Nunca «blue-500», «gray-900» o «red-light». El nombre semántico es el acuerdo; el valor es el detalle de implementación.

Capa 1: primitivas. Valores básicos de color, espaciado y tipografía. azul-50, azul-100, azul-200..., azul-900. espacio-1, espacio-2..., espacio-12. Estos valores constituyen la escala subyacente y rara vez cambian.

Capa 2: semántica. Tokens con nombres específicos que se corresponden con primitivas. «accent-primary» se corresponde con «blue-500», «accent-hover» con «blue-600», «surface-base» con «gray-50» y «text-primary» con «gray-900». Los componentes hacen referencia a estos, nunca a las primitivas directamente.

Capa 3: ámbito del componente. Tokens específicos de cada componente que se corresponden con tokens semánticos. «button-primary-bg» se corresponde con «accent-primary», «card-border» con «border-subtle» y «nav-active-bg» con «accent-emphasis». Los componentes utilizan estos tokens.

Cuando se lleva a cabo la renovación de la marca, se modifica la escala primitiva y, posiblemente, la correspondencia entre semántica y primitiva. Los tokens con ámbito de componente se mantienen sin cambios. El rediseño se lanza en cuestión de días, en lugar de meses.

Codificar: color, espaciado, tipografía (familias de fuentes, tamaños, grosores, alturas de línea), radio de los bordes, sombra, duración del movimiento y aceleración, anchuras de los puntos de ruptura.

No codifiques: valores específicos del diseño (ancho máximo de 1280 en la plantilla del artículo), desplazamientos de posicionamiento puntuales, coreografías de animación exclusivas de un único componente. Estos elementos deben incluirse en el código; codificarlos crea un sistema que se contradice a sí mismo.

La prueba de fuego: ¿sería plausible que otro componente utilizara este mismo valor? Si la respuesta es sí, codifícalo. Si la respuesta es no, introdúcelo de forma fija.

Propiedades personalizadas de CSS en el límite del token. Define las primitivas y la semántica en :root; sobrescríbelas en [data-theme="dark"]. Los componentes hacen referencia a los tokens semánticos, nunca a las primitivas.

Tokens accesibles desde JS a través de un archivo TypeScript generado a partir de la misma fuente. Herramientas como Style Dictionary, Theo o un pequeño generador personalizado producen tanto variables CSS como exportaciones TS a partir de una única fuente JSON o YAML. Al tratarse de una única fuente, las animaciones en JS y los componentes con estilo se mantienen sincronizados con las hojas de estilo.

Documenta el sistema en una sola página (una página de Storybook o una página /design en la propia web) para que los futuros colaboradores puedan encontrarlo. Los sistemas de tokens que no son fáciles de encontrar acaban siendo ignorados al cabo de unos meses por personas que desconocen su existencia.