La queja habitual de los desarrolladores no es que los diseños sean feos, ni que lleguen tarde. Es que el archivo de diseño responde a las preguntas equivocadas. Un archivo de Figma describe pantallas; una base de código de React describe componentes con props y estados. Cuando el handoff entrega pantallas, el desarrollador tiene que hacer ingeniería inversa del modelo de componentes, y su conjetura no va a coincidir con la tuya.
En la mayoría de los proyectos, primero diseño y luego construyo yo mismo el front-end, lo que significa que sufro el coste de mis propios handoffs chapuceros unos dos días después. Todo lo que viene a continuación sale de ese bucle.
La verdadera brecha: pantallas frente a estados
Una pantalla es una combinación congelada de datos, viewport y estado de interacción. Un componente tiene que gestionarlas todas. Si el archivo muestra un panel de control con cuatro tarjetas de títulos de longitud ideal, el desarrollador aún tiene que decidir qué pasa con una tarjeta, con doce, con un título que se ajusta a tres líneas, mientras se cargan los datos y cuando la petición falla.
Esas decisiones se toman de todos modos. La única cuestión es si las toma un diseñador o si se las inventa a las seis de la tarde alguien que además está peleándose con un error de tipos. Cada estado sin resolver es un lugar donde el desarrollo se aparta del diseño, y ese desvío es lo que provoca la conversación sobre reconstruirlo.
Así que el entregable no es un conjunto de pantallas bonitas. Es un inventario de componentes más las pantallas que muestran esos componentes compuestos juntos.
Da a las propiedades de Figma la forma de las props de React
Las propiedades de componente de Figma y las props de React son la misma idea con distinta sintaxis. Un botón con la variante fijada en primary o ghost, el tamaño en sm o md, y propiedades booleanas para un icono inicial se traduce directamente en una interfaz de props. Nómbralas de forma idéntica y el mapeo es mecánico en lugar de interpretativo.
Evita las propiedades de variante que codifican dos cosas a la vez. Una variante llamada primary-large-icon hay que desglosarla antes de que pueda convertirse en código, y multiplica tu matriz de variantes. Tres propiedades independientes le ganan a una combinada siempre.
La misma disciplina se aplica a los nombres de capa dentro del componente. Slot, label, icon y container son nombres útiles. Frame 247 no. Un desarrollador que abre Dev Mode lee tu árbol de capas como un esbozo aproximado del DOM, así que un árbol ordenado es de verdad parte del entregable.
Cuando un componente anida otro componente (una tarjeta que contiene un botón), usa un instance swap o una instancia anidada en lugar de volver a dibujarlo. El anidamiento en el archivo es lo que le dice al desarrollador que la composición es intencionada.
Mapea los tokens a la configuración del tema antes del primer componente
Si el proyecto usa Tailwind, los design tokens deberían aterrizar en la configuración del tema como valores con nombre desde el primer día: colores, espaciado, radios, tamaños de fuente, sombras. Haz eso primero y el código que viene después usa bg-surface-raised y p-4 en lugar de valores arbitrarios repartidos por el marcado.
El punto de fricción suele ser la escala de espaciado. Los pasos por defecto de Tailwind son múltiplos de 4px; si los tokens de espaciado de Figma usan otra base, cada hueco del desarrollo se convierte en un valor entre corchetes puesto una sola vez. Alinea las dos escalas al principio, o comprométete a sobrescribir el tema por completo. La alineación a medias es lo peor de ambos mundos.
Los tokens de color deberían cruzar la frontera por nombre semántico, no por hex. Cuando un token cambia de valor más adelante, un mapeo semántico significa una sola edición en el archivo del tema. Un handoff basado en hex significa un buscar y reemplazar por toda una base de código, y se dejará el que hay en la plantilla de correo.
Diseña los estados que nadie pide
Para cada componente que muestra datos, dibuja los casos de cero, uno y muchos. Cero es el estado vacío y necesita un texto que diga qué hacer a continuación, no solo "Sin resultados". Uno es donde a menudo se rompen las maquetaciones centradas y las cuadrículas. Muchos es donde descubres si la lista necesitaba paginación.
Para cada componente que hace peticiones, dibuja los estados de carga y de error. Un esqueleto que coincide con la maquetación final evita el desplazamiento que los usuarios perciben como tirones; un spinner en medio de un contenedor no. Para los errores, escribe el mensaje de verdad: "No se pudieron cargar las facturas. Reintentar" es una decisión de diseño, no un texto que alguien rellena después.
Para cada elemento interactivo, define hover, focus-visible, active y disabled. Los anillos de foco en particular se saltan en el diseño y luego, en el código, o se omiten o se dejan como el valor por defecto del navegador, lo que es a la vez un fallo de accesibilidad y esa clase de detalle sin pulir que los clientes notan sin ser capaces de nombrarlo.
Y prueba la maquetación con contenido hostil: un nombre tres veces más largo que el placeholder, un número con más dígitos de los esperados, un idioma que se extiende más que el inglés. Diez minutos de eso en Figma ahorran un informe de error por pantalla.
Especifica el comportamiento responsive, no lo des por supuesto
Dos frames, uno a 1440 y otro a 390, dejan a la interpretación todo lo que hay entre ellos. Di qué pasa en el hueco: qué breakpoints existen, cuál es el ancho máximo del contenedor, qué cuadrículas pasan de cuatro columnas a dos y a una, y cuál es el padding en cada paso.
El auto layout con wrapping y redimensionado fill-container comunica buena parte de esto sin frames adicionales, porque demuestra la intención en lugar de describirla. Cuando el comportamiento no es nada obvio (una barra lateral que se convierte en un bottom sheet, una tabla que se convierte en tarjetas apiladas), dibuja el estado intermedio. Ese es el que, de lo contrario, el desarrollador tendría que inventar.
Lo que los plugins de diseño a código todavía no pueden hacer
Los plugins que exportan frames de Figma a React han mejorado mucho, y son genuinamente útiles para una sección de marketing estática o un prototipo rápido. Lo que no pueden hacer es producir un componente que encaje en la base de código que ya tienes. El resultado no sabe nada de tu Button existente, tus tokens de tema, tu enrutado, tu capa de datos ni tu gestión de estado, así que llega como una isla de marcado autocontenida que hay que desmontar antes de poder usarla.
Tampoco pueden inferir props ni estados, porque esos no existen en el frame, que es precisamente la brecha descrita al principio de este artículo. El código generado representa una pantalla, un breakpoint, un estado.
El uso realista es el andamiaje: deja que un plugin coloque más o menos la estructura y el espaciado, y luego reescríbelo frente al design system de verdad. Trata el resultado como un primer borrador escrito por alguien que nunca ha visto el resto del proyecto, y la herramienta pasa a ser útil en lugar de una fuente de deuda técnica.
