Convenciones de nomenclatura de design tokens

El nombre de un design token es una ruta, leída de lo general a lo específico: category-concept-variant-state — como en color-background-subtle, space-4, text-heading-lg. Las convenciones que resisten el paso del tiempo siguen cinco reglas: nombra la decisión en lugar del valor, pon la posición antes que la apariencia para los primitivos, pon el rol antes que el contexto para los semánticos, reserva un conjunto fijo de sufijos de estado, y elige una convención de mayúsculas exactamente una vez. Todo lo que queda por debajo de esas reglas — bg o background, sm o small — es una microdecisión que se toma una vez, se anota y se deja de reconsiderar.

Este artículo cubre las convenciones de nomenclatura que atraviesan todas las categorías de tokens; es el capítulo de nomenclatura de nuestra guía de design tokens. El color y la tipografía añaden argumentos específicos de su dominio sobre estas reglas — las reglas en sí son el suelo común.

¿Cómo se estructura el nombre de un token?

Como una ruta en la que cada segmento acota al anterior. La categoría dice qué tipo de valor es (color, space, text); el concepto dice a qué parte de la interfaz sirve (background, border, heading); la variante distingue entre hermanos (subtle, raised, lg, 4); el estado — cuando aparece — nombra una condición de interacción (hover, disabled). No todos los nombres usan los cuatro segmentos: space-4 es una categoría y una variante sin nada en medio, porque el espaciado no tiene conceptos que distinguir.

Dos familias de convenciones llevan la misma ruta. El hyphen-case la escribe en plano — color-background-subtle — que es lo que quieren las propiedades personalizadas de CSS. Las rutas con puntos la escriben como anidamiento — color.background.subtle — que es lo que produce el formato DTCG, donde los grupos son objetos anidados y el nombre es la ruta hasta la hoja. La correspondencia entre ambas es una línea mecánica: reemplaza los puntos por guiones y antepón --, y toda ruta DTCG se convierte en un nombre válido de propiedad personalizada. Como la correspondencia es mecánica, el trabajo de diseño — elegir los segmentos — se transfiere sin cambios entre formatos; solo la puntuación es específica de cada formato.

¿Qué reglas de nomenclatura sobreviven al contacto con la realidad?

1. Nombra la decisión, no el valor. Esta es la ley que está en el corazón de qué son los design tokens, y toda categoría de tokens la instancia: brand-600 sobrevive al cambio de marca que vuelve la marca turquesa, mientras que blue-600 o bien miente sobre su contenido o bien obliga a renombrar en todos los archivos que lo referencian. La misma ley descarta space-16px (falso el día en que el paso se reajusta a 14) y favorece los nombres que declaran para qué sirve un token — porque el “para qué” es el hecho estable y el valor es el volátil.

2. Posición antes que apariencia, para los primitivos. 600 nombra un lugar en una rampa; dark describe cómo resulta verse el valor hoy. Cuando una rampa se reajusta — la curva de luminosidad ajustada, un paso insertado — las posiciones conservan su significado mientras que las palabras de apariencia dejan de ser ciertas sin avisar: ¿sigue siendo blue-dark más oscuro que blue-darker tras el reajuste? Las posiciones numeradas sobreviven a todo reajuste porque nunca afirman nada sobre el valor.

3. Rol antes que contexto, para los semánticos. text-primary nombra una función y se transfiere a toda pantalla que tenga texto primario; article-heading-color nombra un lugar y se queda varado ahí. Los contextos se multiplican sin límite — artículo, tarjeta, modal, barra lateral, ajustes — mientras que los roles siguen siendo contables: la mayoría de los sistemas necesitan una docena o dos. Nombrar por rol mantiene el conjunto de tokens del tamaño de la lista de roles en lugar del tamaño del producto.

4. Reserva los sufijos de estado. Declara un vocabulario corto y fijo — -hover, -pressed, -focus, -disabled, -selected — que solo aparezca al final de un nombre y solo signifique estado de interacción. La recompensa es la predicción: cualquiera que sepa que existe fill-brand puede escribir fill-brand-hover sin abrir un archivo. Un vocabulario sin reservar se degrada hasta que conviven, uno junto a otro, fill-brand-hover, fill-brandHover2 y fill-brand-mouseover.

5. Elige una convención de mayúsculas y no la reconsideres nunca. kebab-case, camelCase o rutas con puntos — la evidencia de que alguna sea superior es escasa, y por eso mismo el debate nunca se zanja por méritos. Las convenciones de nomenclatura son uno de los imanes de debate más antiguos de la programación, y la nomenclatura de tokens hereda el impuesto: los equipos pueden quemar semanas aquí, y esas semanas no compran nada, porque cualquier convención consistente rinde más que una perfecta que aún se está debatiendo — la consistencia es de lo que dependen las reglas 1–4 y cada exportación de la cadena de herramientas. Decídelo en una reunión, anota la decisión, cierra el tema.

Abre un sistema de tokens generado y lee sus nombres a través de los formatos — las mismas rutas escritas como grupos DTCG, como propiedades personalizadas de CSS y como nombres de variables de Figma, con los segmentos visibles en cada representación.

¿Debería ser bg o background, sm o small?

Importa menos cuál elijas que el hecho de que elijas una vez y lo anotes. Estas microdecisiones son donde se esconden los debates de nomenclatura una vez zanjadas las grandes reglas, así que aquí tienes un conjunto defendible de elecciones, con una línea de razonamiento cada una:

El trabajo de la tabla es estar terminada, no ser perfecta. Si tu equipo ya escribe la mitad de estas de la otra manera, conserva las elecciones existentes y documéntalas — una convención consistente heredada supera a una mejor pero inconsistente, que es de nuevo la regla 5 con otra ropa.

¿Qué hace bueno el nombre de un token?

Que pueda predecirlo alguien que nunca lo ha visto. Esa es la prueba práctica: muéstrale a alguien nuevo del equipo color-background-subtle y color-text-primary, y luego pregúntale cómo se llamaría un borde tenue. Si responde color-border-subtle — y existe — la convención está haciendo su trabajo.

La razón intuitiva por la que la previsibilidad importa más que la elegancia: una convención de nomenclatura es una pequeña gramática, y la gente generaliza a partir de las gramáticas de forma automática tras un puñado de ejemplos. Los nombres que siguen la gramática se predicen en lugar de buscarse — cada predicción correcta es una búsqueda en la documentación que nunca ocurre, un casi-duplicado que nunca se acuña, un comentario de revisión que nunca hay que escribir. Los nombres que rompen la gramática cuestan cada uno una búsqueda, para siempre. La prueba también funciona a la inversa: si cada nombre exige tener la documentación abierta, los nombres no llevan ninguna estructura que valga la pena aprender.

¿Qué aspecto tiene el conjunto de tokens de un componente, bien y mal nombrado?

Un componente de tarjeta necesita cinco decisiones de color. Aquí están dos veces — una tal como los conjuntos de tokens tienden a acumularse cuando nadie sostiene una convención, y otra siguiendo las reglas de arriba:

Ambas columnas representan la misma tarjeta hoy. Los problemas de la columna izquierda son todos problemas futuros: tres convenciones de mayúsculas en cinco nombres (regla 5); blueDark nombra un valor y mentirá tras un cambio de marca (regla 1); card_outline_gray rompe dos reglas en un solo nombre — un contexto y una apariencia — así que el siguiente componente que necesite el mismo borde o bien toma prestado un token de “tarjeta” o bien acuña un duplicado (reglas 2 y 3); cardBgHover2 lleva un estado sin reservar y un número de serie misterioso (regla 4). La columna derecha se resuelve a través de una capa semántica en pasos de rampa derivados de un solo color semilla — en esta paleta #2563eb, que es oklch(0.546 0.215 262.9) — y su sexto token es adivinable antes de que exista: un estado pressed en el botón sería color-fill-brand-pressed, y todo lector ya lo sabe.

Somete los nombres a una prueba de esfuerzo frente al cambio

Un esquema de nomenclatura se demuestra en los eventos, no en las reuniones de revisión: cambios de marca, reajustes de rampa, modo oscuro. Carga un archivo de tokens y renombra un primitivo con nombre de valor a un nombre de decisión — reexporta, y el viaje de ida y vuelta conserva cada sección que no tocaste; luego cambia el color semilla y observa cómo el token renombrado sigue diciendo la verdad mientras el valor que hay debajo se mueve.