Convenciones para nombrar tokens

Los nombres de tokens incoherentes hacen imposible predecir qué hace un token sin leer su valor. Una convención de nomenclatura clara y predecible es fundamental para un sistema de tokens escalable.

Un patrón habitual: [category]-[property]-[variant]. Ejemplos: color-text-primary, color-text-secondary, spacing-inset-sm. Cada segmento acota progresivamente el significado.

Evite nombres de paleta como blue-500 en los componentes. Utilice nombres semánticos: color-action-default, color-feedback-error. Los nombres semánticos resisten los cambios de color de marca sin necesidad de actualizar los componentes.

Añada el estado al final: color-button-bg-default, color-button-bg-hover, color-button-bg-disabled. Los sufijos de estado coherentes hacen que los conjuntos de tokens sean predecibles y completos.

Utilice de forma coherente tallas de camiseta (xs, sm, md, lg, xl) o escalas numéricas (100, 200...900). Las escalas numéricas permiten insertar valores intermedios; las tallas de camiseta son más fáciles de leer en conjuntos pequeños.

En sistemas para varias marcas o productos, anteponga a los tokens un espacio de nombres: brand-a-color-primary frente a brand-b-color-primary. Los espacios de nombres evitan colisiones al combinar conjuntos de tokens.

La notación kebab-case se traduce directamente a propiedades personalizadas de CSS: color-text-primary se convierte en --color-text-primary. Los tokens en camel-case necesitan una transformación; los tokens en kebab-case no.

Los buenos nombres se documentan por sí mismos: spacing-stack-md (espaciado vertical entre elementos apilados, medio) comunica la intención sin un comentario. Los nombres deficientes como s3 requieren documentación externa para entenderse.

Una vez que los tokens están en uso, cambiarles el nombre es un cambio incompatible. Utilice alias de obsolescencia: conserve el nombre antiguo, pero haga que haga referencia al token nuevo. Ofrezca a los consumidores un periodo de migración antes de eliminar los tokens obsoletos.

Valide los nombres de los tokens con reglas personalizadas en Style Dictionary o con un script de CI. Rechace los tokens que no coincidan con el patrón de nomenclatura. La validación automatizada evita que la nomenclatura se desvíe a medida que crece el sistema.

Publique una guía de nomenclatura con ejemplos de nombres correctos e incorrectos. Organice un breve taller para que los equipos de diseño e ingeniería acuerden las convenciones antes de que el sistema crezca. La coherencia requiere un entendimiento compartido, no solo documentación.

¿Por qué los tokens de los componentes deben usar nombres semánticos en lugar de nombres de paleta como "blue-500"?

Una convención coherente para nombrar tokens, basada en patrones de categoría-propiedad-variante, nombres semánticos, sufijos de estado y prefijos de espacio de nombres, hace que los sistemas de tokens sean predecibles, autoexplicativos y resistentes a los cambios de marca sin romper el código de los componentes.