Primitivo, semántico, de componente: las tres capas de tokens

«El rediseño de marca se estimó en tres días. Tardó tres semanas.» El análisis posterior detrás de esa frase suele ser el mismo: el color de marca antiguo existía como hex en crudo, pegado en cientos de componentes, así que «cambiar el azul por el verde azulado» no era un solo cambio, sino un buscar-y-reemplazar por todo el código, más una revisión de cada lugar donde el reemplazo se equivocó. Nada estaba mal construido; simplemente no había ninguna capa donde «el color de marca» existiera como una única decisión.

La arquitectura de tokens evita exactamente esto, con hasta tres capas. Los tokens primitivos son el vocabulario en bruto — brand-600, space-4, text-lg — valores con nombres posicionales y sin opinión sobre su uso. Los design tokens semánticos son las decisiones — background, text-primary, accent, gap-section — nombres de rol que apuntan a los primitivos; aquí es donde vive la intención de diseño. Los tokens de componente — button-bg apuntando a accent — son una tercera capa opcional para los casos en que un componente debe desligarse de un valor semántico por defecto. Los componentes leen la capa semántica, y los cambios habituales — rediseño de marca, tema, excepción — aterrizan cada uno en una sola capa. El concepto general de token tiene su propio artículo en nuestra guía de design tokens; este trata sobre el modelo de capas en sí.

¿Qué hace cada capa?

Los primitivos son la paleta y las escalas: de brand-50 a brand-900, de space-1 a space-7, de text-sm a text-xl. Sus nombres declaran una posición, nunca un propósito: brand-600 te dice qué azul es, y deliberadamente nada sobre dónde pertenece. Son el vocabulario del sistema: todo lo que se puede decir, nada dicho todavía.

Los tokens semánticos dicen cosas. background → neutral-50, text-primary → neutral-800, accent → brand-600, gap-section → space-7: cada uno es una decisión de diseño — este rol lo desempeña ese valor — registrada como una referencia. Cuando alguien pregunta dónde está escrita la intención de diseño de un producto, esta capa es la respuesta.

Los tokens de componente registran excepciones. button-bg normalmente no tiene razón de existir: el botón puede leer accent directamente. Se gana su lugar el día en que el botón debe dejar de seguir a accent: un tema de marketing reapunta accent a un tono secundario, pero el botón primario tiene que mantenerse fiel a la marca. El token de componente registra esa desvinculación.

El sistema de tokens de Material Design documenta la misma arquitectura de tres niveles — tokens de referencia, de sistema y de componente — en su resumen de design tokens, bajo otros nombres de capa.

¿Qué reglas hacen que las capas funcionen?

Tres reglas, cada una protegiendo una propiedad distinta:

• Los componentes consumen semántica, nunca primitivos. Un componente que lee brand-600 ha fijado en código una suposición sobre qué paso hace qué trabajo hoy; un componente que lee accent declara una necesidad y deja que el sistema la resuelva. Esta regla es lo que abarata los rediseños de marca y los temas: rómpela y la capa por encima de la ruptura deja de protegerte.
• La semántica apunta hacia abajo, un solo salto. Un token semántico referencia un primitivo, no otro token semántico. Cadenas como button-text → text-inverse → on-dark → neutral-50 parecen flexibilidad pero cuestan navegabilidad: nadie puede resolver un valor sin ponerse a excavar. Un solo salto mantiene cada rol resoluble en una única consulta.
• Los primitivos no referencian nada. Son el suelo. Todo rastreo, seguido hacia abajo, termina en un primitivo que contiene un valor literal, que es lo que hace que los rastreos sean finitos y los archivos depurables.

¿Por qué las capas superan a una lista plana de tokens?

Por lo que cuesta cada cambio. En un sistema por capas, los tres cambios habituales tocan una sola capa cada uno:

En una lista plana — o peor, valores en crudo dentro de los componentes — cada uno de estos se convierte en el rediseño de tres semanas del inicio: un buscar-y-reemplazar por todo, con decisiones de criterio en cada coincidencia, porque el mismo #2563eb que significaba «marca» en un archivo significaba «color de enlace que casualmente coincide» en otro.

El porqué intuitivo merece declararse como el paralelismo con la programación que en realidad es: las capas son indirección, y la indirección es como el software siempre ha contenido el cambio — la misma razón por la que el código llama a funciones en lugar de repetir sus cuerpos. Un token semántico es una interfaz; los primitivos son la implementación; y los cambios dejan de propagarse en la frontera entre ambos. Los sistemas de diseño no inventaron el truco, lo heredaron.

¿Cómo se ve un rastreo completo?

Hacia abajo, desde un componente: button.background lee {semantic.accent}; accent lee {color.brand.600}; brand-600 almacena #2563eb, que es oklch(0.546 0.215 262.9). Tres saltos, cada uno una decisión separable. La misma forma se sostiene fuera del color: gap-section lee {spacing.7}, que almacena 64px.

Hacia arriba, desde un valor: #2563eb se almacena exactamente una vez, en brand-600. Un solo rol semántico apunta a él: accent. Pregunta qué consume accent y tienes el radio de impacto completo de cambiar el color de marca: el botón, los enlaces, el estado activo de navegación — un conjunto finito y enumerable, en lugar de «donde sea que se pegara el hex».

Abre la vista de rastreo en Scale Composer: las rampas primitivas y las escalas a un lado, los roles semánticos apuntando hacia ellas, y la cadena de cualquier rol legible salto a salto hasta el valor almacenado.

Ahora la prueba del rediseño, la demostración del sistema por capas: vuelve a derivar la paleta desde un color semilla verde azulado. brand-600 conserva su nombre y cambia su valor almacenado. accent sigue diciendo {color.brand.600} — como afirmación, queda intacta y sigue siendo verdadera. button.background sigue diciendo {semantic.accent}. El cambio ocurrió en una sola capa, y las capas por encima no se movieron. Ese es el rediseño de tres semanas reducido a su tamaño honesto: una edición y una revisión.

¿Cuándo es honesto saltarse una capa?

La capa de componente, a menudo. Un producto pequeño con una semántica disciplinada rara vez tiene casos de desvinculación, y los tokens de componente creados antes de que haga falta son indirección sin sentido — button-bg → accent → brand-600, tres nombres para un valor que nunca varía de forma independiente, multiplicados por toda una biblioteca de componentes hasta que nadie puede navegar el conjunto. La capa se gana su lugar a escala de sistema de diseño, cuando aparecen excepciones reales — una opción por defecto razonable es introducir cada token de componente junto con la excepción que lo justifica, no antes.

La capa semántica es la que hay que conservar incluso cuando el producto es pequeño. Solo primitivos significa que los componentes fosilizan suposiciones (brand-600 significando «color de botón» en cien lugares), que es la historia del inicio con mejores nombres. Primitivos más semántica es el mínimo honesto para un sistema que espera sobrevivir a un rediseño de marca o hacer crecer un tema oscuro.

Haz tú mismo la prueba del rediseño

El modelo de capas es más fácil de creer después de ver un cambio detenerse en una frontera. Cambia el color semilla y observa cómo funcionan las capas: la rampa primitiva se vuelve a derivar, los roles semánticos se reapuntan automáticamente y conservan sus nombres, y el rastreo desde el botón hacia abajo sigue resolviéndose — las mismas afirmaciones, respuestas nuevas, sin buscar-y-reemplazar.