TOKENS QUE SOBREVIVEN
Construye un sistema de tokens de diseño que perdure más allá del próximo cambio visual. Estructura de tres capas, nombres semánticos, patrones del mundo real.
Por qué la mayoría de sistemas de tokens no sobreviven rediseños
La mayoría de sistemas de tokens de diseño se retiran en menos de dos años porque codificaban los valores visuales del momento en lugar de la intención semántica detrás de ellos. Un token llamado blue-500 queda atado a un valor azul para siempre; un token llamado accent-primary sobrevive cualquier cambio de color porque el próximo diseñador lo mapea a cualquier equivalente azul que use el nuevo sistema.
La regla única que separa los sistemas de tokens que sobreviven de los que mueren: nombra los tokens por propósito, no por apariencia. accent-primary, surface-base, text-secondary, danger-bg. Nunca blue-500, gray-900, red-light. El nombre semántico es el contrato; el valor es el detalle de implementación.
La arquitectura de tres capas
Capa 1: primitivos. Valores brutos de color, espaciado, tipografía. blue-50, blue-100, blue-200..., blue-900. space-1, space-2..., space-12. Estos existen como la escala subyacente y rara vez cambian.
Capa 2: semántica. Tokens nombrados según su propósito que se mapean a primitivos. accent-primary se mapea a blue-500, accent-hover se mapea a blue-600, surface-base se mapea a gray-50, text-primary se mapea a gray-900. Los componentes hacen referencia a estos, nunca directamente a los primitivos.
Capa 3: con alcance de componente. Tokens por componente que se mapean a los semánticos. button-primary-bg se mapea a accent-primary, card-border se mapea a border-subtle, nav-active-bg se mapea a accent-emphasis. Los componentes los consumen.
Cuando ocurre la renovación de marca, cambias la escala primitiva y posiblemente el mapeo de semántico a primitivo. Los tokens con alcance de componente fluyen sin cambios. El rediseño se lanza en días en lugar de meses.
Qué codificar y qué dejar hardcodeado
Codifica: color, espaciado, tipografía (familias de fuente, tamaños, pesos, alturas de línea), border-radius, sombra, duración de movimiento y easing, anchos de breakpoint.
No codifiques: valores específicos de diseño (max-width de 1280 en la plantilla de artículo), desplazamientos de posicionamiento puntuales, coreografía de animación única para un solo componente. Estos deben ser inline; codificarlos crea un sistema que se contradice a sí mismo.
La prueba de fuego: ¿plausiblemente usaría otro componente este mismo valor? Si sí, codifícalo. Si no, déjalo hardcodeado.
Implementación en toda la pila
Propiedades personalizadas CSS en el límite del token. Define los primitivos y semánticos en :root, sobrescribe en [data-theme="dark"]. Los componentes hacen referencia a los tokens semánticos, nunca a los primitivos.
Tokens accesibles desde JS mediante un archivo TypeScript generado de la misma fuente. Herramientas como Style Dictionary, Theo, o un pequeño generador personalizado producen tanto variables CSS como exportaciones TS desde una única fuente JSON o YAML. Una única fuente significa que las animaciones JS y los componentes estilizados se mantienen sincronizados con las hojas de estilos.
Documenta el sistema en una sola página (una página de Storybook o una página /design en el sitio mismo) para que los colaboradores futuros lo encuentren. Los sistemas de tokens que no son descubribles se ignoran en cuestión de meses por personas que no saben que existen.