Design Tokens & Theming Systems

Un sistema de tokens robusto opera en tres capas jerarquizadas. Los tokens primitivos (referencia) almacenan valores brutos sin contexto, como un hex. Los tokens semánticos (alias) mapean esos valores a roles de UI con significado. Los tokens de componente son sobreescrituras específicas de un componente. Esta separación permite que un cambio de marca se propague desde un solo punto sin tocar el código de los componentes: cambias el primitivo y la cascada llega sola hasta el botón.

Un token nombrado por su valor literal (color-blue-600) crea una mentira en el codebase en el instante en que ese valor cambia. El nombre debe comunicar proposito, contexto e intención: no el color, tamaño ni peso concreto. Cuando la marca pasa de azul a indigo, el nombre semántico color-action-primary sigue siendo verdadero y solo se reapunta la capa primitiva. Incluye solo los niveles necesarios para distinguir la intención, sin sobre-especificar.

Soportar light, dark y marcas no requiere duplicar componentes ni crear tokens por tema (button-dark-background, button-light-background). Basta con un archivo de tokens semánticos por tema, todos exportando exactamente los mismos nombres apuntando a primitivos distintos. El código de los componentes nunca cambia: solo se carga otro mapa semántico-a-primitivo. La correspondencia entre temas es 1:1 por nombre.

Un sistema completo debe tokenizar las seis dimensiones de la UI: color, tipografía, espaciado, radii, sombra y motion. Limitar los tokens al color deja decisiones hardcodeadas dispersas por los componentes, lo que imposibilita el theming sistemico y los cambios de escala por plataforma. Cada categoría usa una taxonomia consistente (space/4, radius/md, motion/duration/fast) en lugar de nombres ad-hoc como bigPadding o myFont.

El W3C Design Tokens Community Group publico la versión estable 2025.10 el 28 de octubre de 2025. El estandar define la estructura JSON con las propiedades $value, $type, $description, $deprecated y $extensions, y referencias entre tokens con notación de llaves {group.token}. Adoptar DTCG da portabilidad entre Figma, Tokens Studio, Style Dictionary, Sketch, Framer y Penpot desde una sola fuente de verdad.

Invertir colores (CSS filter: invert(1) o invertir el hex) destruye la coherencia perceptual y arruina imagenes, fotos y gráficos. Un #0070F3 invertido da #FF8F0C (naranja). El dark mode correcto mantiene los mismos nombres semánticos apuntando a primitivos distintos, elegidos por su luminosidad percibida (por ejemplo blue-600 desplaza a blue-700, no se invierte). El modelo de elevación también se invierte: las superficies más altas se aclaran en vez de proyectar sombra.

Un par de colores que cumple 4.5:1 en light mode puede fallar en dark mode si se reasignan los tokens sin reverificar el nuevo par. Cada tema debe tratarse como un sistema de color independiente y auditarse por completo: texto normal ≥ 4.5:1 (SC 1.4.3), texto grande y componentes ≥ 3:1 (SC 1.4.11). La nomenclatura semántica facilita la auditoria, porque el par (text-muted, surface-base) se verifica sistematicamente en todos los temas, idealmente en CI que bloquee PRs bajo el umbral.

Renombrar un token sin anunciarlo rompe en silencio a todos los consumidores. El flujo correcto marca el token con $deprecated: true en DTCG, mantiene el nombre antiguo un ciclo de release, documenta el reemplazo en la descripción, y provee un codemod automatizado para la migración. Ambos nombres coexisten un release; el siguiente elimina el antiguo. Style Dictionary v4 publica codemods de su propia migración como referencia de este patrón.