De Figma a producción: nuestro handoff entre diseño e ingeniería

TL;DR — El bucle de “eso no es lo que diseñé” es un problema de handoff, no de talento. Mátalo con tres cosas: design tokens compartidos (variables, no capturas de pantalla), un contrato de componente que ambos lados firmen, y Figma Code Connect para que el archivo de diseño apunte al código real. Luego revisa la UI construida contra el diseño antes de que alguien diga “listo”.

La mayor parte de la fricción entre diseño y código parece una discusión de gustos. Casi nunca lo es. Son dos equipos leyendo dos fuentes de verdad distintas —un frame de Figma y un árbol de React— y descubriendo la brecha solo después de que el build está “terminado”. Para entonces el arreglo es caro, la diseñadora se siente pasada por encima y el ingeniero se siente fiscalizado. Hemos entregado suficiente trabajo de clientes como para saber que el bucle se puede prevenir. Este es el ritual de handoff que de verdad usamos.

Los tokens son el contrato; las capturas, un rumor

La mayor fuente de desviación son los valores que viven en dos sitios. Una diseñadora pone el radio de un botón en 10px; un ingeniero lo calcula a ojo desde una captura y envía 8px. Multiplica eso por espaciado, color, tipografía y sombra y obtienes una UI que está cerca — que es el peor resultado posible, porque nadie puede señalar qué está mal.

La solución es dejar de transcribir valores a mano. Los design tokens viven una sola vez, como variables de Figma, y se exportan al código con los mismos nombres. No nombres parecidos. Los mismos nombres.

:root {
  --color-bg-surface: #0e0f12;
  --color-accent: #18b6a6;
  --space-3: 12px;
  --radius-md: 10px;
  --shadow-card: 0 1px 2px rgb(0 0 0 / 0.4);
}

Cuando la diseñadora cambia --radius-md, cambia en todas partes —en Figma y en el código— y no queda ningún valor sobre el que discutir. Color, espaciado, radio, escala tipográfica, elevación: todos tokens, todos compartidos, todos nombrados de forma idéntica en ambos lados.

Si un valor existe en el diseño pero no como token, todavía no es una decisión — es un accidente esperando a salir a producción.

Aquí está la parte de disciplina: nada de “números mágicos” en los componentes. Un margin-top: 13px puntual es un mal olor a ambos lados de la línea. Si es intencional, se gana un token. Si no, se borra.

Un componente es un contrato, no una imagen

Un componente de Figma y un componente de código deben coincidir en la misma superficie: las mismas variantes, los mismos estados, los mismos nombres de props. Cuando el diseño tiene un Button con variant (primary / secondary / ghost), size (sm / md / lg) y un estado disabled, el código debe exponer exactamente esas props — escritas igual.

Aquí es donde la disciplina de nombres paga su alquiler. Acordamos el vocabulario antes del build:

• Las variantes se mapean a props, no a copias. Tres variantes de botón son un componente con una prop variant, nunca tres componentes separados llamados ButtonPrimary, ButtonBlue, ButtonCTA.
• Los estados son explícitos. Hover, focus, disabled, loading — si el diseño no los dibujó, preguntamos antes de inventarlos.
• Los nombres reflejan el dominio, no el layout. card-product, no box-3. El nombre sobrevive al rediseño; la posición en píxeles no.

Cuando el contrato está escrito —aunque sea como un documento compartido breve— la conversación de “eso no es lo que diseñé” se mueve a antes de que exista el código, donde es barata.

Code Connect: que el archivo de diseño apunte al código real

Los tokens alinean los valores; el contrato de componente alinea la estructura. Figma Code Connect cierra la última brecha al enlazar cada componente de Figma con su implementación real, de modo que cuando un ingeniero inspecciona un componente en Figma ve tu código —el import real, las props reales— en lugar de markup genérico autogenerado.

import figma from "@figma/code-connect";
import { Button } from "../src/Button";

figma.connect(Button, "https://figma.com/file/…?node-id=…", {
  props: {
    variant: figma.enum("Variant", {
      Primary: "primary",
      Secondary: "secondary",
      Ghost: "ghost",
    }),
    label: figma.string("Label"),
  },
  example: ({ variant, label }) => <Button variant={variant}>{label}</Button>,
});

Ahora el handoff ya no es “aquí tienes un frame, averigua las props”. Es “aquí tienes el frame, y te dice exactamente qué componente y qué props usar”. Los ingenieros dejan de adivinar; las diseñadoras dejan de llevarse sorpresas. El mapeo vive en el repo junto al componente, así que se revisa y se versiona como todo lo demás.

Revisa la UI construida contra el diseño — a propósito

El último paso es el que los equipos se saltan cuando están cansados: una revisión deliberada, lado a lado, del build en ejecución contra el frame de Figma, antes de cerrar el ticket. No un vistazo de buena fe — una checklist.

Comparamos contra los tokens (¿los valores computados reales son los valores del token?), revisamos cada estado interactivo que especificaba el diseño y verificamos el comportamiento responsive en los breakpoints que el diseño definió. La diseñadora aprueba el build, no la descripción del PR. Si algo se desvió, se atrapa aquí —minutos de trabajo— en lugar de en una revisión de cliente tres semanas después.

Esta revisión es también donde el sistema mejora. Un recurrente “necesitábamos un estado que el diseño no tenía” se convierte en una nota en el contrato de componente. Una petición repetida de token se convierte en un token real. El ritual se alimenta a sí mismo.

La conclusión

El bucle de “eso no es lo que diseñé” no va de diseñadoras quisquillosas ni de ingenieros descuidados. Va de dos equipos confiando en dos fuentes de verdad distintas. Colápsalas en una: tokens como variables compartidas, un contrato de componente que ambos firmen, Code Connect cableando el archivo de diseño al código real, y una revisión de construido-contra-diseñado antes del “listo”. Haz eso y el handoff deja de ser una negociación — se convierte en una transferencia. El diseño sale a producción como se diseñó, a la primera, porque nunca hubo una segunda versión sobre la que discrepar.