Design tokens: qué son y cómo usarlos

Un design token es una variable con nombre que almacena un valor de diseño. En lugar de escribir #1A73E8 directamente en tu CSS o en Figma, defines un token llamado color-primary cuyo valor es #1A73E8. Ese token se convierte en el contrato entre diseño y desarrollo.

El concepto fue popularizado por Salesforce con su sistema Lightning Design System y desde entonces ha sido adoptado por prácticamente todos los sistemas de diseño relevantes. En 2024, el W3C Community Group publicó la especificación Design Tokens Format Module, estandarizando la forma de definirlos en JSON.

Los tokens se organizan en categorías que reflejan las distintas dimensiones del diseño visual. Cada categoría tiene sus propias convenciones y escalas.

La arquitectura de tokens más efectiva utiliza tres niveles. Los primitivos definen valores crudos (blue-600 = #1A73E8). Los semánticos asignan intención (color-primary = blue-600). Los tokens de componente aplican el valor a un contexto específico (button-bg-primary = color-primary).

Esta jerarquía permite cambiar un color de marca actualizando un solo token semántico en lugar de editar decenas de componentes. También es la clave para soportar dark mode: redefines los tokens semánticos para el tema oscuro y todos los componentes se adaptan automáticamente.

Un buen naming es la diferencia entre un sistema de tokens intuitivo y uno que nadie entiende. La convención más extendida usa kebab-case con una estructura de categoría-propiedad-variante-estado. Por ejemplo: color-text-primary, spacing-inline-md, shadow-elevation-high.

Evita nombres que describan el valor en lugar de la intención. color-blue-500 es un token primitivo válido, pero como token semántico es frágil: si la marca cambia de azul a verde, el nombre deja de tener sentido. Usa color-brand-primary en su lugar.

El flujo de trabajo con tokens implica definirlos en un formato centralizado (generalmente JSON o YAML), transformarlos a los formatos de cada plataforma (CSS custom properties, SCSS, Swift, Kotlin, XML) y sincronizarlos entre herramientas de diseño y código.

El verdadero poder de los design tokens emerge en proyectos que abarcan múltiples plataformas. Defines los tokens una vez en un formato neutro y los transformas automáticamente a CSS custom properties para la web, UIColor para iOS, ColorRes para Android, y cualquier otro formato que necesites.

Esto garantiza que un cambio de color de marca se propague a todas las plataformas con un solo commit. Sin tokens, ese mismo cambio requeriría coordinar actualizaciones manuales en cada equipo y cada repositorio, con el riesgo inherente de inconsistencias.

El error más habitual es crear demasiados tokens demasiado pronto. Un sistema con 500 tokens desde el primer día es ingobernable. Empieza con los tokens que cubren el 80% de los casos de uso y añade nuevos solo cuando haya una necesidad real y recurrente.

Otro error frecuente es no distinguir entre tokens primitivos y semánticos. Si los desarrolladores referencian directamente blue-500 en lugar de color-primary, pierdes la capacidad de hacer cambios globales. Establece esta regla desde el día uno y automatiza su cumplimiento con linting.