Hace tiempo que vengo optimizando el proceso de handoff entre diseño y desarrollo. He visto cómo pequeños desajustes en colores, tamaños o espaciados generan horas de re-trabajo y fricción en equipos pequeños. Por eso hoy quiero compartir una metodología práctica que uso: combinar Figma con variables CSS y design tokens para crear un handoff claro, escalable y que reduzca al mínimo las correcciones en desarrollo.

Por qué el handoff suele fallar

En muchos proyectos el diseño queda "congelado" en Figma y el desarrollo intenta replicarlo a base de inspección manual. Esto genera varios problemas habituales:

  • Colores declarados en texto (p. ej. "azul principal") sin valores claros ni grados.
  • Tamaños tipográficos aplicados de forma inconsistente (px, rem, scale diferente).
  • Espaciados y unidades que no encajan con el sistema de CSS del proyecto.
  • Dependencia en imágenes exportadas en lugar de componentes reutilizables.

    • El resultado: discrepancias visuales, inventario de estilos distinto y tiempo perdido en correcciones. La solución que propongo evita estos puntos conectando el diseño con el código mediante tokens y variables.

    Conceptos clave: tokens de diseño y variables CSS

    Antes de entrar en el flujo, aclaremos términos:

  • Design token: unidad de representación de una propiedad de diseño (color, tamaño, espaciado, sombra...) en formato neutral (JSON, YAML) para luego transformarlo a cualquier plataforma.
  • Variables CSS (custom properties): variables nativas en CSS (ej. --color-primary) que permiten centralizar valores y usarlos en cualquier lugar del CSS.
  • Figma Styles: estilos de color, tipografía y efectos que actúas como fuente de verdad en el archivo de diseño.

    • La idea es mapear los Figma Styles a tokens y esos tokens a variables CSS. Así diseño y desarrollo hablan el mismo lenguaje.

    Mi flujo paso a paso

    A continuación detallo el flujo que uso en mis proyectos. Lo he probado en startups y en proyectos freelance con equipos reducidos y siempre reduce retrabajo.

  • 1. Establecer el sistema de diseño en Figma

    • Antes de diseñar páginas, creo una librería con Figma Styles: colores (primarios, secundarios, neutrales), tipografías (familia, peso, tamaño base), elevaciones (sombras) y espaciados (scale 4px/8px). Evito nombres ambiguos; uso nomenclatura funcional como color-bg-primary, font-size-base, space-8.

  • 2. Exportar tokens desde Figma

    • Utilizo plugins como Figma Tokens o herramientas como Design Tokens de Amazon para exportar los estilos en JSON. Aquí defino la estructura jerárquica y las variables. Un ejemplo sencillo de JSON:

    tokenvalor
    color.primary#0f62fe
    font.baseInter, sans-serif
    size.spacing.88px
  • 3. Transformar tokens a variables CSS

    • Con herramientas como Style Dictionary (by Amazon) o Theo se transpilan los tokens JSON a formatos concretos: CSS variables, SCSS, Android XML, iOS plist, etc. Para la web genero algo similar a:

    <style>:root {  --color-primary: #0f62fe;  --font-base: "Inter, sans-serif";  --space-8: 8px;}</style>

    De esta manera el equipo de desarrollo solo importa un archivo CSS con todas las variables, que actúa como fuente verdadera.

  • 4. Documentar ejemplos y reglas de uso

    • Un error frecuente es asumir que todos saben cómo usar un token. Por eso creo una pequeña documentación (con Storybook o un archivo estático) que incluye:

  • Ejemplos de componentes con tokens aplicados.
  • Reglas de escalado tipográfico (ej. h1=2rem, h2=1.5rem).
  • Cómo combinar colores y cuándo usar variantes.

    • Esto evita debates durante la implementación.

  • 5. Integración continua del token pipeline

    • Si tu proyecto evoluciona, el token debe actualizarse de forma controlada. Yo configuro un pipeline básico: los tokens JSON se guardan en el repositorio (o en una rama de diseño), y cada vez que se actualizan se genera un PR que produce las variables CSS y actualiza Storybook. Así todo cambio queda registrado y revisable.

    Tips prácticos para evitar re-trabajo

    Algunos trucos que me han ahorrado tiempo:

  • No uses colores "sobre el fly". Crea variantes de color para estados (hover, active) y documenta el contraste.
  • Define una escala de espaciados. 4px o 8px como base evita inconsistencias entre padding, margin y grid.
  • Usa tokens semánticos además de tokens atómicos. Además de --color-primary, crea --color-brand, --color-success, que describen el propósito y permiten cambios globales sin romper componentes.
  • Implementa un archivo de referencia en el repositorio. Un CSS o un JSON central que el equipo importa reduce errores humanos.

    • Casos reales y errores comunes

    En un proyecto reciente cometimos el error de nombrar colores por su uso (p. ej. "header-bg") en lugar de por su rol. Al cambiar la paleta, hicimos refactors masivos. Aprendí que los tokens deben ser semánticos: color-surface, color-on-surface permiten re-tematizar sin buscar y reemplazar mil clases.

    Otro caso: la tipografía base se definía en px y los desarrolladores usaban rem. Solución: definir el root font-size y publicar ejemplos en rem en la documentación, además de un mapa de conversión (16px = 1rem). Esto evita textos demasiado grandes o pequeños en dispositivos.

    Herramientas que recomiendo

  • Figma + plugin Figma Tokens: para mantener tokens dentro del archivo de diseño.
  • Style Dictionary: para transformar tokens a CSS, SCSS, Android, iOS.
  • Storybook: para documentar componentes con los tokens aplicados.
  • Zeroheight o Notion: para documentación de estilos y guidelines accesibles al equipo.

    • Ejemplo conciso de implementación

    Imagina que defines en Figma un color primario y una escala de espaciados. Exportas tokens JSON y con Style Dictionary produces un archivo CSS con:

    :root {  --color-primary: #0f62fe;  --space-4: 4px;  --space-8: 8px;  --font-size-base: 1rem;}

    En los componentes usas:

    .btn {  background: var(--color-primary);  padding: var(--space-8) var(--space-16);  font-size: var(--font-size-base);}

    Si más tarde el diseñador ajusta el color, únicamente actualizas el token y el proyecto entero se adapta sin tocar cada componente.

    Si quieres, puedo compartir una plantilla JSON de tokens y un pipeline básico de Style Dictionary para que lo pruebes en tu proyecto. También puedo revisar tu Figma y proponer la estructura de tokens óptima según tus necesidades.