Nombrar tokens de color: brand-600 vs blue-600

Dos archivos de tokens se enfrentan al mismo cambio de marca. En el primero, la paleta se nombró por tono: blue-600, referenciado en cientos de archivos. La marca se vuelve teal, y todas las opciones son malas: mantener el nombre y blue-600 ahora guarda un teal, mintiéndole a cada futuro lector; o renombrarlo y tocar cada referencia en el código. En el segundo archivo, el mismo color se llamó brand-600. El cambio de marca es una sola edición: el valor cambia, el nombre sigue diciendo la verdad, nada aguas abajo se mueve.

Nombrar tokens de color funciona por capas, hasta tres. La capa primitiva nombra el lugar de un color en la paleta (brand-600); la capa semántica nombra los trabajos de la interfaz (background, text-primary, accent) y apunta a las primitivas; la capa de componente opcional (button-bg) existe solo donde un componente realmente necesita desacoplarse de la semántica. En el nivel primitivo, brand-600 le gana a blue-600 para una paleta de una sola marca porque nombra el rol que juega un color, no el tono que resulta tener, aunque los nombres por tono siguen siendo una opción defendible para paletas crudas de múltiples tonos. Lo que significa el número en sí —la posición en la escala detrás del 600— lo cubre nuestra guía de escalas de color; este artículo trata sobre las palabras que van delante.

¿Las primitivas deberían llamarse brand-600 o blue-600?

Ambas posturas merecen su defensa honesta.

El argumento a favor de brand-600: el hecho estable de una primitiva es su posición en la paleta de este producto, no su longitud de onda. La paleta tiene un tono principal, un conjunto de neutros, quizá un secundario: esos son roles, y sobreviven a cada evento en la vida de la paleta. El tono es la propiedad volátil: los cambios de marca lo modifican, y el escenario inicial es lo que cuesta el nombre blue-600 cuando eso ocurre. Nadie que consuma una paleta de una sola marca necesitó nunca saber que el color de marca es azul; necesitaba saber que es el color de marca. Los grupos de paleta de Scale Composer se nombran justo con este principio —Brand, Secondaries, Neutral, Functional—: roles primero, tonos en ningún sitio.

El argumento a favor de blue-600: en un sistema de múltiples tonos puede que no haya ningún rol que nombrar. Una paleta cruda que ofrece veinte tonos como material de propósito general —la postura de Tailwind— no tiene ninguna «marca» entre ellos; el tono es el único nombre honesto que esa paleta puede ofrecer, y blue-600 es exactamente lo correcto ahí. La misma lógica cubre los conjuntos categóricos de gráficas, donde seis tonos son pares sin ninguna jerarquía que codificar.

La regla general se deduce con limpieza: si la paleta pertenece a una marca, nombra las primitivas por rol; si es una caja de crayones al servicio de muchos amos, nómbralas por tono. La mayoría de los sistemas de diseño de producto son del primer tipo y heredan los nombres del segundo al copiar las convenciones de un framework, y así es como blue-600 acaba mintiendo tras un cambio de marca que nadie planeó.

¿Qué añade la capa semántica?

Indirección con significado. Los tokens semánticos nombran trabajos —background, surface, border, text-primary, text-secondary, accent, los colores de estado interactivo— y cada uno apunta a una primitiva. Los componentes consumen tokens semánticos y nunca tocan las primitivas directamente.

La ventaja es que significado y valor pasan a ser modificables de forma independiente. Un componente escrito contra text-primary funciona en cualquier tema, porque el nombre promete un trabajo, no un valor; un componente escrito contra brand-900 ha fijado por código una suposición sobre qué paso hace ese trabajo hoy. La capa es también donde la accesibilidad vive de forma natural: un trabajo como «texto primario sobre esta superficie» lleva consigo un requisito de contraste, así que el token que nombra el trabajo es el lugar adecuado para imponerlo. Scale Composer deriva así aproximadamente diecisiete roles semánticos por superficie —cada rol apuntando a un paso de escala, comprobado contra los mínimos de WCAG (4,5:1 para texto de cuerpo, 7:1 para el nivel más estricto) con APCA mostrado al lado—. El sistema de tokens de Material Design documenta la misma arquitectura por capas —tokens de referencia, de sistema y de componente en su resumen de design tokens— con nombres de capa distintos.

Mira las capas en una paleta real en Scale Composer: las rampas primitivas agrupadas por rol, los roles semánticos de una superficie apuntando a ellas, y el panel de exportación llevándose ambas capas como DTCG, CSS, Tailwind o Figma Variables.

¿Cuándo se gana su lugar una capa de componente?

Rara vez, y ese es el diseño de la capa, no su debilidad. Un token de componente como button-bg se justifica cuando un componente debe desacoplarse de la capa semántica: el sitio de marketing reapunta accent a un tono secundario, pero el botón primario debe permanecer en el color de marca, así que button-bg deja de seguir a accent y se ancla a la primitiva de marca. Eso es un desacoplamiento real, y el token lo registra.

Sin esa divergencia, un token de componente es indirección sin significado: button-bg → accent → brand-600, tres nombres para un valor que nunca varía de forma independiente. Multiplicado a lo largo de una biblioteca de componentes, esto produce esos conjuntos de tokens que nadie sabe navegar. Un valor por defecto razonable: introduce el token de componente cuando aparece la excepción, no antes de ella.

¿Qué te aportan las capas cuando algo cambia?

Tres escenarios, con el color semilla azul #2563eb —oklch(0.546 0.215 262.9)— haciendo de marca.

Cambio de marca. La paleta se vuelve a derivar desde un color semilla teal. Las primitivas mantienen sus nombres e intercambian valores: brand-600 ya no guarda ≈#3E65B5, pero sigue siendo el 600 de la rampa de marca. La capa semántica, que apunta a nombres en vez de a valores, no cambia en absoluto. Los componentes no notan nada.

Modo oscuro. Los nombres semánticos conservan su significado mientras sus objetivos se mueven: accent apunta a brand-600 (≈#3E65B5) en el tema claro y a un paso más claro como brand-300 (≈#71AEFF) en el oscuro, donde un fondo oscuro exige un acento más claro para el contraste. Los valores incluso provienen de rampas distintas —una paleta oscura derivada se genera con su propia curva de luminosidad y un aumento de croma de aproximadamente un 20 %—, y aun así un componente sigue diciendo simplemente accent.

Una primitiva, varios trabajos. El mismo brand-600 puede servir como texto accent en una superficie y como el relleno en reposo del botón en otra. Un valor almacenado, varios significados, y los significados viven en la capa semántica, que es toda la razón de su existencia. Colapsa las capas y cada uno de estos cambios se convierte en un buscar-y-reemplazar por todos los componentes.

Nombrar es además la parte de un sistema de tokens que sobrevive a la herramienta que lo creó: los nombres elegidos aquí son lo que cada exportación lleva al código y a los archivos de diseño, con el hex junto al OKLCH. Y el camino de migración funciona en ambas direcciones. Importa tu archivo de tokens existente y renombra una capa: carga un archivo DTCG, renombra las primitivas nombradas por tono a nombres por rol, y vuelve a exportar; el viaje de ida y vuelta preserva las secciones que no tocaste, así que una limpieza de nombres cuesta exactamente los tokens que renombra.