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

[Canonical HTML page](https://gradiently.design/es/guide/design-tokens)

Un color de marca que vive en cuarenta archivos acabará desviándose. Un token vive en un solo sitio y todas las plataformas lo leen de ahí. Así se estructuran los design tokens, se nombran para que duren y llegan al código y al diseño.

## The short version

- Los design tokens son valores con nombre e independientes de la plataforma para decisiones de diseño como colores, familias tipográficas, tamaños, espaciado, radios, sombras y tiempos de animación.
- La mayoría de los sistemas de tokens usan tres niveles: los tokens primitivos guardan valores en bruto, los semánticos describen un propósito y los de componente aplican propósitos a piezas concretas.
- El formato del W3C Design Tokens Community Group guarda los tokens en JSON con las propiedades $value y $type y hace referencia a otros tokens con llaves.
- Herramientas como Style Dictionary transforman un único archivo de tokens en propiedades personalizadas de CSS, JavaScript y recursos de iOS y Android.
- El modo oscuro y las marcas múltiples se reducen a cambiar los valores que hay detrás de los tokens semánticos, mientras los componentes no cambian.

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](https://www.w3.org/community/design-tokens/) los escribe en JSON, con propiedades que empiezan por el símbolo del dólar para que no choquen con los nombres de grupo.

```json
{
  "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 en el formato del grupo comunitario. Los grupos se anidan libremente; la ruta, como color.violet.700, pasa a ser el nombre del token.

- color.violet.100: #ede9fe
- color.violet.500: #8b5cf6
- color.violet.700: #6d28d9
- color.violet.900: #4c1d95
- color.ink: #14121f
- color.paper: #faf8ff

Los tokens de color de arriba como muestras. Son ingredientes en bruto: todavía nada dice cuál es un botón o un titular.

## 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.

| Nivel | Nombre de ejemplo | Valor | Cambia cuando |
| --- | --- | --- | --- |
| Primitivo | `color.violet.700` | `#6d28d9` | Se rediseña la paleta |
| Semántico | `color.action.primary` | `{color.violet.700}` | Una función pasa a otro color |
| Semántico | `color.text.default` | `{color.ink}` | Modo oscuro, una marca nueva |
| Componente | `button.primary.background` | `{color.action.primary}` | Un componente necesita una excepción |

Las referencias entre llaves son alias. Cambia color.violet.700 y todos los tokens que apuntan a él lo siguen.

```json
{
  "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}" }
    }
  }
}
```

Los tokens semánticos describen para qué sirve un color. Es la capa en la que deberían hablar diseñadores e ingenieros.

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.

### Nombres que envejecen mal

- `color.purple` usado para botones
- `text.dark`, que es claro en modo oscuro
- `spacing.16` usado como regla de maquetación
- `blue2`, `blueNew`, `blueFinal`
- `hero.gradient.lisa` con el nombre de una persona

### Nombres que duran

- `color.action.primary`
- `color.text.default`
- `space.section` apuntando a `{space.16}`
- Una escala numerada como `blue.100` a `blue.900`
- `gradient.hero` con sus paradas como tokens

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](https://gradiently.design/es/guide/brand-style-guide). 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.

```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;
}
```

Resultado generado. Los alias se convierten en referencias var(), así que la capa semántica llega hasta el navegador. Mira [variables CSS para temas](https://gradiently.design/es/guide/css-custom-properties-theming).

Si usas Tailwind v4, el bloque `@theme` ya es una capa de tokens: cada variable `--color-*` se convierte en utilidades. [Colores de Tailwind](https://gradiently.design/es/guide/tailwind-colors) 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.

```css
@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;
}
```

Dos sobrescrituras, ningún componente editado. Los degradados también merecen sus propios valores oscuros; [degradados en modo oscuro](https://gradiently.design/es/guide/dark-mode-gradients) explica cómo ajustarlos.

> **Tokens en las herramientas de diseño** Las Variables de Figma admiten colecciones y modos, que encajan muy bien con tokens primitivos y semánticos y con temas claro y oscuro. Mantén el archivo de tokens como fuente y sincroniza hacia la herramienta de diseño, no al revés, o en un mes no coincidirán.

## Implantar design tokens

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. **Define los primitivos** Redúcelos a escalas claras. Construir las escalas de color en OKLCH mantiene los pasos uniformes; mira [OKLCH explicado](https://gradiently.design/es/guide/oklch-explained).
3. **Añade la capa semántica** Nombra funciones: texto, superficie, borde, acción, feedback. Apunta cada una a un primitivo.
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. **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](https://gradiently.design/es/guide/brand-consistency) cubre el hábito en general.

## FAQ

### ¿Qué son los design tokens?

Valores con nombre para decisiones de diseño como colores, fuentes, espaciado, radios y movimiento, guardados en un archivo independiente de la plataforma y transformados en CSS, código de apps y variables de herramientas de diseño.

### ¿Qué diferencia hay entre tokens primitivos y semánticos?

Los tokens primitivos guardan valores en bruto, como `color.violet.700`. Los semánticos describen un propósito, como `color.action.primary`, y apuntan a un primitivo.

### ¿Los design tokens son lo mismo que las variables CSS?

No. Los tokens son la fuente, guardada en un formato neutro como JSON; las propiedades personalizadas de CSS son uno de los resultados que se generan a partir de ellos, junto a los de otras plataformas.

### ¿Existe un formato estándar para los design tokens?

El W3C Design Tokens Community Group publica un formato JSON con $value, $type y alias entre llaves, que herramientas como Style Dictionary pueden leer.

### ¿Cómo gestionan los design tokens el modo oscuro?

Los componentes leen tokens semánticos, y un tema oscuro aporta otros valores para esos tokens, así que los componentes no necesitan cambios.