Nuestro sistema de design tokens: cómo unificamos diseño y código

Un botón rojo. Parece trivial. Pero si ese rojo vive como #FF4B69 hardcodeado en 40 componentes, en 3 repos, y en 12 frames de Figma, ya tenés un problema. Cambiarlo va a doler.

Los design tokens resuelven eso. Son variables con significado que viven en un solo lugar y se propagan a todos los demás. El contrato entre diseño y código.

Nuestra convención: 3 capas

Después de romper varios sistemas, llegamos a una estructura que funciona:

1. Primitive tokens — valores crudos, sin contexto.

--color-red-500: #FF4B69;
--space-4: 1rem;
--radius-md: 8px;

2. Semantic tokens — primitives con intención.

--color-brand-primary: var(--color-red-500);
--color-surface-danger: var(--color-red-500);
--space-section-gap: var(--space-4);

3. Component tokens — semantics aplicados a un componente específico.

--button-primary-bg: var(--color-brand-primary);
--button-primary-radius: var(--radius-md);

¿Por qué tres capas? Porque cambiar el rojo de marca (capa 2) no debería obligarte a tocar los 40 componentes que lo usan. Y porque los primitives son neutrales — no saben si son para errores, marca, o un botón de CTA.

Figma → CSS: la parte aburrida pero crítica

Usamos Tokens Studio en Figma, que exporta a JSON. Después, Style Dictionary transforma ese JSON a CSS custom properties, tokens para Tailwind, y constantes TypeScript.

El workflow:

1. Diseñador ajusta un token en Figma.
2. PR automático a un repo de tokens.
3. Style Dictionary genera los assets.
4. El design system publica una nueva versión.
5. Los consumidores actualizan la dependencia.

No es glamoroso. Pero es auditable, versionado, y reversible. Que es exactamente lo que un sistema maduro necesita.

Los errores que cometimos

• Empezar con component tokens primero. Sin capa semántica, cada cambio era una refactorización masiva.
• Nombres basados en el look, no en la función: --color-blue-button envejece mal. Cuando el botón deja de ser azul, el nombre miente.
• No documentar el “por qué”: cada token semántico tiene un comentario explicando cuándo usarlo. Sin eso, nadie sabe si elegir --color-surface-danger o --color-text-error.

La conclusión

Un sistema de tokens no es un archivo de variables. Es una disciplina compartida entre diseño y desarrollo. Si tu equipo no habla el mismo idioma, los tokens no lo van a arreglar. Pero si lo habla, los tokens lo hacen escalable.