Color semántico frente a color bruto
Un design token de color bruto 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. Así, los componentes pueden ignorar los tonos literales de la marca. Un botón con el estilo bg-primary text-primary-foreground funciona con verde salvia, rosa intenso o un tema oscuro, porque el rol permanece fijo mientras que su valor cambia.
Este es el modelo que popularizó shadcn/ui y sobre el cual se construye el temizado de Tailwind. Con los tokens semánticos, el cambio de tema de una aplicación puede limitarse a un único bloque :root. Las clases hardcodeadas como bg-gray-900 y text-white convierten ese mismo cambio en una búsqueda exhaustiva por todo el código base.
La regla de emparejamiento de foreground
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. Use --primary-foreground sobre --primary en lugar de esperar que el foreground predeterminado tenga suficiente contraste. Cada pareja debe verificarse en ambos modos.
Los 28 roles que necesita un sistema completo
Una paleta mínima de tres colores deja 25 decisiones sin definir: estados de hover, texto atenuado, bordes, anillos de enfoque, series de gráficos, modo oscuro. Un sistema completo los nombra todos. Los kits de Identity Forge definen estos 28 roles, agrupados por su función, para modo 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 resaltado. - Sutiles y neutros:
muted/muted-foreground. Fondos tenues y texto secundario. - Estado:
destructive/destructive-foreground,success/success-foreground,warning/warning-foreground. Errores, confirmaciones y advertencias. - Formulario y enfoque:
border,input,ring. Divisores y contornos, superficies de campos de formulario y el indicador 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 predeterminada genérica.
Por qué son importantes cinco colores de gráfico
La visualización de datos es donde los sistemas insuficientemente especificados fallan de forma más visible: un tablero con tres colores de marca y un arcoíris aleatorio para su gráfico de barras. Definir chart-1…5 de antemano mantiene los gráficos dentro del mismo lenguaje visual que el resto de la aplicación.
Vea los roles en un kit real
A continuación se muestra el kit gratuito ambient-sage renderizado enteramente a partir de estos tokens. La fila de muestras es --primary, --secondary, --accent y los cinco roles de gráfico; el botón utiliza --primary con --primary-foreground; las superficies utilizan --background, --card y --muted. Nada de esto es un color hardcodeado:
Ambient Sage
Live renderRendered from the kit's actual tokens, fonts, and treatments
Typography
Plus Jakarta Sans
Color system
28 semantic roles, light + dark
Agent outputs
DESIGN.md, CSS, Tailwind, shadcn
Obtenga un conjunto completo de tokens
Puede definir los 28 roles a mano, pero es tedioso mantener el equilibrio y la accesibilidad entre el modo claro y el 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 integrar un conjunto completo en un proyecto de shadcn/ui:
npx shadcn add https://identityforge.io/r/ambient-sage.jsonLos tokens también constituyen la mitad de un DESIGN.md: los valores a los que hace referencia el brief escrito. Juntos, son lo que se le entrega a un agente de código para que su UI se mantenga coherente.
Preguntas frecuentes
¿Qué son los design tokens de color semánticos?
Variables de color nombradas por rol en lugar de por tono: --primary, --background, --muted-foreground en lugar de --blue-500. Los componentes se estilizan según el nombre del rol, por lo que cambiar de tema o pasar al modo oscuro nunca requiere editar los componentes.
¿Cuántos design tokens de color necesita un sistema de diseño?
Identity Forge utiliza 28 roles semánticos: superficies con sus foregrounds, roles de marca y atenuados, colores de estado, roles de formulario y cinco colores de gráfico. Cada rol tiene un valor para modo claro y otro para modo oscuro.
¿En qué consiste la convención -foreground?
La mayoría de los roles base se emparejan con un rol -foreground para el texto o los iconos situados sobre esa superficie: --primary con --primary-foreground. Este emparejamiento garantiza un contraste legible tanto en modo claro como oscuro sin necesidad de hacer estimaciones.
¿Cómo exporto un conjunto completo de tokens semánticos?
Cada kit de Identity Forge exporta sus 28 roles (claro + oscuro) como variables CSS, @theme de Tailwind v3/v4, un elemento del registro de shadcn o JSON de DTCG/W3C. Para shadcn/ui, el comando npx shadcn add https://identityforge.io/r/<slug>.json los instala directamente.