Design tokens explicados: del color en Figma a la variable en código

Hace un tiempo un cliente nos escribió un viernes por la tarde: había decidido ajustar el verde de su marca, un poco más profundo, y quería verlo en la web antes del lunes. En la versión anterior de su web, hecha años atrás, ese verde aparecía escrito a mano en más de cien sitios del código con cuatro valores ligeramente distintos. En la nueva, el cambio fue una línea: el valor de un token llamado color-brand-600. Los botones, los enlaces, los iconos activos y los fondos de sección se actualizaron solos, y el modo oscuro, que usa una variante más clara del mismo verde, también.

Eso son los design tokens: decisiones de diseño con nombre propio, guardadas en un solo sitio y usadas en todas partes. Suenan a herramienta de grandes empresas, y es verdad que nacieron ahí (el equipo de Salesforce popularizó el término a mediados de la década de 2010 con su sistema Lightning), pero la idea es útil en cualquier proyecto que tenga más de tres pantallas o que vaya a crecer.

Esta guía explica qué son, cómo se organizan, cómo se nombran y cómo viajan de un archivo de Figma a una variable en el código, con ejemplos que puedes adaptar.

01Qué es un design token

Un design token es un par nombre-valor que representa una decisión de diseño. El valor puede ser un color, una medida, una tipografía, una duración, una sombra. El nombre dice qué es y, sobre todo, para qué sirve.

• →color-text-primary → #1A1A1A
• →space-4 → 16px
• →radius-md → 8px
• →font-size-body → 1rem
• →duration-fast → 150ms

La gracia no está en el valor, que podría escribirse directamente, sino en el nombre. Cuando un diseñador elige el color de un texto en Figma, ya no escribe un código hexadecimal: elige color-text-primary. Cuando un desarrollador escribe el CSS de ese texto, usa la misma palabra. Diseño y código hablan el mismo idioma, y cualquier cambio de valor se propaga a todos los sitios donde se usa.

Clave: un design token convierte un valor suelto en una decisión con nombre. El valor puede cambiar mañana; el nombre, y el significado que transporta, permanecen.

Los tokens son la base de cualquier sistema de diseño: los componentes se construyen con tokens, y las pantallas con componentes.

02Las tres capas: primitivos, semánticos y de componente

La forma más extendida y más útil de organizar los tokens es en tres capas, donde cada una hace referencia a la anterior.

Capa 1: tokens primitivos

También llamados globales o de referencia. Son la paleta completa de valores disponibles, sin intención de uso. Responden a la pregunta «¿qué opciones tenemos?».

• →color-green-100 … color-green-900
• →color-neutral-0 … color-neutral-950
• →space-1 (4 px) … space-10 (128 px)
• →font-size-100 … font-size-900

Nadie debería usar un primitivo directamente en un componente. Son la materia prima.

Capa 2: tokens semánticos

También llamados alias. Asignan un significado a un primitivo. Responden a la pregunta «¿para qué se usa esto?».

• →color-action → {color-green-600}
• →color-text-primary → {color-neutral-900}
• →color-bg-surface → {color-neutral-0}
• →color-border-subtle → {color-neutral-200}
• →color-feedback-error → {color-red-600}

Esta es la capa que más se usa en el diseño y en el código, y la que permite los temas. El modo oscuro, por ejemplo, no cambia los primitivos: cambia a qué primitivo apunta cada semántico. En modo claro color-text-primary apunta a neutral-900; en oscuro, a neutral-50. Lo desarrollamos en modo oscuro bien diseñado.

Capa 3: tokens de componente

Opcionales. Asignan valores a partes concretas de un componente cuando necesita diferenciarse del uso semántico general.

• →button-primary-bg → {color-action}
• →button-primary-bg-hover → {color-action-hover}
• →card-padding → {space-5}
• →input-border-focus → {color-action}

En proyectos pequeños y medianos solemos prescindir de casi toda esta capa y dejar que los componentes usen directamente los semánticos. En productos grandes con varias marcas, en cambio, es la que da flexibilidad para ajustar un componente sin afectar a otros.

03Cómo nombrar los tokens

El nombre es la parte más difícil y la más importante. Un buen sistema de nombres se entiende sin documentación y aguanta el crecimiento. La estructura que más usamos va de lo general a lo particular:

categoría-propiedad-variante-estado

• →color-bg-surface
• →color-bg-surface-raised
• →color-text-secondary
• →color-border-input-focus
• →space-inset-md
• →font-weight-strong

Algunas reglas que nos ahorran discusiones:

1. 01Nombra por uso, no por aspecto, en la capa semántica. color-action envejece bien; color-green-button deja de tener sentido el día que el botón pasa a ser azul.
2. 02En los primitivos, usa escalas numéricas. green-100 a green-900 permite insertar tonos intermedios y se entiende el orden de un vistazo.
3. 03Elige un vocabulario y repítelo. Si usas bg para fondo, úsalo siempre, nunca background en unos y bg en otros.
4. 04Evita los tamaños ambiguos. sm, md, lg funcionan bien para radios o sombras; para espaciado, una escala numérica es más predecible.
5. 05Escribe en minúsculas y con guiones. Es lo más fácil de traducir a CSS, a JSON y a las convenciones de cada plataforma.

04El formato: tokens en JSON

Para que los tokens puedan viajar entre herramientas, conviene guardarlos en un formato neutro. El grupo comunitario de design tokens del W3C (Design Tokens Community Group) lleva años trabajando en una especificación común, y en octubre de 2025 publicó la primera versión estable de su formato. Su estructura usa propiedades con el prefijo $ para distinguir los metadatos de los nombres de grupo:

{
  "color": {
    "green": {
      "600": { "$type": "color", "$value": "#1F7A4D" },
      "700": { "$type": "color", "$value": "#17603C" }
    },
    "neutral": {
      "0": { "$type": "color", "$value": "#FFFFFF" },
      "900": { "$type": "color", "$value": "#1A1A1A" }
    },
    "action": { "$type": "color", "$value": "{color.green.600}" },
    "action-hover": { "$type": "color", "$value": "{color.green.700}" },
    "text-primary": { "$type": "color", "$value": "{color.neutral.900}" }
  },
  "space": {
    "4": { "$type": "dimension", "$value": { "value": 16, "unit": "px" } },
    "5": { "$type": "dimension", "$value": { "value": 24, "unit": "px" } }
  }
}

Las llaves {color.green.600} son referencias: el token action no repite el valor, apunta a otro token. Es lo que hace posible la estructura en capas.

05De Figma al código, paso a paso

Así es el recorrido completo que montamos en un proyecto con design tokens. Se puede simplificar mucho en proyectos pequeños, pero el esqueleto es este.

1. 01Definir los primitivos en Figma. Una colección de variables «Primitives» con la paleta completa, la escala de espaciado y los radios. Se marcan como ocultos para publicación, para que nadie los use directamente en los diseños.
2. 02Definir los semánticos. Otra colección «Semantic» cuyas variables apuntan a los primitivos. Si hay modo oscuro, esta colección tiene dos modos, «Light» y «Dark». Los detalles de variables y modos están en Figma a fondo: variables, modos y auto layout.
3. 03Diseñar los componentes con semánticos. Rellenos, bordes, textos y espacios de cada componente se asignan a variables, nunca a valores sueltos.
4. 04Exportar a JSON. Con el plugin Tokens Studio, con la API de variables de Figma o con un script propio. El resultado es un archivo como el del ejemplo anterior, que se guarda en el repositorio del proyecto.
5. 05Transformar con Style Dictionary. Esta herramienta de código abierto lee el JSON y genera los archivos de cada plataforma: variables CSS, un tema de Tailwind, constantes de Swift o recursos de Android.
6. 06Usar las variables en los componentes. El código de cada componente solo usa tokens semánticos.
7. 07Versionar y revisar. Cualquier cambio de token pasa por una revisión, como el resto del código, y se anota qué ha cambiado.

El resultado en CSS se parece a esto:

:root {
  --color-green-600: #1F7A4D;
  --color-green-700: #17603C;
  --color-neutral-0: #FFFFFF;
  --color-neutral-900: #1A1A1A;
  --color-action: var(--color-green-600);
  --color-action-hover: var(--color-green-700);
  --color-text-primary: var(--color-neutral-900);
  --color-bg-surface: var(--color-neutral-0);
  --space-4: 1rem;
  --space-5: 1.5rem;
  --radius-md: 0.5rem;
}
.button-primary {
  background: var(--color-action);
  border-radius: var(--radius-md);
  padding: 0.75rem var(--space-5);
}
.button-primary:hover {
  background: var(--color-action-hover);
}

06Qué tipos de decisiones se convierten en tokens

El color es el ejemplo más evidente, pero casi cualquier decisión repetida puede ser un token:

La escala de espaciado, por ejemplo, es un candidato perfecto: un sistema de 8 puntos convertido en tokens hace que cada distancia de la interfaz salga de la misma lista.

07Tokens que cuidan la accesibilidad

Una ventaja menos conocida de los tokens semánticos es que permiten garantizar el contraste una sola vez. Si cada token de texto se diseña pensando en el fondo sobre el que va a vivir, todas las combinaciones que se usen en la interfaz cumplirán por construcción.

Lo que hacemos en el estudio es definir los tokens por parejas: color-text-primary sobre color-bg-surface, color-on-action sobre color-action, color-text-secondary sobre color-bg-subtle. Para cada pareja comprobamos el contraste con las referencias de WCAG 2.2 (4,5:1 para texto normal, 3:1 para texto grande y para bordes o iconos que transmiten información) y lo anotamos en la documentación. Si mañana alguien ajusta un primitivo, basta con repasar las parejas afectadas.

El mismo principio sirve para el movimiento: un token duration-fast que se reduce a cero cuando la persona ha activado la preferencia de reducir animaciones en su sistema hace que todo el producto respete esa elección sin tocar componente por componente.

08Lo que hace que un sistema de tokens funcione en el tiempo

Montar los tokens es la parte fácil. Lo que les da valor es que sigan siendo útiles dentro de dos años. Esto es lo que mejor nos ha funcionado:

• →Una única fuente de verdad. Decidir dónde viven (en Figma, en el repositorio) y que todo lo demás se genere a partir de ahí.
• →Documentación breve y visual. Una página con cada token semántico, su muestra y una frase de uso. Mejor corta y al día que completa y desactualizada.
• →Pocos semánticos, bien pensados. Es más fácil añadir un token cuando se necesita que retirar uno que se usa en 40 sitios.
• →Retirada ordenada. Cuando un token deja de usarse, se marca como obsoleto, se indica cuál lo sustituye y se elimina en la siguiente versión.
• →Diseño y desarrollo en la misma conversación. Los tokens funcionan cuando ambos equipos los sienten como suyos. Revisar juntos los cambios es la mejor garantía. En la guía sobre handoff de diseño a desarrollo contamos cómo organizar esa colaboración.

09Ejemplo resuelto: una segunda marca con los mismos componentes

Un grupo hostelero con el que trabajamos tenía dos restaurantes con identidades distintas que compartían sistema de reservas. En lugar de construir dos webs, construimos una con dos temas:

1. 01Primitivos comunes: escala de neutros, espaciado, radios y tipografías de las dos marcas.
2. 02Primitivos de cada marca: la gama de terracotas de un restaurante y la de azules del otro.
3. 03Semánticos con dos modos: «Marca A» y «Marca B». color-action apunta a terracotta-600 en uno y a blue-700 en otro; font-family-heading cambia de una serif a una sans geométrica.
4. 04Componentes únicos: botones, calendario, tarjetas de menú y formulario de reserva usan solo semánticos.

Cada web se ve completamente propia y el mantenimiento es uno solo. Cuando se mejoró el calendario de reservas, las dos marcas lo recibieron el mismo día.

Los design tokens son una manera de cuidar la coherencia de una marca en digital sin depender de la memoria de nadie. En SIMA los definimos desde el inicio en cada proyecto de desarrollo web y apps, con la misma estructura en Figma y en el código, para que la web pueda crecer y cambiar sin perder su identidad. Si quieres poner orden en el sistema visual de tu producto, escríbenos y lo vemos juntos.