Implementar Diseño
Resumen
Esta habilidad proporciona un flujo de trabajo estructurado para traducir diseños de Figma en código listo para producción con precisión de píxel perfecto. Garantiza una integración consistente con el servidor MCP de Figma, el uso adecuado de tokens de diseño y una paridad visual 1:1 con los diseños.
Límites de la Habilidad
- Usa esta habilidad cuando el entregable sea código en el repositorio del usuario.
- Si el usuario solicita crear/editar/eliminar nodos dentro de Figma, cambia a figma-use.
- Si el usuario solicita construir o actualizar una pantalla de página completa en Figma a partir de código o una descripción, cambia a figma-generate-design.
- Si el usuario solicita solo mapeos de Code Connect, cambia a figma-code-connect-components.
- Si el usuario solicita redactar reglas de agente reutilizables (
CLAUDE.md/AGENTS.md), cambia a figma-create-design-system-rules.
Prerrequisitos
- El servidor MCP de Figma debe estar conectado y accesible
- El usuario debe proporcionar una URL de Figma con el formato:
https://figma.com/design/:fileKey/:fileName?node-id=1-2:fileKeyes la clave del archivo1-2es el ID del nodo (el componente o marco específico a implementar)
- O al usar el MCP
figma-desktop: El usuario puede seleccionar un nodo directamente en la aplicación de escritorio de Figma (no se requiere URL) - El proyecto debe tener un sistema de diseño o biblioteca de componentes establecido (preferiblemente)
Flujo de Trabajo Requerido
Sigue estos pasos en orden. No omitas pasos.
Paso 1: Obtener el ID del Nodo
Opción A: Extraer de la URL de Figma
Cuando el usuario proporciona una URL de Figma, extrae la clave del archivo y el ID del nodo para pasarlos como argumentos a las herramientas MCP.
Formato de URL: https://figma.com/design/:fileKey/:fileName?node-id=1-2
Extrae:
- Clave del archivo:
:fileKey(el segmento después de/design/) - ID del nodo:
1-2(el valor del parámetro de consultanode-id)
Nota: Al usar el MCP de escritorio local (figma-desktop), no se pasa fileKey como parámetro a las llamadas de herramientas. El servidor usa automáticamente el archivo abierto actualmente, por lo que solo se necesita nodeId.
Ejemplo:
- URL:
https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15 - Clave del archivo:
kL9xQn2VwM8pYrTb4ZcHjF - ID del nodo:
42-15
Opción B: Usar la Selección Actual de la Aplicación de Escritorio de Figma (solo figma-desktop MCP)
Al usar el MCP figma-desktop y el usuario NO ha proporcionado una URL, las herramientas usan automáticamente el nodo seleccionado actualmente del archivo Figma abierto en la aplicación de escritorio.
Nota: La activación basada en selección solo funciona con el servidor MCP figma-desktop. El servidor remoto requiere un enlace a un marco o capa para extraer el contexto. El usuario debe tener la aplicación de escritorio de Figma abierta con un nodo seleccionado.
Paso 2: Obtener el Contexto del Diseño
Ejecuta get_design_context con la clave del archivo y el ID del nodo extraídos.
get_design_context(fileKey=":fileKey", nodeId="1-2")
Esto proporciona los datos estructurados que incluyen:
- Propiedades de diseño (Auto Layout, restricciones, dimensionamiento)
- Especificaciones tipográficas
- Valores de color y tokens de diseño
- Estructura de componentes y variantes
- Valores de espaciado y relleno
Si la respuesta es demasiado grande o está truncada:
- Ejecuta
get_metadata(fileKey=":fileKey", nodeId="1-2")para obtener el mapa de nodos de alto nivel - Identifica los nodos secundarios específicos necesarios a partir de los metadatos
- Obtén nodos secundarios individuales con
get_design_context(fileKey=":fileKey", nodeId=":childNodeId")
Paso 3: Capturar la Referencia Visual
Ejecuta get_screenshot con la misma clave de archivo e ID de nodo para obtener una referencia visual.
get_screenshot(fileKey=":fileKey", nodeId="1-2")
Esta captura de pantalla sirve como fuente de verdad para la validación visual. Mantenla accesible durante toda la implementación.
Paso 4: Descargar los Activos Requeridos
Descarga cualquier activo (imágenes, iconos, SVG) devuelto por el servidor MCP de Figma.
IMPORTANTE: Sigue estas reglas de activos:
- Si el servidor MCP de Figma devuelve una fuente
localhostpara una imagen o SVG, usa esa fuente directamente - NO importes ni agregues nuevos paquetes de iconos: todos los activos deben provenir de la carga útil de Figma
- NO uses ni crees marcadores de posición si se proporciona una fuente
localhost - Los activos se sirven a través del endpoint de activos incorporado del servidor MCP de Figma
Paso 5: Traducir a las Convenciones del Proyecto
Traduce la salida de Figma al framework, estilos y convenciones de este proyecto.
Principios clave:
- Trata la salida del MCP de Figma (típicamente React + Tailwind) como una representación del diseño y el comportamiento, no como un estilo de código final
- Reemplaza las clases utilitarias de Tailwind con las utilidades preferidas del proyecto o los tokens del sistema de diseño
- Reutiliza componentes existentes (botones, entradas, tipografía, envoltorios de iconos) en lugar de duplicar funcionalidades
- Usa el sistema de color, la escala tipográfica y los tokens de espaciado del proyecto de manera consistente
- Respeta los patrones existentes de enrutamiento, gestión de estado y obtención de datos
Paso 6: Lograr Paridad Visual 1:1
Esfuérzate por lograr una paridad visual perfecta con el diseño de Figma.
Directrices:
- Prioriza la fidelidad a Figma para que coincida exactamente con los diseños
- Evita valores codificados: usa tokens de diseño de Figma cuando estén disponibles
- Cuando surjan conflictos entre los tokens del sistema de diseño y las especificaciones de Figma, prefiere los tokens del sistema de diseño pero ajusta el espaciado o los tamaños de manera mínima para que coincidan con lo visual
- Sigue los requisitos WCAG para accesibilidad
- Agrega documentación de componentes según sea necesario
Paso 7: Validar Contra Figma
Antes de marcar como completado, valida la IU final contra la captura de pantalla de Figma.
Lista de verificación de validación:
- El diseño coincide (espaciado, alineación, dimensionamiento)
- La tipografía coincide (fuente, tamaño, peso, altura de línea)
- Los colores coinciden exactamente
- Los estados interactivos funcionan según lo diseñado (hover, activo, deshabilitado)
- El comportamiento responsivo sigue las restricciones de Figma
- Los activos se renderizan correctamente
- Se cumplen los estándares de accesibilidad
Reglas de Implementación
Organización de Componentes
- Coloca los componentes de IU en el directorio del sistema de diseño designado del proyecto
- Sigue las convenciones de nomenclatura de componentes del proyecto
- Evita estilos en línea a menos que sean realmente necesarios para valores dinámicos
Integración del Sistema de Diseño
- Usa SIEMPRE componentes del sistema de diseño del proyecto cuando sea posible
- Mapea los tokens de diseño de Figma a los tokens de diseño del proyecto
- Cuando exista un componente coincidente, extiéndelo en lugar de crear uno nuevo
- Documenta cualquier nuevo componente agregado al sistema de diseño
Calidad del Código
- Evita valores codificados: extráelos a constantes o tokens de diseño
- Mantén los componentes componibles y reutilizables
- Agrega tipos TypeScript para las propiedades de los componentes
- Incluye comentarios JSDoc para los componentes exportados
Ejemplos
Ejemplo 1: Implementar un Componente de Botón
Usuario dice: "Implementa este componente de botón de Figma: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15"
Acciones:
- Extraer de la URL: fileKey=
kL9xQn2VwM8pYrTb4ZcHjFy nodeId=42-15 - Ejecutar
get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15") - Ejecutar
get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")para referencia visual - Descargar cualquier icono de botón desde el endpoint de activos
- Verificar si el proyecto tiene un componente de botón existente
- Si es así, extenderlo con la nueva variante; si no, crear un nuevo componente usando las convenciones del proyecto
- Mapear colores de Figma a tokens de diseño del proyecto (p. ej.,
primary-500,primary-hover) - Validar contra la captura de pantalla: relleno, radio de borde, tipografía
Resultado: Componente de botón que coincide con el diseño de Figma, integrado con el sistema de diseño del proyecto.
Ejemplo 2: Construir un Diseño de Panel
Usuario dice: "Construye este panel: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Dashboard?node-id=10-5"
Acciones:
- Extraer de la URL: fileKey=
pR8mNv5KqXzGwY2JtCfL4Dy nodeId=10-5 - Ejecutar
get_metadata(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")para entender la estructura de la página - Identificar las secciones principales a partir de los metadatos (encabezado, barra lateral, área de contenido, tarjetas) y sus IDs de nodos secundarios
- Ejecutar
get_design_context(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId=":childNodeId")para cada sección principal - Ejecutar
get_screenshot(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")para la página completa - Descargar todos los activos (logotipos, iconos, gráficos)
- Construir el diseño usando las primitivas de diseño del proyecto
- Implementar cada sección usando componentes existentes cuando sea posible
- Validar el comportamiento responsivo contra las restricciones de Figma
Resultado: Panel completo que coincide con el diseño de Figma con diseño responsivo.
Mejores Prácticas
Siempre Comenzar con Contexto
Nunca implementes basándote en suposiciones. Siempre obtén primero get_design_context y get_screenshot.
Validación Incremental
Valida con frecuencia durante la implementación, no solo al final. Esto detecta problemas temprano.
Documentar Desviaciones
Si debes desviarte del diseño de Figma (por ejemplo, por accesibilidad o restricciones técnicas), documéntalo en comentarios de código.
Reutilizar Sobre Recrear
Siempre verifica si existen componentes antes de crear nuevos. La consistencia en todo el código base es más importante que la réplica exacta de Figma.
Priorizar el Sistema de Diseño
En caso de duda, prefiere los patrones del sistema de diseño del proyecto sobre la traducción literal de Figma.
Problemas Comunes y Soluciones
Problema: La salida de Figma está truncada
Causa: El diseño es demasiado complejo o tiene demasiadas capas anidadas para devolverlo en una sola respuesta.
Solución: Usa get_metadata para obtener la estructura del nodo, luego obtén nodos específicos individualmente con get_design_context.
Problema: El diseño no coincide después de la implementación
Causa: Discrepancias visuales entre el código implementado y el diseño original de Figma. Solución: Compara uno al lado del otro con la captura de pantalla del Paso 3. Verifica los valores de espaciado, colores y tipografía en los datos del contexto de diseño.
Problema: Los activos no cargan
Causa: El endpoint de activos del servidor MCP de Figma no es accesible o las URL se están modificando.
Solución: Verifica que el endpoint de activos del servidor MCP de Figma sea accesible. El servidor sirve activos en URLs localhost. Úsalas directamente sin modificación.
Problema: Los valores de los tokens de diseño difieren de Figma
Causa: Los tokens del sistema de diseño del proyecto tienen valores diferentes a los especificados en el diseño de Figma. Solución: Cuando los tokens del proyecto difieran de los valores de Figma, prefiere los tokens del proyecto para mantener la consistencia, pero ajusta el espaciado/dimensionamiento para mantener la fidelidad visual.
Entendiendo la Implementación del Diseño
El flujo de trabajo de implementación de Figma establece un proceso confiable para traducir diseños a código:
Para diseñadores: Confianza en que las implementaciones coincidirán con sus diseños con precisión de píxel perfecto. Para desarrolladores: Un enfoque estructurado que elimina las conjeturas y reduce las revisiones de ida y vuelta. Para equipos: Implementaciones consistentes y de alta calidad que mantienen la integridad del sistema de diseño.
Al seguir este flujo de trabajo, aseguras que cada diseño de Figma se implemente con el mismo nivel de cuidado y atención al detalle.