Tokens de color en CSS y Tailwind
· 3 min de lectura
Cómo nombrar y organizar las variables de color por rol, conectar el modo claro y oscuro en CSS y usar los mismos tokens en un tema de Tailwind v4.
Los valores hex escritos a mano y repartidos por una hoja de estilos son la razón principal de que cambiar colores sea tan penoso. Cambiar de marca, añadir el modo oscuro o corregir un problema de contraste se convierte en un buscar y reemplazar a lo largo de cientos de líneas. Los tokens de color, variables con nombre que describen para qué sirve un color, lo resuelven. Esta guía muestra cómo organizarlos en CSS puro y usar los mismos tokens en Tailwind.
Dos capas: primitivos y roles
Una configuración sólida separa qué colores hay de cómo se usan.
Los tokens primitivos son la paleta en bruto, nombrada por matiz y paso. Nunca aparecen directamente en los estilos de los componentes.
:root {
--blue-100: #E3E8FF;
--blue-500: #3D5AFE;
--blue-700: #2638C4;
--sand-50: #F7F5F0;
--ink-900: #1D2433;
}Los tokens semánticos (de rol) describen una función en la interfaz y apuntan a un primitivo o tienen un valor propio. Los componentes solo usan estos.
:root {
--color-bg: var(--sand-50);
--color-surface: #EFECE4;
--color-border: #DAD6CC;
--color-text: var(--ink-900);
--color-muted: #5C6475;
--color-primary: var(--blue-500);
--color-on-primary: #FFFFFF;
--color-accent: #C2410C;
}.button {
background: var(--color-primary);
color: var(--color-on-primary);
}
.card {
background: var(--color-surface);
border: 1px solid var(--color-border);
color: var(--color-text);
}Ahora el botón no sabe que es azul. Si la marca pasa al verde, cambias una línea. Si una comprobación de contraste falla, ajustas un token y todos los componentes lo siguen.
Nombra los tokens por su rol, no por su aspecto
Nombres como --light-gray o --brand-blue describen cómo se ve un color hoy. Dejan de ser ciertos en cuanto cambia el valor, y en modo oscuro --light-gray contendría un color oscuro. Los nombres de rol siguen siendo ciertos:
--color-bg,--color-surface,--color-borderpara la estructura.--color-texty--color-mutedpara el contenido.--color-primary,--color-accentpara el énfasis.--color-on-primary,--color-on-accentpara el texto que va sobre colores de relleno.- Roles de estado opcionales:
--color-success,--color-warning,--color-danger.
Mantén la lista corta. Una docena de tokens de rol cubre la mayoría de productos; añadir un token para cada componente devuelve el problema original.
El modo oscuro pasa a ser un conjunto de valores nuevos
Con tokens de rol, el modo oscuro no es una segunda hoja de estilos. Son los mismos nombres con otros valores. El patrón de abajo sigue el ajuste del sistema y aun así permite que un interruptor fuerce cualquiera de los dos temas con un atributo data-theme:
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
--color-bg: #14161F;
--color-surface: #1C1F2B;
--color-border: #2C3040;
--color-text: #E6E8EF;
--color-muted: #9AA1B2;
--color-primary: #8C9EFF;
--color-on-primary: #14161F;
--color-accent: #FB923C;
}
}
:root[data-theme="dark"] {
/* los mismos valores, para quien elige el modo oscuro a mano */
}Fíjate en que el principal oscuro es un azul más claro y su etiqueta es oscura. Los valores oscuros hay que elegirlos, no calcularlos invirtiendo; la guía del modo oscuro explica por qué.
Los navegadores modernos también admiten la función light-dark(), que mantiene los dos valores en una sola línea. Sigue la propiedad color-scheme, así que necesita esa declaración para funcionar:
:root {
color-scheme: light dark;
--color-bg: light-dark(#F7F5F0, #14161F);
--color-text: light-dark(#1D2433, #E6E8EF);
}Deriva los colores discretos
Las superficies y los bordes se pueden mezclar a partir del fondo y el texto en lugar de elegirlos a mano. color-mix() lo hace en CSS, y mezclar en OKLCH da pasos uniformes y naturales:
:root {
--color-surface: color-mix(in oklch, var(--color-bg) 94%, var(--color-text));
--color-border: color-mix(in oklch, var(--color-bg) 82%, var(--color-text));
}Como hacen referencia a otros tokens, se actualizan solos en modo oscuro. Comprueba que el borde llega a 3:1 si marca un campo u otro control.
Usar los tokens en Tailwind CSS v4
Tailwind v4 se configura en CSS. Cualquier variable --color-* declarada en @theme se convierte en un juego completo de utilidades (bg-*, text-*, border-*, etc.). Las utilidades generadas leen la variable en tiempo de ejecución (bg-primary pasa a ser background-color: var(--color-primary)), así que basta con sobrescribir la variable para el modo oscuro:
@import "tailwindcss";
/* los valores claros se convierten en utilidades: bg-bg, text-text, bg-primary ... */
@theme {
--color-bg: #F7F5F0;
--color-surface: #EFECE4;
--color-text: #1D2433;
--color-muted: #5C6475;
--color-primary: #3D5AFE;
--color-on-primary: #FFFFFF;
--color-accent: #C2410C;
}
/* los valores oscuros sobrescriben las mismas variables */
@media (prefers-color-scheme: dark) {
:root {
--color-bg: #14161F;
--color-text: #E6E8EF;
--color-primary: #8C9EFF;
--color-on-primary: #14161F;
/* ... */
}
}<button class="bg-primary text-on-primary">Save</button>
<p class="text-muted">Last edited 2 hours ago</p>No hacen falta variantes dark: en cada elemento: los tokens ya cambian, así que bg-primary es correcto en los dos temas.
Tailwind v3
En v3, asigna las mismas variables en el archivo de configuración:
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
bg: 'var(--color-bg)',
surface: 'var(--color-surface)',
text: 'var(--color-text)',
primary: 'var(--color-primary)',
accent: 'var(--color-accent)',
},
},
},
}Escribir los valores en OKLCH
El hex sirve para guardar colores, pero OKLCH es más fácil de entender cuando los editas. Sus tres canales son luminosidad, croma (saturación) y matiz, y la luminosidad se corresponde mucho con lo que ve el ojo. Para hacer una versión más oscura de un color de marca para texto, bajas L y dejas el resto igual: oklch(55% 0.2 265) pasa a ser oklch(42% 0.2 265). Todos los navegadores principales actuales admiten oklch().
Ahórrate escribirlo
Cada paleta de Colorset exporta exactamente esta estructura: tokens de rol para el modo claro y oscuro como variables CSS, un tema de Tailwind v4, una configuración de Tailwind v3, SCSS, JSON o design tokens, en HEX, RGB, HSL u OKLCH. Elige una combinación que te guste, abre Exportar y pega. El generador de escalas crea una escala primitiva 50–950 a partir de cualquier color si quieres construir tú la capa de primitivos.