Handoff de diseño a desarrollo: especificaciones, Dev Mode y documentación clara

Hay una conversación que se repite en muchos equipos. Desarrollo pregunta qué pasa con el botón cuando el texto es más largo, diseño responde que eso «se ve en el archivo», desarrollo no lo encuentra y al final alguien decide sobre la marcha. Multiplica eso por cien decisiones pequeñas y entenderás por qué tantas webs se parecen a su diseño, pero no del todo: el espaciado se ha estrechado, los estados de error son genéricos y en móvil el titular parte la línea en un sitio raro.

En el estudio diseñamos y desarrollamos en el mismo equipo, y aun así cuidamos el traspaso como un entregable más, porque el código no puede adivinar lo que el diseño no dice. El handoff (la entrega de diseño a desarrollo) no es enviar un enlace a Figma. Es preparar el diseño para que quien lo construye tenga todas las respuestas antes de hacer las preguntas.

Esta guía recoge cómo lo hacemos: cómo organizar el archivo, qué especificar, cómo aprovechar Dev Mode de Figma, qué anotar sobre accesibilidad y comportamiento, y cómo cerrar el círculo revisando lo construido.

01El handoff empieza antes de terminar el diseño

El error de planteamiento más frecuente es pensar en el handoff como un momento final. Lo que funciona es tratarlo como un proceso que arranca con el diseño.

• →Desarrollo en las revisiones intermedias. Una persona del equipo técnico revisando los wireframes detecta pronto lo que será complejo de construir, cuando aún es barato cambiarlo.
• →Componentes desde el principio. Si el diseño se construye con componentes y variables, la mitad del handoff está hecha sin darte cuenta. Lo explicamos en la guía de Figma a fondo.
• →Nombres compartidos. Que el botón se llame igual en Figma y en código («Button / primary / large») ahorra traducciones constantes.
• →Prototipos que se pueden tocar. Un prototipo interactivo explica el comportamiento mejor que cualquier nota.

Cuando llega el momento formal del traspaso, esas conversaciones previas hacen que la sesión dure una hora en lugar de una semana de mensajes.

02Cómo preparar el archivo de Figma

Un archivo de diseño de trabajo y uno de entrega son cosas distintas. El primero está lleno de exploraciones, versiones descartadas y notas para uno mismo. El segundo tiene que entenderse sin su autor delante.

Estructura que se lee sola

1. 01Una página de portada con el nombre del proyecto, la fecha, el estado y enlaces a la documentación y al prototipo.
2. 02Páginas por flujo o sección, no por fecha de trabajo: «Registro», «Ficha de producto», «Checkout».
3. 03Las exploraciones, en una página aparte claramente marcada como archivo, o fuera del archivo de entrega.
4. 04Secciones marcadas como listas para desarrollo solo cuando lo están de verdad. En Dev Mode, el estado Ready for dev permite a desarrollo filtrar lo que puede empezar a construir.
5. 05Frames con nombre descriptivo: «Checkout / Paso 2 / Error tarjeta», mejor que «Frame 482».

Componentes, variables y auto layout

Las pantallas de entrega deberían estar construidas con instancias de componentes, no con grupos sueltos, y con auto layout, que es la forma en que Figma expresa espaciados y comportamiento flexible de manera muy parecida al flexbox de CSS. Los colores, espaciados, radios y tipografías, como variables y estilos con nombre. Así, al inspeccionar, desarrollo ve space/400 o color/text/secondary y no un 16px o un #6B6B6B que tiene que interpretar. Esos nombres son la base de los design tokens, el puente natural entre diseño y código.

03Qué especificar más allá de las pantallas

Una pantalla estática enseña un instante. El producto vive en muchos. Esta es la lista de lo que documentamos además del diseño «feliz».

Estados de cada componente

Por defecto, hover, foco, pulsado, desactivado, cargando, error y éxito, según aplique. El estado de foco merece mención especial: es el que se ve al navegar con teclado y el que más a menudo se olvida. WCAG 2.2 incluye criterios específicos para que el foco sea visible y no quede oculto por otros elementos.

Estados de cada pantalla

• →Vacío: cuando todavía no hay datos.
• →Cargando: con skeletons o indicadores, según la duración esperada.
• →Error: de red, de permisos, de datos.
• →Parcial: un solo elemento en una lista pensada para muchos.
• →Exceso: un nombre de 60 caracteres, una lista de 300 resultados, un precio con seis cifras.

Comportamiento responsive

En lugar de entregar tres versiones de cada pantalla sin explicación, describimos las reglas: qué columnas se apilan, qué se oculta en móvil y dónde va, qué elementos tienen ancho fijo y cuáles se estiran, cuál es el ancho máximo del contenido. Normalmente diseñamos a 375, 768 y 1440 px y anotamos qué pasa entre medias.

Movimiento

Para cada animación: qué la dispara, qué propiedades cambian, duración, curva de easing y alternativa con movimiento reducido. Una línea por animación basta: «Drawer: entra desde la derecha, 300 ms, cubic-bezier(0.05, 0.7, 0.1, 1); con movimiento reducido, fundido de 150 ms». En la guía de animación en UI tienes los rangos de referencia.

Contenido

Textos definitivos o, como mínimo, reglas: longitud máxima de un titular, qué pasa si se corta, formato de fechas y precios, mensajes de error exactos. El microcopy es diseño y se entrega con el mismo cuidado.

04Anotaciones de accesibilidad

La accesibilidad se resuelve mucho mejor si viene especificada desde diseño, porque hay decisiones que no se pueden deducir de una imagen. Estas son las anotaciones que añadimos en las pantallas clave:

• →Orden de foco cuando no coincide con el orden visual evidente.
• →Estructura de encabezados: qué es H1, H2, H3, independientemente del tamaño visual.
• →Regiones (landmarks): cabecera, navegación, contenido principal, pie.
• →Textos alternativos de imágenes informativas e indicación de las decorativas.
• →Nombres accesibles de botones que solo tienen icono («Cerrar», «Añadir a favoritos»).
• →Anuncios dinámicos: qué debe comunicarse a un lector de pantalla cuando algo cambia sin recargar la página.
• →Contrastes verificados: 4,5:1 para texto normal y 3:1 para texto grande e iconos necesarios.

Figma incorpora herramientas de anotación propias en Dev Mode y existen kits de anotación de accesibilidad de uso libre que añaden marcadores visuales para estas indicaciones. Cualquier sistema vale si es consistente.

05Dev Mode, Code Connect y tokens: herramientas que ayudan

Dev Mode es la vista de Figma pensada para desarrollo. Muestra medidas, espaciados, variables aplicadas, propiedades de componentes y fragmentos de código de referencia en CSS, iOS o Android. Permite filtrar lo marcado como listo para desarrollo y comparar qué ha cambiado en un frame desde la última versión, algo muy útil cuando el diseño se ajusta a mitad de la construcción.

Code Connect enlaza cada componente de Figma con su equivalente en el repositorio de código. Cuando está configurado, al inspeccionar un botón Dev Mode muestra el fragmento real que usa el equipo, con sus propiedades, en lugar de CSS genérico. Es uno de los avances más prácticos de los últimos años para equipos con sistema de diseño.

Los tokens exportados cierran el círculo. Con plugins como Tokens Studio, o con la API de variables de Figma, los valores de diseño se exportan a JSON y una herramienta como Style Dictionary los transforma en variables CSS, constantes de JavaScript o recursos de iOS y Android. El W3C Design Tokens Community Group ha publicado un formato estándar para estos archivos, lo que facilita que distintas herramientas se entiendan:

{
  "color": {
    "text": {
      "primary": { "$type": "color", "$value": "#1d2420" },
      "secondary": { "$type": "color", "$value": "#5b645e" }
    },
    "action": {
      "primary": { "$type": "color", "$value": "{color.brand.500}" }
    }
  },
  "space": {
    "200": { "$type": "dimension", "$value": "8px" },
    "400": { "$type": "dimension", "$value": "16px" }
  }
}

Si el equipo es pequeño y no hay sistema de tokens automatizado, una tabla de variables con nombre y valor, mantenida en la documentación, cumple la misma función.

06La sesión de traspaso y el documento de entrega

Además del archivo, preparamos una página de documentación por funcionalidad (en Notion, Confluence o en el propio Figma) con esta estructura:

1. 01Objetivo: qué problema resuelve y para quién, en dos frases.
2. 02Enlaces: archivo de Figma, prototipo, tickets relacionados.
3. 03Flujos: diagrama simple de pantallas y decisiones.
4. 04Reglas de negocio: validaciones, permisos, límites.
5. 05Estados y casos límite: la lista de la sección anterior.
6. 06Accesibilidad: anotaciones clave.
7. 07Fuera de alcance: lo que no entra en esta entrega, para evitar suposiciones.
8. 08Dudas abiertas: con responsable y fecha.

Con esa página, hacemos una sesión de 45 a 60 minutos con quien va a desarrollar. Recorremos el prototipo, explicamos las decisiones con su porqué y resolvemos dudas en el momento. Las respuestas se añaden a la documentación, no se quedan en el chat.

Ejemplo resuelto: especificar un buscador con autocompletado

Para que se vea el nivel de detalle, esta es la ficha que entregamos para el buscador de un catálogo de mobiliario:

• →Disparo: las sugerencias aparecen a partir del segundo carácter, con una espera de 250 ms tras la última pulsación para no lanzar una petición por cada letra.
• →Contenido de la lista: hasta seis sugerencias; las dos primeras pueden ser categorías y el resto productos con miniatura de 40 × 40 px. La parte del texto que coincide con lo escrito, en negrita.
• →Teclado: flechas para recorrer, Intro para abrir la sugerencia activa, Escape para cerrar la lista y devolver el foco al campo.
• →Accesibilidad: patrón combobox de las prácticas de autoría ARIA del W3C; el número de resultados se anuncia a lectores de pantalla («6 sugerencias disponibles»).
• →Sin resultados: mensaje «No encontramos nada con “sofá cama nórdico”» y tres búsquedas populares como alternativa.
• →Error de red: la lista se cierra sin aviso y la búsqueda completa sigue funcionando al pulsar Intro.
• →Móvil: al enfocar el campo, el buscador ocupa la pantalla completa con un botón «Cancelar» visible arriba a la derecha.
• →Movimiento: la lista aparece con fundido y desplazamiento de 4 px en 150 ms; con movimiento reducido, solo fundido.

Son ocho líneas. Escribirlas lleva media hora y evita, como mínimo, otras tantas preguntas durante el desarrollo, además de que todas las personas del equipo imaginen el mismo buscador. Si quieres profundizar en las decisiones de experiencia que hay detrás de este componente, la guía de búsqueda interna las desarrolla.

07Design QA: revisar que lo construido es lo diseñado

El handoff termina cuando diseño revisa lo construido en el entorno de pruebas. Lo hacemos con una lista fija:

• →Tipografía: tamaños, pesos, interlineado y cortes de línea en móvil y escritorio.
• →Espaciados y alineaciones respecto a la rejilla.
• →Colores y contrastes en modo claro y, si existe, oscuro.
• →Todos los estados interactivos, incluido el foco con teclado.
• →Estados vacíos, de carga y de error, provocándolos a propósito.
• →Comportamiento entre los tamaños diseñados, estirando la ventana poco a poco.
• →Animaciones y su versión con movimiento reducido.
• →Rendimiento básico: que imágenes y fuentes no provoquen saltos de contenido.

Las observaciones se registran como tickets priorizados: imprescindible antes de publicar, deseable, mejora futura. Con capturas anotadas y la referencia exacta del frame de Figma.

08Un traspaso que es una conversación

La mejor señal de un handoff bien hecho es que el equipo técnico construye con calma, pregunta poco y lo que pregunta es interesante. Cuando el diseño llega con sus reglas, sus estados y su porqué, desarrollo puede dedicar su talento a resolverlo bien en lugar de adivinar.

En SIMA tenemos la suerte de diseñar y programar en casa, desde el diseño web y de experiencia digital hasta el desarrollo, y aun así seguimos este proceso en cada proyecto. Si tu equipo quiere ordenar el traspaso entre diseño y código, o necesitas un estudio que haga las dos cosas, escríbenos.