Convenciones de nombres de design tokens: sistema de 3 niveles

Al terminar esta guía tendrás un esquema de nombres en el que cualquier desarrollador puede nombrar un token nuevo bien a la primera, sin preguntar a nadie. El esquema usa tres niveles, primitivo, semántico y de componente, y el propio nombre te dice a qué nivel pertenece un token.

Una convención de nombres para design tokens es el conjunto de reglas que decide cómo se llama cada token y en qué orden van las partes del nombre. Si lo haces bien, el sistema escala. Un diseñador añade un color, un desarrollador sabe dónde va y el cambio a modo oscuro toca unas pocas líneas. Si lo haces mal, acabas con blue2, blueDark y brandBlueNew apuntando a tres tonos que seis meses después nadie sabe distinguir.

Qué necesitas antes de empezar

Tres cosas, y la segunda es la que más discusiones genera, así que ciérrala primero.

• Una lista de los valores en crudo que ya hay en tu producto: colores, pasos de espaciado, tamaños de fuente, radios, sombras y duraciones. Estás nombrando lo que existe, no inventando una paleta.
• Un acuerdo sobre un único delimitador y un único orden de palabras. Mezclar color-bg-primary y colorBgPrimary en el mismo sistema rompe las herramientas y la búsqueda. Elige uno y hazlo cumplir.
• Un formato de archivo donde escribir. Desde octubre de 2025 el W3C Design Tokens Format Module tiene una primera versión estable, así que el JSON con $value y $type es un valor por defecto seguro que Style Dictionary, Tokens Studio y las variables de Figma leen todos.

Paso 1: divide cada token en uno de tres niveles

Los sistemas maduros, entre ellos Carbon de IBM, organizan los tokens en tres niveles unidos por una cadena de referencias: primitivo hacia semántico hacia componente. Cada nivel responde a una pregunta distinta.

• Primitivo (también llamado global o base): el valor en crudo sin contexto. blue-500 dice que existe un azul y a cuánto equivale. No dice dónde usarlo.
• Semántico (también llamado alias): la intención. color-text-default apunta a un primitivo y dice para qué sirve ese valor.
• De componente: ligado a un solo componente. button-background-hover apunta a un semántico y existe para que un componente pueda divergir por su cuenta.

Los primitivos son las opciones. Los semánticos son las decisiones. El producto consume los tokens semánticos y de componente; los primitivos quedan tras el telón como valores de referencia.

Paso 2: nombra los primitivos por lo que son

Los primitivos describen la apariencia, porque la apariencia es todo lo que llevan. Usa una categoría, un tono o propiedad y una escala numérica: color-blue-500, dimension-space-4, font-size-300. La escala numérica importa. Pasos de 100 (de 100 a 900) dejan hueco para insertar un valor más adelante sin renombrar a sus vecinos. Evita adjetivos como blueMedium o spaceBig: se quedan sin margen en cuanto añades un tono entre dos de ellos.

Paso 3: nombra los tokens semánticos por intención, nunca por apariencia

Esta es la única regla que ahorra más problemas. Nombra un token semántico por lo que hace, no por cómo se ve. Usa color-feedback-success, no color-green. Cuando una marca muestra el éxito en ámbar, o el modo oscuro invierte una superficie, el nombre de intención aguanta y solo cambia su referencia. Un nombre de apariencia como color-green-button se convierte en una mentira el día en que el valor deja de ser verde.

La taxonomía de tokens de Nathan Curtis da los niveles a los que puede recurrir un nombre semántico: namespace, categoría, concepto, propiedad, variante, estado y escala. Rara vez los usas todos. Una forma común y legible es categoría, concepto, propiedad y luego estado: color-action-primary-hover. Leído de izquierda a derecha dice: un color, para acciones, la primaria, en su estado hover.

Paso 4: añade tokens de componente solo cuando un componente se lo gana

Un token de componente existe para dar a un solo componente un gancho que un diseñador puede reapuntar sin tocar la capa semántica compartida. card-border-default permite al equipo de la card cambiar los bordes de la card por su cuenta. Es útil el día en que un componente necesita divergir de verdad. Es ruido todos los demás días. Parte de la capa semántica. Asciende un valor a token de componente cuando, y solo cuando, aparece una divergencia real. La mayoría de los componentes no necesita ninguno.

Paso 5: fija un delimitador y un orden, luego escríbelo en el linter

Ordena los niveles de lo general a lo específico: namespace, categoría, concepto, propiedad, variante, estado, escala. Quita los niveles que un token no use. El propio ejemplo de Curtis, esds-color-neutral-42, empaqueta en ese orden un namespace (esds), una categoría (color), una variante (neutral) y una escala (42).

El delimitador depende de la salida. Usa puntos en el origen JSON (color.text.default), porque así se anidan los grupos en el formato W3C. Usa guiones en las custom properties CSS que emite tu build (--ds-color-text-default). Elige un único prefijo de namespace para la capa CSS (aquí --ds-) para que tus tokens nunca choquen con una hoja de estilos de terceros. Una herramienta como Style Dictionary transforma un solo origen en cada salida, así que el nombre lo escribes una sola vez.

Paso 6: convierte la convención en una gramática de una página

Una lista de tokens queda obsoleta la semana siguiente de publicarla. Una gramática de una página no. Escribe cada nivel, las palabras permitidas en ese nivel (¿es bg o background, text o fg?) y el orden en que aparecen. Con la gramática en la mano, un desarrollador nombra un token que no ha visto nunca y llega al mismo nombre que habría elegido un mantenedor. En eso consiste una convención.

¿Cómo sabes si la convención funciona?

Dos pruebas. Primera: dale a un desarrollador nuevo un valor en crudo sin token y pídele que lo nombre. Si produce el nombre que habrías escrito tú, sin preguntar, la convención aguanta. Si se equivoca, la gramática tiene un hueco. Segunda: ejecuta un cambio de tema. Un rebrand o un modo oscuro deberían tocar la capa semántica y nada más. Si obliga a editar decenas de tokens de componente, tu capa semántica es demasiado fina y los componentes apuntan directamente a los primitivos.

Errores comunes y cómo corregirlos

• Palabras de apariencia en la capa semántica. color-green-success anula el propósito. Renómbralo a color-feedback-success y reapunta la referencia.
• Codificar el valor en el nombre. color-text-16px mezcla un color con un tamaño. El tamaño es un token aparte; mantén separados los dos ejes.
• Proliferación de sinónimos. bg, background y surface usados para el mismo concepto obligan a todos a adivinar. Elige una palabra por concepto y prohíbe las demás en el linter.
• Anidamiento sin control. color-button-primary-default-hover-large tiene demasiados niveles para leerse. Limita los nombres a unos cuatro niveles con sentido; si necesitas más, dentro se esconde un token de componente.
• Tokens de componente por defecto. Crear button-*, card-* y modal-* para cada propiedad antes de que ninguna diverja duplica la superficie sin ningún beneficio. Espera a la divergencia.

Para profundizar

El naming es una capa de una estructura más amplia. Lee design tokens, variables CSS y Tailwind comparados para ver dónde encajan los tokens en el stack, la estructura de un design system para el orden en que construir las categorías y el component drift para lo que pasa cuando una convención existe sobre el papel pero nadie la hace cumplir.