La mayoría de los archivos de Figma no están listos para handoff a desarrollo. Se ven impresionantes: las pantallas están pulidas, la alineación es perfecta, las opciones de color son deliberadas. Pero cuando un developer abre el archivo y trata de extraer lo que necesita para construirlo, choca con una pared. Los componentes no tienen naming consistente. Auto layout se aplica inconsistentemente, así que los valores de espaciado están enterrados en posicionamiento manual. Las variantes existen para el estado hover pero no para los estados disabled o error. Los design tokens en Figma no coinciden con nada en el codebase.
He estado en ambos lados de este problema a lo largo de mi carrera. Como diseñador UX/UI he entregado archivos que pensé estaban completos y recibí mensajes confusos de developers dos días después. Como Senior Angular developer he recibido archivos de Figma que requerían horas de llamadas de clarificación antes de poder escribir una sola línea de código. La solución, que he refinado a lo largo de años de trabajo en rol dual, es un conjunto de prácticas que ahora aplico consistentemente a cada archivo de Figma que creo. Este post documenta esas prácticas.
Naming: La base de todo
El mal naming en Figma es la causa raíz de la mayoría de los problemas de handoff. Cuando un developer abre el panel Inspect y ve 'Frame 247' o 'Rectangle copy 3', no tiene información útil. Peor aún, el naming inconsistente significa que el developer no puede mapear con confianza los componentes de Figma a los componentes de código correspondientes en el design system.
Sigo una convención de naming que refleja la API del componente lo más cercanamente posible. Los nombres de componentes en Figma usan el mismo formato que el selector del componente Angular o el token del design system. Un botón en Figma se llama Button, no 'CTA' o 'Primary Action'. Sus variantes se nombran usando los nombres de propiedades y valores que aparecerán en código: variant=Primary, size=Medium, state=Default.
// Figma component naming convention
Button
variant: Primary | Secondary | Tertiary | Destructive
size: Small | Medium | Large
state: Default | Hover | Focus | Disabled | Loading
// Maps directly to Angular component usage
<app-button
variant="primary"
size="medium"
[disabled]="isLoading">
Submit
</app-button>Cuando el lenguaje de naming en Figma coincide con el lenguaje de naming en código, la conversación de handoff se vuelve mucho más corta. El developer puede mirar un componente en Figma, identificar su variante y estado desde el panel de propiedades, y saber exactamente qué componente Angular y qué valores de input usar.
Auto Layout bien hecho
Auto layout es la única funcionalidad de Figma que hace cruzar el handoff al modelo CSS flexbox intacto. Usado correctamente, el developer lee el layout en vez de adivinarlo. Usado incorrectamente, o salteado del todo, lo deja infiriendo la lógica de layout desde mediciones de píxeles que describen un solo frame congelado y nada sobre cómo se comporta la cosa cuando el viewport se mueve.
Mis reglas para auto layout en archivos listos para handoff:
- Cada componente que se construirá con flexbox o grid en CSS debe usar auto layout en Figma. Sin excepciones.
- El espaciado entre elementos debe venir del gap de auto layout, no de elementos posicionados manualmente. Un valor de gap en Figma se traduce directamente a gap en CSS.
- Usa 'Fill container' para elementos que se estiran para tomar el espacio disponible, y 'Hug contents' para elementos dimensionados por lo que tienen adentro. El mapeo a CSS es cercano, no exacto, y lo decide el eje. Fill a lo largo del eje del layout es flex-grow: 1. Fill a través del eje del layout es align-self: stretch. Hug es fit-content en el eje y auto a través de él. Di de qué eje hablas en la anotación y el developer deja de adivinar.
- El padding debe establecerse en el panel de auto layout, no agregando frames espaciadores invisibles. Los valores de padding en Figma son lo que el developer implementará en CSS.
- Usa restricciones de min/max width para componentes que necesitan comportamiento responsive: una card que debe ser de al menos 280px de ancho pero puede crecer se expresa en restricciones de auto layout.
Variantes y estados interactivos
Un componente sin todos sus estados documentados no es un componente, es una especificación parcial. Ya he escrito sobre esto desde la perspectiva de escritura de briefs, pero en Figma específicamente, el estándar es: cada componente interactivo debe tener variantes para todos los estados que existen en la implementación.
Para un campo de texto input, eso significa: Default, Focused, Filled, Error, Disabled, y Read-only. Para un botón: Default, Hover, Focus, Active, Disabled, y Loading. Estos no son edge cases: son el conjunto mínimo que cualquier botón encontrará en producción.
La funcionalidad de componentes interactivos de Figma (conexiones de prototipo entre variantes) es valiosa para comunicar el comportamiento de hover y focus en prototipos. Pero no dependas de ella como sustituto de la documentación de variantes. Cada estado debe existir como una variante distinta en el set de componentes, etiquetada claramente, para que un developer pueda inspeccionarla directamente sin tener que disparar una interacción de prototipo.
Design Tokens: El puente entre Figma y código
Los design tokens son la herramienta más importante para reducir la fricción de handoff, y también la más comúnmente mal implementada. El objetivo es simple: cada decisión de diseño en Figma (color, espaciado, tipografía, border radius, sombra, duración) debe referenciar un token nombrado, y ese token debe existir en el codebase bajo el mismo nombre.
En la práctica, esto significa configurar tus variables de Figma para que coincidan exactamente con tus CSS custom properties o el objeto de tokens JavaScript. El armado que aguanta exporta las Figma Variables como JSON y pasa el archivo por Style Dictionary para generar el CSS. Tokens Studio (anteriormente Figma Tokens) es otra opción: maneja el set de tokens dentro de Figma y lo puede sincronizar con un repositorio.
/* In CSS (design system tokens) */
:root {
--color-action-primary: #0052cc;
--color-action-primary-hover: #003d99;
--color-surface-default: #ffffff;
--color-text-primary: #172b4d;
--space-2: 8px;
--space-3: 12px;
--space-4: 16px;
--radius-md: 6px;
--shadow-card: 0 1px 3px rgba(0,0,0,0.12);
}Cuando el developer inspecciona un botón en Figma y ve que el color de fondo es var(--color-action-primary) en lugar de un valor hexadecimal, puede implementarlo inmediatamente con el token correcto. Sin color-picking, sin valores hex hardcodeados, sin drift entre diseño e implementación.
Sincronizando tokens entre Figma y código
Otro workflow que elimina la deriva, cuando la misma persona o el mismo equipo es dueño de la librería de Figma y de la librería de componentes, es código primero: los design tokens viven en un archivo JSON del repositorio como única fuente de verdad. Un plugin de sincronización como Tokens Studio lee ese archivo y pobla el set de tokens en Figma. Cuando un token cambia (actualización de color de marca, ajuste de espaciado), el cambio se hace en el archivo JSON, se abre un PR, y una vez que se fusiona, la librería de Figma se sincroniza desde el archivo actualizado. Figma siempre refleja lo que está en código, no al revés. Escribir los tokens en Figma Variables y exportar el JSON, el armado que describí arriba, funciona igual de bien, siempre que el equipo elija una dirección y la deje por escrito. En BMO el design system pertenecía a otro equipo y yo trabajaba del lado consumidor, donde la pregunta que importa es la misma: ¿en qué dirección fluye la verdad?
Plugins de anotación y especificaciones
El panel de inspección de Figma es útil pero insuficiente para componentes complejos. Cuatro tipos de nota tienen que vivir en algún lugar del canvas: notas de interacción (qué pasa al hacer clic, qué interacciones de teclado se soportan), notas de comportamiento responsive, anotaciones de accesibilidad (roles ARIA, orden de foco), y notas de restricciones de contenido (conteos máximos de caracteres, ratios de aspecto de imágenes). Ninguna aparece sola en Inspect.
Empieza por la vía gratuita, porque funciona con cualquier asiento y es donde yo sigo empezando por defecto. Un componente de callout y un estilo de texto para las notas te dan una capa de spec completa sin pagar nada. Si quieres que las partes de medición y anatomía se generen en vez de dibujarlas a mano, el plugin Specs de EightShapes tiene un nivel gratuito que cubre anotaciones de anatomía, layout y espaciado, y Redlines & Annotations en la comunidad de Figma hace overlays de medición. Los dos escriben capas comunes en el canvas, así que cualquiera con acceso de lectura puede leer el resultado.
Figma Dev Mode tiene anotaciones y mediciones nativas, y son mejores que cualquier cosa que dibujes a mano: la anotación se ata a la capa, sobrevive a un renombrado, se actualiza cuando la capa se mueve, y aparece en el panel de Inspect, donde el developer ya está mirando. El detalle es el asiento. Dev Mode exige un asiento pago Full o Dev desde enero de 2024. Trátalo como un upgrade que compras cuando el volumen de handoff lo justifica, no como el punto de partida. Si tu equipo ya lo paga, úsalo y borra tu capa de anotación manual.
Vengan de donde vengan las notas, viven en su propia página de Figma en mis archivos, nombrada 'Specs & Annotations'. Contiene un duplicado de cada pantalla con las anotaciones superpuestas, en vez de anotaciones puestas sobre los frames de diseño mismos, porque eso satura el diseño apenas un stakeholder lo abre. El developer necesita la spec, va a la página de Specs. El stakeholder quiere el diseño limpio, se queda en la página de diseño.
Organización de archivos que los developers pueden navegar
Un archivo de Figma que es visualmente hermoso pero estructuralmente caótico es inútil para handoff. Mi estructura de archivos para cualquier proyecto listo para desarrollo:
- Página de portada: Nombre del proyecto, estado (En Progreso / Listo para Dev / En Desarrollo / Hecho), última fecha de actualización, dueño de diseño, contacto de developer.
- Página de tokens: Todas las variables y estilos documentados con sus valores y notas de uso.
- Página de componentes: La librería de componentes: todas las variantes de todos los componentes organizadas por categoría.
- Página de flujos: Flujos pantalla por pantalla organizados por journey de usuario, con conexiones de prototipo.
- Página de Specs & Annotations: Versiones anotadas de todas las pantallas listas para inspección del developer.
- Página de archivo: Exploraciones antiguas y conceptos rechazados, guardados para referencia pero claramente etiquetados.
La ventaja del rol dual en el handoff
Escribir este post me hace darme cuenta de cuánto mi experiencia de desarrollo ha moldeado cómo diseño. Cuando creo una variante de componente para el estado de carga de un botón, no lo hago por exhaustividad en sí misma: lo hago porque sé por experiencia que un developer implementando ese botón necesitará saber cómo se ve cuando isLoading es true, y sin una referencia de diseño va a preguntar o inventar algo.
Cada anotación que escribo en una spec es una respuesta a una pregunta que sé que un developer hará, porque yo mismo he hecho esas mismas preguntas. ¿Cómo debería verse el focus ring? ¿Cuántas líneas soporta este campo de texto antes de desbordarse? ¿Qué pasa con el layout de la card si no hay imagen thumbnail?
Si eres un diseñador que no codea, la forma más rápida de mejorar la calidad de tu handoff es hacer pair con un developer por un sprint y pedirle que narre su experiencia abriendo tu archivo de Figma e implementando desde él. Los puntos de fricción que encuentre te dirán exactamente qué mejorar. El developer es tu usuario cuando el producto es un archivo de Figma, y la investigación de usuarios aplica.
Un archivo de Figma es un documento de especificación. Un documento de especificación es una herramienta de comunicación. Júzgalo no por lo hermoso que se ve, sino por cuán claramente responde las preguntas del developer.
El objetivo no es un archivo perfecto: es un archivo que le permita a un developer empezar a construir el lunes por la mañana sin una sola pregunta de clarificación. Ese es un estándar alto, pero es alcanzable, y vale la inversión inicial cada vez.
Referencias
- Figma auto-layout. https://help.figma.com/hc/en-us/articles/360040451373-Guide-to-auto-layout
- Figma variants. https://help.figma.com/hc/en-us/articles/360056440594-Create-and-use-variants
- Guía de Figma Dev Mode, requiere asiento pago Full o Dev. https://help.figma.com/hc/en-us/articles/15023124644247-Guide-to-Dev-Mode
- Anuncio de disponibilidad general de Figma Dev Mode, enero de 2024. https://www.figma.com/blog/dev-mode-ga/
- Tokens Studio. https://tokens.studio/
- API REST de Figma Variables (solo plan Enterprise; los plugins de exportación de la comunidad son la vía gratuita). https://developers.figma.com/docs/rest-api/variables/