Tokens semánticos frente a primitivos
Un token semántico es un token de diseño nombrado por la función que cumple y no por el valor que contiene, como --color-text-danger en lugar de --color-red-600. Normalmente referencia a un token primitivo, lo que permite cambiar el valor subyacente sin renombrar nada de lo que lo usa.
Las dos capas
La mayoría de sistemas de tokens maduros tienen al menos dos niveles.
Tokens primitivos (también llamados crudos, globales o núcleo) guardan los valores reales. Se nombran de forma descriptiva:
--red-600: #DC2626;
--blue-500: #2563EB;
--space-4: 16px;Tokens semánticos guardan decisiones sobre dónde se usan esos valores. Se nombran por su función:
--color-text-danger: var(--red-600);
--color-action-primary: var(--blue-500);
--space-card-padding: var(--space-4);Los componentes referencian la capa semántica. Casi nada debería referenciar un primitivo directamente.
Por qué la indirección merece la pena
Cambiar de marca deja de ser una reescritura. Cambias a qué apunta --color-action-primary y todos los botones lo siguen. Si los componentes referenciaran --blue-500, tendrías que editar cada componente, y los que usaban azul por un motivo ajeno a las acciones se romperían.
Los temas se vuelven posibles. El modo oscuro son los mismos nombres semánticos apuntando a primitivos distintos. Sin la capa semántica no hay nada que reapuntar.
El código dice lo que significa. --color-text-danger le explica a quien lee por qué está ahí ese valor. --red-600 no dice nada, y eso pesa sobre todo cuando alguien tiene que decidir si cambiarlo es seguro.
El error habitual
Los equipos se saltan la capa semántica porque el primer día parece burocracia, cuando hay once colores y todo el mundo recuerda para qué sirven.
El coste aparece en el primer cambio de marca, el primer modo oscuro o la primera revisión de accesibilidad, y para entonces los primitivos están referenciados en cientos de sitios. Añadir después una capa semántica es un trabajo mecánico pero tedioso que nadie planifica.
Un tercer nivel
Los sistemas grandes añaden tokens a nivel de componente: --button-primary-background apuntando a --color-action-primary apuntando a --blue-500.
Ayuda cuando un componente necesita divergir de verdad, y cuesta indirección cuando no. Dos niveles es el valor por defecto correcto; añade el tercero cuando aparezca un caso real, no por adelantado.
Dónde encaja Flash DSM
Los sistemas generados vienen con ambos niveles ya montados: escalas primitivas, y roles semánticos para texto, fondo, borde y estados que las referencian, en claro y en oscuro.