Los tres niveles de token, y por qué tres

Casi todo el mundo que adopta tokens empieza con un nivel: una lista de colores y espaciados en :root. Casi todo el mundo acaba con tres, y llega a esa conclusión después de un rediseño doloroso. Los tres niveles no son burocracia de sistema de diseño: cada uno resuelve un problema distinto y verificable, y saltarse uno produce un fallo concreto y reconocible. Esta lección explica cuál es el fallo de cada omisión, que es la única forma de que la estructura se entienda en lugar de copiarse.

Los tres niveles

Nivel 1: primitivos. Los valores brutos, nombrados por lo que son. Una rampa de color completa, la escala de espaciado, los radios, los pesos tipográficos. No tienen ningún significado de producto: --azul-600 es un color, no es nada más.

--azul-500: oklch(0.62 0.17 262);
--azul-600: oklch(0.55 0.18 265);
--azul-700: oklch(0.47 0.17 266);
--gris-50:  oklch(0.98 0.004 265);
--gris-900: oklch(0.22 0.012 265);
--esp-1: 0.25rem;
--esp-2: 0.5rem;
--esp-3: 0.75rem;
--esp-4: 1rem;
--radio-md: 0.5rem;

Nivel 2: semánticos. Los valores nombrados por lo que significan en tu producto. No contienen valores literales: apuntan a primitivos.

--color-accion: var(--azul-600);
--color-accion-hover: var(--azul-700);
--superficie: var(--gris-50);
--superficie-elevada: white;
--texto: var(--gris-900);
--texto-tenue: var(--gris-600);
--borde: var(--gris-200);
--espaciado-interior: var(--esp-4);

Nivel 3: de componente. La configuración de un componente concreto, que por defecto apunta a semánticos y existe para poder ajustarse sin tocar nada más.

.boton {
  --boton-fondo: var(--color-accion);
  --boton-texto: white;
  --boton-relleno: var(--esp-2) var(--esp-4);

  background: var(--boton-fondo);
  color: var(--boton-texto);
  padding: var(--boton-relleno);
}

Qué falla al saltarse cada nivel

Esta es la parte que convierte la estructura en algo defendible.

Si te saltas los primitivos y escribes los valores directamente en los semánticos, el fallo es la deriva de la paleta. Sin una rampa cerrada, cada semántico nuevo se define con un color escrito a ojo, y a los seis meses tienes diecinueve grises que se diferencian en el segundo decimal. Nadie lo detecta porque cada uno se añadió por separado y todos parecían razonables. La rampa existe para que el conjunto de valores posibles sea finito y auditable.

Si te saltas los semánticos y los componentes leen primitivos —background: var(--azul-600) dentro del botón— el fallo es que el rediseño se propaga. El día que la acción primaria pasa de azul a verde, tienes que encontrar todos los sitios donde --azul-600 significaba “acción” y distinguirlos de los sitios donde significaba “es azul porque el diseño pedía azul ahí”. Esa distinción no está escrita en ninguna parte, así que hay que reconstruirla mirando pantallas. Es exactamente el trabajo que el nivel semántico existe para evitar, y es la omisión más frecuente y más cara.

Si te saltas los tokens de componente y el componente usa semánticos directamente, el fallo es la excepción que se convierte en global. Llega la petición de que el botón de la barra tenga otro fondo. Como el botón lee --color-accion directamente, las opciones son escribir una regla con un selector más específico —y volver a la escalada— o cambiar --color-accion en el contexto de la barra, con lo que cambias todo lo que sea acción ahí dentro, incluidos los enlaces y los iconos que no querías tocar. El token de componente es lo que permite mover una sola pieza.

/* con token de componente, la excepcion es quirurgica */
.barra .boton { --boton-fondo: var(--superficie-elevada); }

La regla de dirección única

Es la única regla que hay que hacer cumplir, y con ella el sistema se sostiene solo:

Cada nivel solo puede leer del nivel inmediatamente inferior. Los componentes leen semánticos. Los semánticos leen primitivos. Los primitivos no leen nada.

De ahí salen tres prohibiciones concretas:

• Un componente no lee un primitivo. Si necesita un valor que no existe como semántico, es que falta un semántico, no que haya que hacer una excepción.
• Un semántico no contiene un valor literal. Si lo contiene, ese valor está fuera de la rampa y no lo audita nadie.
• Un primitivo no apunta a otro primitivo. Eso crea alias que nadie sabe si son intencionados.

Esto se puede verificar mecánicamente, y merece la pena hacerlo. Una regla de linter que prohíba var(--azul- fuera del bloque de semánticos captura el noventa por ciento de las violaciones y es de las pocas reglas de estilo automatizables que aportan valor real.

La consecuencia que justifica todo el esfuerzo es esta: un cambio de diseño toca exactamente un nivel. Cambiar el color de marca toca primitivos. Cambiar qué significa “acción” toca semánticos. Cambiar un componente toca sus tokens. Si un cambio de diseño te obliga a tocar dos niveles, hay una violación de la regla en alguna parte y merece la pena encontrarla.

Nombrar el nivel semántico

El nivel 2 es donde se gana o se pierde el sistema, y nombrarlo bien es más difícil que los otros dos porque es el único que exige entender el producto.

El criterio que funciona: el nombre describe el papel, no la apariencia ni el sitio.

Los nombres por apariencia se rompen en el modo oscuro, donde --gris-claro-fondo contiene un gris oscuro. Los nombres por sitio se rompen en cuanto el mismo valor se usa en otro sitio, que es siempre. Los nombres por papel sobreviven a los dos.

Un buen conjunto semántico mínimo, para un producto normal, cabe en veinte tokens: superficie en tres profundidades, texto en tres énfasis, borde en dos intensidades, un color de acción con sus estados, y los cuatro tonos de significado —informativo, éxito, aviso, peligro—. Si el tuyo tiene ochenta, probablemente haya tokens de componente disfrazados de semánticos.