Nomenclatura de design tokens: el sistema de tres niveles y dónde falla

La convención es casi universal, lo que facilita adoptar la estructura sin el razonamiento. Cada nivel responde a una pregunta diferente, y saber cuál es esa pregunta evita colocar los elementos en el lugar equivocado.

La regla que hace que esto funcione, y la que más se incumple: nada fuera del nivel semántico puede referenciar un primitivo. En el momento en que un componente usa blue-600 directamente, el nivel primitivo se convierte en una API pública y ya no se puede cambiar un valor sin auditar todo el código, que era precisamente la razón de tener niveles.

:root {
  /* Tier 1: primitives. Values only. Nobody uses these directly. */
  --blue-600: #2563eb;
  --red-600:  #dc2626;
  --gray-500: #6b7280;

  /* Tier 2: semantic. Roles. This is the public API. */
  --color-primary:   var(--blue-600);
  --color-danger:    var(--red-600);
  --text-muted:      var(--gray-500);

  /* Tier 3: component. Only where a component truly deviates. */
  --button-danger-bg: var(--color-danger);
}

/* ✅ product code */
.alert { color: var(--color-danger); }

/* ❌ reaches past the semantic layer */
.alert { color: var(--red-600); }

Leído de izquierda a derecha, de lo general a lo específico: categoría, función, variante, estado. No todos los tokens necesitan los cuatro, y los que los requieren suelen ser interactivos.

La consistencia importa mucho más que el patrón que elija. Una base de código donde la mitad de los tokens se llaman text-color-muted y la otra mitad color-text-muted obliga a todo el equipo a hacer una comprobación cada vez, para siempre. Elija un orden, documéntelo y hágalo cumplir en las revisiones.

Aquí se muestra el patrón aplicado en lugar de descrito. Lea los nombres de los roles, no los colores; la pregunta que cada uno responde es «¿para qué sirve esto?». Un nombre que solo responde a «¿de qué color es?» ha fallado en el nivel en el que se encuentra.

Una sola pregunta resuelve la mayoría de las discusiones sobre nomenclatura en segundos:

Aplíquelo a casos reales y las respuestas serán inequívocas:

El caso de --shadow-card es sutil y merece un análisis detallado. Nombrar un token según su implementación bloquea dicha implementación. Una vez que cada tarjeta en el código dice box-shadow: var(--shadow-card), pasar a una elevación basada en bordes se convierte en una refactorización en lugar de un simple cambio de token; que es precisamente el acoplamiento que los tokens deberían eliminar.

La mayoría de los sistemas de tokens que fallan, lo hacen aquí. El nivel de componente comienza siendo pequeño y legítimo, luego lo absorbe todo y, eventualmente, se termina con cuatrocientos tokens, de los cuales la mitad tienen un único consumidor.

El mecanismo es siempre el mismo. Alguien necesita un fondo de botón que no sea exactamente --color-primary. Añadir --button-primary-bg lleva treinta segundos, mientras que añadirlo al nivel semántico requiere una conversación. Así que se introduce el token de componente, la siguiente persona hace lo mismo y el nivel semántico deja de ser la fuente de verdad sin que nadie lo haya decidido.

Una auditoría útil: cuente los tokens de nivel de componente que tengan exactamente un consumidor. Si ese número es elevado, el nivel se está usando como una vía de escape y la solución debe aplicarse en etapas anteriores.

Estos errores se repiten en casi todos los sistemas de tokens que dejan de utilizarse. Cada uno tiene una solución económica si se detecta a tiempo y una costosa si no es así.

1. 1

   Escalas numeradas sin anclaje

   De color-1 a color-12 no dice nada a nadie, y los números adquieren significado solo a través del folclore. Las escalas numeradas están bien en el nivel primitivo, donde el número sigue una dimensión real como la luminosidad. Nunca son aceptables en el nivel semántico, porque el propósito de ese nivel es definir para qué sirve algo.

2. 2

   Codificar el tema en el nombre

   Tener --light-bg y --dark-bg como tokens separados significa que cada componente hace referencia a ambos y bifurca la lógica. Un nombre, dos valores, cambiados según el tema: para eso sirve la capa de tokens. Si encuentra if (theme === 'dark') en el código de un componente, los tokens están mal nombrados.

   Copy

   /* ❌ */  --light-bg: #fff;  --dark-bg: #0a0a0a;
   /* ✅ */  --surface-base: #fff;
            [data-theme="dark"] { --surface-base: #0a0a0a; }

3. 3

   Tamaños nombrados según dónde se utilizan hoy

   --text-hero funciona bien hasta que el tamaño hero aparece en una tabla de precios. --text-4xl o --font-scale-7 nombran el paso, no el sitio, y sobreviven a la reutilización. Nombre por posición en una escala, no por el primer cliente.

4. 4

   Colores de estado que actúan como colores de marca

   La forma más común en que un sistema se vuelve incapaz de mostrar estados. Si el verde de marca y el verde de éxito son el mismo token, no se puede rediseñar la marca sin cambiar la apariencia del éxito, y no se puede distinguir una fila saludable de una de marca. Mantenga el conjunto de estados reservado e indíquelo en un comentario.

5. 5

   Abreviaturas que solo una persona sabe expandir

   --clr-bg-scndry ahorra once caracteres y obliga a cada lector a realizar un paso de decodificación para siempre, incluyendo a un modelo que debe adivinar si scndry es secondary o una errata. El autocompletado hace que la longitud sea prácticamente gratuita. Escriba las palabras completas.

Los tokens tienen que viajar cada vez más: desde una herramienta de diseño a CSS, a un tema de Tailwind, a una plataforma nativa, a un elemento del registro de shadcn, a un DESIGN.md que lee un agente. Esto impone una restricción en los nombres que la mayoría de los equipos no consideran hasta que falla la primera exportación.

La regla práctica: elija nombres que sean simultáneamente una propiedad personalizada de CSS válida, una clave de JSON válida y una frase en inglés legible. El formato plano, en minúsculas y con guiones satisface las tres condiciones, y los grupos anidados del formato de tokens DTCG/W3C pueden generarse a partir de un conjunto plano mucho más fácilmente que a la inversa.

La decisión de nomenclatura con mayor impacto no es el patrón. Es si los nombres en su herramienta de diseño son idénticos a los nombres en el código.

SLDS 2 de Salesforce es el ejemplo publicado más claro: su librería de Figma utiliza los mismos nombres de hooks semánticos que el CSS —sus propios ejemplos son radius-border-4 y font-scale-4— por lo que los diseños se mapean uno a uno con el código real. Su objetivo declarado es un vocabulario compartido que una el diseño y el desarrollo.

El efecto práctico es que desaparece toda una clase de errores de handoff. Cuando un diseñador dice font-scale-4 y un desarrollador escribe font-scale-4, no hay paso de traducción y, por lo tanto, no hay lugar para que el significado se pierda. Compare esto con un estilo de Figma llamado "Heading / Large" que se mapea a una variable de CSS llamada --text-2xl, donde cada handoff es una búsqueda y cada búsqueda es una oportunidad de equivocarse.

La nomenclatura de tokens solía ser una cuestión de ergonomía humana: autocompletado, legibilidad, onboarding. Cada vez más, el lector más frecuente de su archivo de tokens es un agente de código, y eso cambia cuáles fallos son los que importan.

Un humano que no sabe cuál de dos grises usar preguntará, o elegirá uno y se le corregirá en la revisión. Un modelo elegirá uno, silenciosamente, en cada archivo que toque, y la inconsistencia llegará más rápido de lo que la revisión puede detectar. La ambigüedad en el nivel semántico es un defecto mucho más costoso de lo que solía ser.

Analizamos 299 archivos DESIGN.md publicados para que los lean los agentes y descubrimos que el 86% especifica los colores como valores hex puros sin ningún rol semántico asociado. No tokens mal nombrados, sino ausencia de tokens. A un modelo al que se le da #6b7280 y se le dice que es parte de la paleta, lo usará donde sea plausible un gris medio: texto del cuerpo, bordes, iconos, placeholders, estados desactivados. Cinco funciones diferentes, un solo valor, sin forma de cambiar ninguno de ellos independientemente más adelante.

La segunda versión cuesta tres líneas adicionales y permite oscurecer los bordes sin oscurecer los subtítulos; un cambio que querrá realizar y que la primera versión hace imposible sin una auditoría de todo el código base.

Si está nombrando un sistema desde cero, este es un mínimo defendible. Es reducido a propósito: un sistema que nadie puede retener en la cabeza acaba siendo ignorado.

/* Surfaces — what things sit on */
--surface-base        /* the page */
--surface-raised      /* cards, panels */
--surface-overlay     /* modals, popovers */
--surface-sunken      /* wells, inset areas */

/* Text — by emphasis, never by colour */
--text-primary
--text-secondary
--text-muted
--text-disabled
--text-on-accent      /* text sitting on the accent colour */

/* Borders — by weight of presence */
--border-subtle
--border-strong
--border-focus

/* Action — the interactive colour and its states */
--action-primary
--action-primary-hover
--action-primary-active

/* Status — reserved. Nothing decorative uses these. */
--status-success
--status-warning
--status-danger
--status-info

Dos notas sobre ese conjunto. Los tokens de texto se nombran por énfasis en lugar de por color, para que sigan siendo coherentes en el modo oscuro. Los tokens de estado incluyen un comentario que los reserva, ya que la forma más común en que un sistema de estados falla es cuando un diseñador usa el verde de éxito como acento decorativo y luego nadie puede distinguir una fila correcta de una con colores de marca.