Arquitectura de tokens para múltiples temas y marcas

Un tema cambia el modo de color de una misma marca (las versiones clara y oscura de un mismo producto). Una marca es una identidad visual diferente: los mismos componentes del sistema de diseño se representan con distintos colores, tipografía y espaciado para atender a diferentes productos o clientes. Ambos utilizan la misma arquitectura de tokens, pero en distintos niveles de abstracción.

Los tokens primitivos son la paleta completa de valores sin procesar disponibles para el sistema. Incluyen cada nivel de color (color-blue-50 a color-blue-900), cada unidad de espaciado y cada tamaño de fuente. Los tokens primitivos nunca se utilizan directamente en los componentes; solo reciben referencias de los tokens semánticos. La paleta se define una vez y se comparte entre todos los temas y marcas.

Los tokens semánticos expresan una intención: color-background-page, color-text-primary, color-action-primary. Cada token semántico hace referencia a un valor de token primitivo adecuado para el tema actual. Los componentes se construyen exclusivamente con tokens semánticos. Esta es la capa en la que se aplica la tematización.

En el tema claro: color-background-page hace referencia a color-white, color-text-primary hace referencia a color-gray-900 y color-action-primary hace referencia a color-blue-500. Estas asignaciones se definen en un archivo de tokens específico del tema que sustituye la capa semántica para el contexto claro.

En el tema oscuro: color-background-page hace referencia a color-gray-950, color-text-primary hace referencia a color-gray-50 y color-action-primary hace referencia a color-blue-400 (ligeramente más claro para ofrecer contraste sobre fondos oscuros). Solo cambian las asignaciones semánticas; la paleta primitiva y todos los componentes permanecen sin cambios.

La marca A usa el azul como color principal (color-action-primary: {color-blue-500}). La marca B usa el verde (color-action-primary: {color-green-500}). El componente de botón lee var(--color-action-primary) y desconoce por completo qué marca está activa. Las anulaciones de marca solo cambian las asignaciones de tokens semánticos, nunca el código de los componentes.

Las propiedades personalizadas de CSS hacen que cambiar de tema en tiempo de ejecución sea sencillo. Almacene el tema actual en un atributo de datos: document.documentElement.setAttribute('data-theme', 'dark'). Las reglas CSS sustituyen los tokens semánticos dentro de [data-theme="dark"]. El navegador resuelve inmediatamente todas las referencias var() con los nuevos valores; no se necesita volver a renderizar con JavaScript.

Para marcas diferentes que se sirven mediante despliegues independientes, utilice la tematización durante la compilación: genere archivos CSS de tokens separados para cada marca con Style Dictionary y cargue el CSS de la marca correspondiente al iniciar la aplicación. Este enfoque es adecuado cuando la marca se determina durante el despliegue (dominios, subdominios o instancias de marca blanca diferentes), no durante la interacción del usuario.

Un sistema con múltiples marcas y temas requiere una matriz bidimensional: marca A clara, marca A oscura, marca B clara y marca B oscura. Las propiedades personalizadas de CSS gestionan esto de forma elegante mediante selectores anidados: [data-brand="a"][data-theme="dark"] sustituye los tokens semánticos para esa combinación específica. Cuatro combinaciones son cuatro bloques CSS, no cuatro bases de código.

A medida que el sistema de diseño evoluciona, se añaden, renombran o eliminan tokens. Versione los tokens en el mismo repositorio que el código. Al declarar obsoleto un token, conserve el nombre antiguo como un alias que apunte al nombre nuevo durante un ciclo de lanzamiento, añada un comentario de obsolescencia y actualice el código que lo consume. Coordine los cambios de tokens entre diseño e ingeniería mediante un registro de cambios estructurado.

La gobernanza define quién puede añadir o modificar tokens y qué proceso de revisión se requiere. Los tokens primitivos requieren la aprobación del equipo de diseño. Los tokens semánticos requieren una revisión tanto de diseño como de ingeniería. Los tokens de componente pueden ser gestionados por la persona responsable del componente. Sin esta gobernanza, aparecen tokens duplicados y la garantía de contar con una «fuente única de verdad» se debilita.

¿Por qué deberían los componentes hacer referencia a tokens semánticos en lugar de tokens primitivos?

Los temas cambian los modos de color dentro de una marca; las marcas son identidades visuales diferentes. Los tokens primitivos son la paleta sin procesar, mientras que los tokens semánticos expresan significado y permiten aplicar temas. Los componentes solo utilizan tokens semánticos. El modo oscuro y las sobrescrituras de marca cambian únicamente las asignaciones de tokens semánticos; los componentes no cambian. La tematización en tiempo de ejecución utiliza propiedades personalizadas de CSS con selectores [data-theme]; la creación de marca en tiempo de compilación genera CSS independiente para cada marca. La gobernanza y el versionado de tokens mantienen la coherencia del sistema a medida que evoluciona.