Un token de color puro nombra el color en sí: --blue-500, --gray-900. Un token semántico nombra la función que cumple el color: --primary, --background, --muted-foreground. De este modo, los componentes pueden ignorar los matices literales de la marca. Un botón con el estilo bg-primary text-primary-foreground funcionará con verde salvia, rosa intenso o en un tema oscuro porque el rol permanece fijo mientras su valor cambia.

Este es el modelo que popularizó shadcn/ui y sobre el cual se construye la tematización de Tailwind. Con tokens semánticos, cambiar el tema de una aplicación puede limitarse a un solo bloque :root. Las clases fijas como bg-gray-900 y text-white convierten ese mismo cambio en una búsqueda exhaustiva por todo el código.

La mayoría de los roles base vienen con un rol -foreground emparejado para el texto o los iconos sobre esa superficie: --primary / --primary-foreground, --card / --card-foreground, --muted / --muted-foreground. Usa --primary-foreground sobre --primary en lugar de esperar que el foreground por defecto tenga suficiente contraste. Cada par debe verificarse igualmente en ambos modos.

Una paleta mínima de tres colores deja 25 decisiones sin definir: estados hover, texto atenuado, bordes, anillos de enfoque, series de gráficos, modo oscuro. Un sistema completo las nombra todas. Los kits de Identity Forge definen estos 28 roles, agrupados por su función, para los modos claro y oscuro:

• Superficies: background / foreground, card / card-foreground, popover / popover-foreground. La página, los paneles elevados y las capas flotantes, cada uno con su color de texto legible.
• Marca y énfasis: primary / primary-foreground, secondary / secondary-foreground, accent / accent-foreground. La acción principal, la de apoyo y el elemento destacado.
• Sutiles y neutros: muted / muted-foreground. Fondos atenuados y texto secundario.
• Estado: destructive / destructive-foreground, success / success-foreground, warning / warning-foreground. Errores, confirmaciones y advertencias.
• Formularios y enfoque: border, input, ring. Divisores y contornos, superficies de campos de formulario e indicadores de enfoque.
• Datos: chart-1, chart-2, chart-3, chart-4, chart-5. Cinco colores de serie distintos y alineados con la marca para que los gráficos no recurran a una paleta genérica por defecto.

A continuación se muestra el kit gratuito ambient-sage renderizado íntegramente con estos tokens. La fila de muestras es --primary, --secondary, --accent y los cinco roles de gráficos; el botón usa --primary con --primary-foreground; las superficies usan --background, --card y --muted. Nada aquí es un color fijo:

Puedes definir los 28 roles a mano, pero es tedioso mantener el equilibrio y la accesibilidad entre el modo claro y oscuro. Cada kit de Identity Forge los incluye completos en ambos modos, exportables como variables CSS, @theme de Tailwind v3/v4, un elemento del registro de shadcn o JSON de DTCG/W3C. La forma más rápida de añadir un conjunto completo a un proyecto shadcn/ui:

npx shadcn add https://identityforge.io/r/ambient-sage.json

Los tokens son también la mitad de un DESIGN.md: los valores a los que hace referencia el brief escrito. Juntos son lo que puedes darle a un agente de programación para que su interfaz sea coherente.