Tokens y componentes: el lenguaje compartido

Los tokens de diseño son el mecanismo que hace que las decisiones de diseño viajen sin fricción desde Figma hasta el código. Un componente bien definido con sus variantes y estados es lo que permite que desarrollo implemente sin adivinar.

Esta lección cubre los dos bloques técnicos del Design System: tokens y componentes.

Design Tokens

Un design token es una variable nombrada que almacena una decisión de diseño: un color, un tamaño, un tiempo de animación, un radio de borde.

En lugar de usar el valor directamente (#0066FF, 16px, 200ms), usas el nombre del token (color-brand-primary, spacing-4, motion-duration-medium). Ese nombre tiene el mismo valor en Figma y en el código.

Por qué importan los tokens

Sin tokens:

• El diseñador usa #0066FF en Figma.
• El desarrollador implementa #006FFF porque “cree que era ese azul”.
• Cuando cambia la marca y el color primario pasa a ser #0055EE, hay que actualizar cada instancia manualmente en ambos sitios.

Con tokens:

• Hay un único lugar donde color-brand-primary = #0066FF.
• Figma lee ese valor. El código también.
• Cuando cambia la marca, se actualiza el token y el cambio se propaga a todo el sistema.

Tipos de tokens

La convención más extendida distingue tres capas de tokens:

1. Tokens de referencia (primitivos)

Son los valores base del sistema, sin significado semántico. Son el vocabulario crudo.

color-blue-100: #E8F0FF
color-blue-200: #C5D8FF
color-blue-500: #0066FF
color-blue-700: #0044BB

size-1:  4px
size-2:  8px
size-4: 16px
size-8: 32px

Estos tokens no se usan directamente en componentes: son la materia prima de la siguiente capa.

2. Tokens semánticos (de decisión)

Son tokens que expresan intención, no solo valor. Referencian tokens primitivos.

color-action-primary:       → color-blue-500
color-action-primary-hover: → color-blue-700
color-feedback-error:       → color-red-500
color-feedback-success:     → color-green-500
color-surface-default:      → color-neutral-0
color-text-primary:         → color-neutral-900

spacing-component-padding-sm: → size-2
spacing-component-padding-md: → size-4
spacing-layout-section:       → size-8

Estos son los tokens que los componentes usan. Un botón primario usa color-action-primary, no color-blue-500.

3. Tokens de componente (opcionales)

Tokens específicos para un componente concreto. Solo tienen sentido en sistemas grandes donde necesitas sobreescribir comportamientos sin romper el sistema base.

button-primary-background:    → color-action-primary
button-primary-text:          → color-neutral-0
button-primary-radius:        → border-radius-md

Nomenclatura de tokens

Una buena convención de nombres es:

[categoria]-[escala-o-variante]-[propiedad]-[modificador]

Ejemplos:

color-brand-primary
color-brand-primary-hover
color-feedback-error
spacing-4
border-radius-md
motion-duration-fast
shadow-elevation-2

Lo más importante: el nombre debe expresar el propósito, no el valor. color-azul-oscuro es un nombre de valor. color-text-primary es un nombre de propósito.

Tokens en Figma y en código

En Figma se gestionan con:

• Variables nativas de Figma (desde Figma Variables, 2023+).
• Tokens Studio (plugin): permite gestionar tokens en JSON y sincronizarlos con un repositorio.

En código se procesan con herramientas como:

• Style Dictionary: transforma un JSON de tokens en variables CSS, Sass, JavaScript, Swift, etc.
• Theo: alternativa de Salesforce con enfoque similar.

El pipeline ideal: Figma → JSON de tokens → Style Dictionary → variables CSS y constantes JS/TS. Cualquier cambio en Figma se propaga al código automáticamente.

Componentes

Un componente en un Design System es un elemento de interfaz con anatomía definida, variantes documentadas, estados completos y reglas de uso claras.

Anatomía

La anatomía describe las partes que componen el componente y cómo se llaman. Esto crea el vocabulario que comparten diseño y desarrollo.

Ejemplo: anatomía de un botón

Button
├── Container (el elemento raíz, define tamaño y padding)
├── Leading Icon (opcional, a la izquierda del label)
├── Label (el texto)
└── Trailing Icon (opcional, a la derecha del label)

Nombrar las partes importa porque en el código el desarrollador va a preguntar “¿qué es el ícono de la izquierda?” y la respuesta correcta es “leading icon”, no “el iconito ese”.

Variantes

Las variantes son las versiones distintas de un componente que tienen un propósito diferente.

Ejemplo: variantes de un botón

Estados

Cada componente interactivo necesita todos sus estados diseñados. Omitirlos en Figma garantiza que desarrollo los improvise.

Estados mínimos para un botón:

• Default: aspecto en reposo.
• Hover: cuando el cursor está encima.
• Focus: cuando recibe foco por teclado (visible para accesibilidad).
• Active / Pressed: mientras se mantiene pulsado.
• Loading: cuando la acción está en progreso.
• Disabled: cuando no está disponible. Nunca como único feedback de “no puedes hacer esto”: el usuario también necesita saber por qué.

Estados adicionales para inputs:

• Filled: con texto introducido.
• Error: con mensaje de validación.
• Success: cuando la validación es correcta.
• Read-only: visible pero no editable.

Reglas de uso y anti-patrones

La documentación del componente debe incluir explícitamente:

Cuándo usar: “Usa el botón Primary para la acción más importante de la pantalla. No debe haber más de un botón Primary por vista.”

Cuándo no usar: “No uses Primary para acciones secundarias o de navegación. No lo uses en cadenas de pasos intermedios donde todavía no hay una decisión tomada.”

Anti-patrones (con ejemplo visual):

• Dos botones Primary en la misma vista → confusión sobre cuál es la acción principal.
• Botón Primary y Destructive del mismo tamaño en un diálogo de confirmación → el usuario puede ejecutar la acción equivocada.

¿Qué hemos aprendido?

• Los tokens conectan las decisiones de diseño con el código usando nombres con propósito, no valores.
• Hay tres capas de tokens: primitivos, semánticos y de componente.
• Los componentes necesitan anatomía nombrada, variantes justificadas y todos sus estados diseñados.
• Las reglas de uso y los anti-patrones son tan importantes como el componente en sí.

Siguiente paso

En la próxima lección veremos Patrones de interfaz: soluciones probadas para los problemas de diseño más recurrentes en productos digitales.