Design tokens explicados, con un conversor de JSON a CSS en vivo
Design tokens explicados
Design tokens explicados con ejemplos (JSON, CSS, Tailwind) | We.Inc
Qué son los design tokens, cómo los escribe el formato JSON del grupo comunitario del W3C y un conversor en vivo que convierte el JSON de tokens en variables CSS y en un bloque @theme de Tailwind v4.
Los design tokens son decisiones de diseño con nombre, como color.primary o space.md, guardadas como datos para que todas las plataformas lean los mismos valores. El formato del Design Tokens Community Group los escribe en JSON con $value y $type, y permite que un token apunte a otro con llaves. Después, las herramientas convierten ese JSON en variables CSS, temas de Tailwind o código de aplicación.
Niveles de tokens que usan la mayoría de los equipos
Nivel
Nombre de ejemplo
Contiene
Base (primitivo)
Un valor en bruto: un color, un tamaño o una fuente
Semántico (alias)
Un rol que apunta a un token base
Componente
Un rol limitado a un solo componente
La mayoría de las explicaciones se quedan en la definición. Pega o edita abajo un JSON de tokens en el formato del grupo comunitario y verás, mientras escribes, las propiedades personalizadas de CSS y el tema de Tailwind v4 que genera, con los alias resueltos como referencias var().
Edita el JSON de la izquierda. Los grupos pueden definir $type una sola vez para todos los tokens que contienen.
Para referenciar otro token, envuelve su ruta con puntos entre llaves, por ejemplo {color.blue-500}.
Consulta la pestaña CSS para ver las variables de :root, o la pestaña Tailwind para ver un bloque @theme.
Copia el resultado en tu hoja de estilos. Antes, corrige cualquier mensaje de error que aparezca bajo el editor.
Nombra los tokens semánticos por su función (text, surface, danger) y no por su aspecto (red, dark), para que un cambio de marca solo toque el nivel base.
Mantén los tokens base fuera de los componentes. Los componentes deben leer nombres semánticos para que el modo oscuro y los temas puedan cambiar los valores por debajo.
Guarda los tokens en un único archivo bajo control de versiones y genera desde él la salida de cada plataforma.
Usa la extensión recomendada .tokens o .tokens.json para que las herramientas reconozcan los archivos.
Preguntas frecuentes
¿Qué es un design token?
Un design token es un nombre asociado a un valor de diseño, por ejemplo color.text con un color casi negro. El código y los archivos de diseño usan el nombre, así que cambiar el valor en un solo sitio actualiza cada botón, página y aplicación que lo usa.
¿Existe un formato estándar para los design tokens?
Sí. El Design Tokens Community Group del W3C publicó el Format Module 2025.10 como informe final de grupo comunitario el 28 de octubre de 2025 y lo describe como estable. Es un informe de grupo comunitario, no una Recomendación del W3C.
¿Qué diferencia hay entre los design tokens y las variables CSS?
Los tokens son los datos de origen, independientes de cualquier plataforma. Las propiedades personalizadas de CSS son solo una salida. El mismo archivo de tokens puede generar también constantes de Swift, Android o JavaScript, algo que las variables CSS por sí solas no te dan.
¿Cómo funcionan los design tokens con Tailwind CSS?
En Tailwind v4 declaras las variables del tema dentro de @theme, como --color-primary. Tailwind crea a partir de ellas utilidades como bg-primary y además las emite como variables CSS normales en :root, así que tokens y utilidades se mantienen sincronizados.
¿Cómo se escriben los colores en el formato de tokens?
En el formato 2025.10, un valor de color es un objeto con un colorSpace, como srgb, y un array de componentes de 0 a 1, con alfa opcional. El conversor de esta página también acepta cadenas simples para que puedas pegar archivos de tokens antiguos.
Por qué los equipos adoptan tokens
Sin tokens, el azul de la marca vive como un código hexadecimal pegado en cientos de lugares entre el CSS, las apps móviles y los archivos de diseño. Cambiarlo exige un buscar y reemplazar que siempre se deja alguno.
Con tokens, ese azul tiene un nombre y un único hogar. Diseñadores y desarrolladores hablan de color.primary, y un paso de compilación escribe el valor en el formato propio de cada plataforma.
Cómo leer el formato JSON
Cualquier objeto con $value es un token; cualquier otro objeto es un grupo. Las propiedades que empiezan por el signo de dólar están reservadas por el formato: $value, $type, $description, $deprecated y $extensions.
La especificación define tipos simples como color, dimension, fontFamily, fontWeight, duration, cubicBezier y number, además de tipos compuestos como shadow, border, transition, typography, strokeStyle y gradient. Las dimensiones y duraciones son objetos con un valor numérico y una unidad.
De los tokens a un tema que funciona
Un sitio pequeño puede mantener los tokens directamente en CSS como propiedades personalizadas. En cuanto publicas en más de una plataforma, o diseñas en una herramienta que exporta tokens, genera el CSS desde JSON para tener una única fuente.
El modo oscuro pasa a ser un segundo conjunto de valores semánticos. Los colores base no cambian, y la capa semántica cambia a qué base apunta cada rol dentro de una media query de esquema oscuro o de un atributo data.
Tokens semánticos con un tema oscuro
Cambia los valores semánticos, conserva los valores base
La tarjeta solo lee --surface y --text. El bloque oscuro reasigna esos dos nombres y la tarjeta los sigue sin ningún cambio en sus propias reglas.
Un token compuesto
Token de sombra en el formato del grupo comunitario
Los tokens compuestos agrupan varios valores. Aquí el color es a su vez un alias, y los desplazamientos usan objetos de dimensión.
No se encontraron tokens. Un token es un objeto con la propiedad $value.
Todavía no es un JSON válido: {message}
Conversor de JSON de tokens a CSS
Edita el archivo de tokens y las variables CSS y el tema de Tailwind se actualizan mientras escribes. El archivo inicial se convierte en: