Arquitectura de Tokens (Global vs Semántico vs Componente)

Descubre cómo estructurar una arquitectura de tokens de diseño robusta utilizando el modelo de tres capas (Global, Semántico y Componente) para crear sistemas de diseño escalables y mantenibles.

info Definición Rápida
La arquitectura de tokens de diseño es la estructura lógica que organiza las decisiones de diseño (colores, tipografía, espaciado) en capas de abstracción. Un modelo bien diseñado permite cambiar la apariencia de todo un producto en minutos, garantizando coherencia y escalabilidad entre diseño y código.

¿Qué es la Arquitectura de Tokens?

Imagina que estás construyendo una ciudad. No quieres tener que pintar cada ladrillo de cada casa individualmente. En su lugar, defines una “paleta de materiales” (tokens globales), decides que todos los edificios públicos serán de “color institucional” (tokens semánticos) y finalmente aplicas ese color a la “puerta principal del ayuntamiento” (tokens de componente).

Esta jerarquía es lo que llamamos arquitectura de tokens. Su objetivo principal es separar el valor (el color azul #007bff) del significado (este es el color de acción principal).

Las 3 Capas Fundamentales

Para que un sistema de diseño sea escalable, se recomienda seguir el modelo de tres niveles:

1. Tokens Globales (Primitivos)

Son la base de todo el sistema. Almacenan valores brutos sin una intención específica de uso.

  • Nombramiento: Basado en el valor (ej. blue-500, space-16, font-size-large).
  • Función: Definen las opciones disponibles en la paleta del sistema. No deben usarse directamente en los componentes, ya que si cambias el valor de blue-500, podrías romper la coherencia en lugares inesperados.

2. Tokens Semánticos (Alias)

Es la capa más importante. Estos tokens referencian a los globales pero les añaden un contexto o intención de uso.

  • Nombramiento: Basado en la función (ej. color-background-primary, color-text-error, space-inset-medium).
  • Función: Permiten crear temas (como el Modo Oscuro). Por ejemplo, el token color-bg-surface puede apuntar a white en modo claro y a grey-900 en modo oscuro. El componente no sabe qué color es, solo sabe que es su “color de superficie”.

3. Tokens de Componente (Específicos)

Son la capa de especialización final. Referencian a los tokens semánticos (o a veces directamente a los globales) para un componente específico.

  • Nombramiento: Incluye el nombre del componente y la prop (ej. button-primary-background, input-border-color-focus).
  • Función: Sirven para hacer ajustes finos en un componente sin afectar al resto del sistema. Proporcionan el máximo nivel de control.

Beneficios para el Equipo

  • Escalabilidad: Añadir un nuevo tema (ej. una versión de marca blanca) es cuestión de remapear los tokens semánticos.
  • Mantenibilidad: Reduce drásticamente la deuda técnica. No hay valores “hardcoded” en el código ni en el diseño.
  • Comunicación: Diseñadores y desarrolladores hablan el mismo idioma. Ya no dicen “usa el azul clarito”, dicen “usa action-primary-hover”.

Consejos de Mentor

  • No te saltes capas: Es tentador usar tokens globales directamente para ahorrar tiempo, pero te arrepentirás cuando el sistema crezca.
  • Mantén los nombres agnósticos: Evita nombres como color-text-red. Si mañana ese texto debe ser naranja, el nombre dejará de tener sentido. Usa color-text-danger.
  • Automatiza la exportación: Utiliza herramientas como Style Dictionary para transformar tu JSON de tokens en formatos útiles para web, iOS y Android.
  • Documenta el “por qué”: En tu sistema de diseño, indica siempre cuándo debe usarse cada token semántico para evitar confusiones.

Recursos y Herramientas

  • Style Dictionary (Amazon): La herramienta estándar para transformar tokens.
  • Token Studio (Plugin de Figma): Para gestionar tokens directamente en tu lienzo de diseño.
  • W3C Design Tokens Community Group: El estándar en desarrollo para el formato de tokens.
  • Libros: Design Systems de Alla Kholmatova.