Design tokens: una sola fuente de verdad para color y tipografía

Los design tokens son valores con nombre para cada decisión de diseño que una marca repite: colores, tipografías, tamaños de letra, espaciado, radios de esquina, sombras y tiempos de animación. En lugar de escribir #5b21b6 en una hoja de estilos, un archivo de Figma y una app de iOS, defines color.brand.700 una vez, en un solo archivo, y generas a partir de él el formato de cada plataforma. Cambias el token y todos los productos se actualizan a la vez. Esa única fuente de verdad es todo el sentido.

Cómo es un design token

Un token tiene un nombre, un valor y un tipo. El formato que publica el W3C Design Tokens Community Group los escribe en JSON, con propiedades que empiezan por el símbolo del dólar para que no choquen con los nombres de grupo.

{
  "color": {
    "violet": {
      "100": { "$type": "color", "$value": "#ede9fe" },
      "500": { "$type": "color", "$value": "#8b5cf6" },
      "700": { "$type": "color", "$value": "#6d28d9" },
      "900": { "$type": "color", "$value": "#4c1d95" }
    },
    "ink": { "$type": "color", "$value": "#14121f" },
    "paper": { "$type": "color", "$value": "#faf8ff" }
  },
  "font": {
    "heading": { "$type": "fontFamily", "$value": ["Fraunces", "Georgia", "serif"] },
    "body": { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] }
  },
  "radius": {
    "control": { "$type": "dimension", "$value": { "value": 10, "unit": "px" } }
  },
  "duration": {
    "quick": { "$type": "duration", "$value": { "value": 160, "unit": "ms" } }
  }
}

Tokens primitivos, semánticos y de componente

Una lista plana de colores es una paleta, no un sistema. La estructura que aguanta años tiene tres niveles, y cada uno hace referencia al de abajo. Los componentes nunca tocan valores en bruto; piden un propósito.

{
  "color": {
    "action": {
      "primary": { "$type": "color", "$value": "{color.violet.700}" },
      "primary-hover": { "$type": "color", "$value": "{color.violet.900}" }
    },
    "text": {
      "default": { "$type": "color", "$value": "{color.ink}" },
      "on-action": { "$type": "color", "$value": "{color.paper}" }
    },
    "surface": {
      "page": { "$type": "color", "$value": "{color.paper}" },
      "tint": { "$type": "color", "$value": "{color.violet.100}" }
    }
  }
}

Muchos equipos se quedan en dos niveles, primitivo y semántico, y añaden tokens de componente solo donde un componente es realmente distinto. Así el archivo sigue siendo lo bastante pequeño para entenderlo.

Nombrar los design tokens para que duren

Los nombres sobreviven a los valores. Un token llamado color.purple se rompe el día que la marca pasa a verde azulado; uno llamado color.action.primary lo aguanta. Nombra los tokens semánticos por su función y deja que los nombres primitivos describan el valor.

Elige un patrón, como categoría, luego función, luego variante y luego estado, y déjalo por escrito en tu guía de estilo de marca. La coherencia en los nombres importa más que el patrón que elijas.

Del archivo de tokens a CSS y a las apps

El archivo de tokens no se publica tal cual. Un paso de compilación lo transforma en lo que necesita cada plataforma. Style Dictionary es la herramienta de código abierto más usada para esto, y otras leen el mismo formato. En la web, el resultado suele ser propiedades personalizadas de CSS.

:root {
  --color-violet-100: #ede9fe;
  --color-violet-700: #6d28d9;
  --color-violet-900: #4c1d95;
  --color-ink: #14121f;
  --color-paper: #faf8ff;

  --color-action-primary: var(--color-violet-700);
  --color-text-default: var(--color-ink);
  --color-surface-page: var(--color-paper);

  --font-heading: Fraunces, Georgia, serif;
  --radius-control: 10px;
  --duration-quick: 160ms;
}

.button {
  background: var(--color-action-primary);
  color: var(--color-paper);
  border-radius: var(--radius-control);
  transition: background var(--duration-quick) ease;
}

Si usas Tailwind v4, el bloque @theme ya es una capa de tokens: cada variable --color-* se convierte en utilidades. Colores de Tailwind muestra cómo conectar ahí una escala de tokens. El mismo archivo puede generar también constantes de Swift y recursos de Android, y ahí es donde los tokens se amortizan en equipos multiplataforma.

Modo oscuro y varias marcas

Como los componentes solo leen tokens semánticos, un tema no es más que otro conjunto de valores para esa capa. El modo oscuro redefine color.text.default y color.surface.page; una segunda marca redefine color.action.primary. En los componentes no cambia nada.

@media (prefers-color-scheme: dark) {
  :root {
    --color-text-default: #e9e5f5;
    --color-surface-page: #0b0a14;
    --color-action-primary: var(--color-violet-500);
  }
}

[data-brand="harbour"] {
  --color-action-primary: #0f766e;
}

Implantar design tokens

1. 1

   Audita lo que existe

   Reúne cada color, tamaño de letra y valor de espaciado en uso. Cuenta con duplicados que difieren en un solo dígito hex.

2. 2

   Define los primitivos

   Redúcelos a escalas claras. Construir las escalas de color en OKLCH mantiene los pasos uniformes; mira OKLCH explicado.

3. 3

   Añade la capa semántica

   Nombra funciones: texto, superficie, borde, acción, feedback. Apunta cada una a un primitivo.

4. 4

   Automatiza la compilación

   Genera el CSS y los recursos de las apps a partir del archivo en tu compilación, nunca a mano.

5. 5

   Protégelo

   Usa un linter que detecte valores hex en bruto en los componentes, para que el código nuevo use tokens desde el primer día.

Los tokens mantienen coherente el producto, pero las marcas también se desvían en los gráficos que se hacen fuera de él: publicaciones, presentaciones, banners. Un kit de marca de Gradiently guarda las mismas decisiones, tus paletas de color, fuentes de títulos y texto, logos y tono, para que los diseños hechos en el Studio encajen. Y como Gradiently funciona dentro de ChatGPT, Claude y otros asistentes compatibles con servidores MCP remotos, un asistente con una clave de API limitada puede crear diseños fieles a la marca desde el mismo espacio de trabajo. Coherencia de marca cubre el hábito en general.