Guía de Contribución — Edifiko

Índice

1. Requisitos previos
2. Configuración del servidor MCP de Figma
3. Vinculación con GitHub Copilot en VS Code
4. Verificación de la conexión
5. Flujo de trabajo de diseño a código
6. Resolución de problemas
7. Git para el equipo de diseño

1. Requisitos previos

Antes de comenzar asegúrate de tener instalado:

2. Configuración del servidor MCP de Figma

El servidor MCP permite que GitHub Copilot acceda directamente al contexto de los diseños en Figma (colores, tipografía, layout, componentes, etc.).

2.1 Instalar el plugin en Figma Desktop

1. Abre Figma Desktop (no la versión web; el servidor sólo funciona en la app de escritorio).
2. Ve a Menú principal → Plugins → Manage plugins.
3. Busca "Figma MCP" en la comunidad de plugins e instálalo.
4. Una vez instalado, abre cualquier archivo del proyecto Edifiko.
5. Ejecuta el plugin: Plugins → Figma MCP → Start server.

El plugin levantará un servidor HTTP local en http://127.0.0.1:3845. Verás un indicador verde en la barra del plugin cuando esté activo.

Importante: El servidor MCP sólo está activo mientras Figma Desktop esté abierto y el plugin en ejecución. Debes arrancarlo cada vez que inicies una sesión de desarrollo.

3. Vinculación con GitHub Copilot en VS Code

La configuración ya está incluida en el repositorio en .vscode/mcp.json. No necesitas crearla manualmente, pero es útil entender qué contiene:

{
  "servers": {
    "FigmaMCP": {
      "url": "http://127.0.0.1:3845/mcp",
      "type": "http"
    }
  },
  "inputs": []
}

Este archivo le indica a Copilot Agent que existe un servidor MCP llamado FigmaMCP escuchando en el puerto 3845. VS Code lo carga automáticamente al abrir el workspace.

3.1 Habilitar los servidores MCP en VS Code

1. Abre la Paleta de comandos (Cmd+Shift+P en macOS / Ctrl+Shift+P en Windows/Linux).
2. Ejecuta MCP: List Servers.
3. Verifica que FigmaMCP aparezca con estado Running. Si aparece en rojo, el servidor de Figma no está activo (ver paso 2.1).

3.2 Abrir Copilot en modo Agente

Para que Copilot pueda usar las herramientas MCP debes usar el modo Agent, no el modo Chat normal:

1. Abre el panel de Copilot (Cmd+Ctrl+I).
2. En el selector de modo (parte superior del chat), elige Agent.
3. A partir de aquí, cuando hagas una consulta relacionada con diseño, Copilot invocará automáticamente las herramientas de Figma MCP.

4. Verificación de la conexión

Para confirmar que todo funciona correctamente, pega el siguiente prompt en el chat de Copilot (modo Agent):

Si la conexión es exitosa, Copilot responderá con los colores, tipografías y estructura del componente directamente desde Figma. Si no tiene acceso, mostrará un error indicando que el servidor MCP no está disponible.

5. Flujo de trabajo de diseño a código

El flujo estándar del proyecto para implementar una pantalla o componente desde Figma es el siguiente:

5.1 Obtener el node-id del diseño

1. En Figma Desktop, selecciona el frame o componente que vas a implementar.
2. Copia la URL desde el navegador o desde Copiar enlace al archivo — tendrá el formato: https://www.figma.com/design/GHndKg4N155tzEat2CRHf0/Edifiko?node-id=51-19
3. El node-id es el valor 51-19 (en la API de MCP se usa con : en lugar de -: 51:19).

5.2 Solicitar el código a Copilot

Usa el siguiente prompt como plantilla:

5.3 Convenciones obligatorias al implementar

• No hardcodes colores una vez que los tokens estén definidos en globals.css o tailwind.config.ts. Usa clases como bg-primary, text-foreground, etc.
• No llames a Firebase directamente desde un componente. Usa la capa de servicios en @/services/firebase.
• Responsividad Mobile First: diseña primero para móvil y usa md:, lg: para pantallas mayores.

6. Resolución de problemas

El servidor MCP no aparece en VS Code

• Verifica que Figma Desktop esté abierto y el plugin MCP esté corriendo.
• Recarga VS Code: Cmd+Shift+P → Developer: Reload Window.
• Confirma que .vscode/mcp.json existe en la raíz del proyecto.

Copilot no usa las herramientas de Figma

• Asegúrate de estar en modo Agent (no modo Chat).
• Comprueba que el estado del servidor en MCP: List Servers sea Running.
• Si el estado es Error, reinicia el plugin en Figma Desktop.

El plugin de Figma no levanta en el puerto 3845

• Puede haber un proceso ocupando ese puerto. Revisa con:
  bash

  lsof -i :3845
  

• Si hay un proceso activo, termínalo con kill -9 [PID] y reinicia el plugin.

Copilot genera código genérico sin contexto de Figma

• Asegúrate de incluir el node-id en tu prompt.
• El plugin sólo expone nodos del archivo actualmente abierto en Figma Desktop. Abre el archivo correcto (GHndKg4N155tzEat2CRHf0).

7. Git para el equipo de diseño

Git es el sistema de control de versiones que usa el proyecto. Permite que todo el equipo trabaje en paralelo sin pisarse los cambios. Esta sección explica, en términos simples, cada comando que necesitarás en tu día a día.

Prerequisito: Tener instalado Git y acceso al repositorio en GitHub. Si no tienes acceso, contacta al tech lead del proyecto.

7.1 git clone — Descargar el repositorio por primera vez

Qué hace: Copia el repositorio remoto de GitHub a tu máquina local. Solo lo haces una vez al incorporarte al proyecto.

git clone git@github.com:rappidtech/edifiko.git
cd edifiko

Después del clone, instala las dependencias:

pnpm install

7.2 git fetch — Ver qué cambios existen en remoto

Qué hace: Descarga la información de los cambios que hay en GitHub sin aplicarlos a tu código. Es seguro: no modifica nada en tu trabajo actual.

git fetch --all

Úsalo para saber si hay ramas nuevas o cambios antes de empezar a trabajar.

7.3 git branch y git checkout — Trabajar en una rama propia

Qué es una rama: Una rama es una copia aislada del proyecto donde puedes hacer cambios sin afectar el código principal (main).

Convención de nombres de rama en Edifiko:

Crear y moverse a una rama nueva:

# Ver todas las ramas existentes
git branch -a

# Crear una nueva rama y moverse a ella en un solo comando
git checkout -b feat/mi-nueva-pantalla

Moverse a una rama que ya existe:

git checkout nombre-de-la-rama

Regla del equipo: Nunca trabajes directamente en main. Siempre crea una rama propia a partir de main.

7.4 git pull — Actualizar tu rama con los últimos cambios

Qué hace: Descarga los cambios remotos y los aplica a tu rama actual. Úsalo siempre al inicio de tu sesión de trabajo para no quedarte desactualizado.

# Asegúrate de estar en tu rama antes de ejecutarlo
git pull origin main

Si tu rama lleva tiempo sin actualizarse, es buena práctica traer los últimos cambios de main:

git pull origin main

7.5 git add — Marcar archivos para guardar

Qué hace: Indica a Git qué archivos quieres incluir en el próximo guardado (commit). Es como seleccionar qué fotos vas a subir antes de publicarlas.

# Agregar un archivo específico
git add src/components/features/MiComponente.tsx

# Agregar todos los archivos modificados del proyecto
git add .

Tip: Usa git status antes de git add para ver qué archivos cambiaste.

git status

7.6 git commit — Guardar los cambios con un mensaje

Qué hace: Crea un "punto de guardado" permanente con todos los archivos que marcaste con git add. El mensaje describe qué hiciste.

Convención de mensajes de commit en Edifiko (formato Conventional Commits):

git commit -m "feat: agrega componente tarjeta de propiedad"

Importante: Los commits pasan por eslint, prettier y vitest automáticamente (Husky). Si algo falla, el commit no se creará hasta que corrijas los errores.

Omitir los hooks en casos excepcionales: Si necesitas commitear un trabajo en progreso sin pasar por las validaciones (por ejemplo, para hacer un checkpoint rápido o debuggear), puedes saltear Husky con el flag --no-verify:

bash

git commit -m "wip: descripción" --no-verify

Úsalo con criterio. Nunca hagas push con --no-verify hacia main o dev sin asegurarte de que el código compila y los tests pasan.

7.7 git push — Subir tus cambios a GitHub

Qué hace: Envía los commits de tu rama local al repositorio remoto en GitHub para que el resto del equipo los vea.

# La primera vez que subes una rama nueva
git push --set-upstream origin feat/mi-nueva-pantalla

# Las veces siguientes, en la misma rama
git push

7.8 Crear un Pull Request (PR) en GitHub

Un Pull Request es la solicitud formal para que tu trabajo sea revisado e integrado a main. Es el punto donde el equipo de desarrollo revisa los cambios antes de publicarlos.

Pasos:

1. Asegúrate de haber subido tu rama con git push.
2. Ve al repositorio en GitHub: https://github.com/tu-org/edifiko.
3. Aparecerá un banner amarillo con el botón "Compare & pull request" — haz clic en él.
4. Rellena el formulario del PR:
   • Título: Usa el mismo formato que los commits (ej. feat: pantalla de búsqueda de propiedades).
   • Descripción: Explica qué diseño implementaste, incluye capturas de pantalla o el node-id de Figma.
   • Reviewers: Asigna al tech lead o al desarrollador responsable.
   • Labels: Agrega design si el cambio es principalmente visual.
5. Haz clic en "Create pull request".

Nunca hagas merge de tu propio PR. Espera la aprobación de al menos un revisor.

7.9 Flujo completo de trabajo (resumen)

Este es el ciclo que debes seguir cada vez que trabajes en una tarea:

# 1. Actualizar tu copia local con los últimos cambios de main
git checkout main
git pull origin main

# 2. Crear una rama nueva para tu tarea
git checkout -b feat/nombre-de-tu-tarea

# 3. Hacer tus cambios en el código o assets...

# 4. Ver qué archivos modificaste
git status

# 5. Marcar los archivos que quieres guardar
git add .

# 6. Crear el commit con un mensaje descriptivo
git commit -m "feat: descripción de lo que hiciste"

# 7. Subir la rama a GitHub
git push --set-upstream origin feat/nombre-de-tu-tarea

# 8. Abrir GitHub y crear el Pull Request

8 Guía de Uso: Edifiko Designer

Para garantizar que los componentes generados por IA respeten la arquitectura del proyecto, los estándares de diseño (Tailwind v4 / Shadcn) y se documenten correctamente en el Showcase, utiliza la siguiente plantilla al interactuar con el Edifiko Designer.

Plantilla de Prompt (Copiar y Pegar)

Copia el bloque a continuación, completa los datos entre corchetes [ ] y envíaselo al agente:

Agente: Designer

Por favor, implementa un nuevo componente UI siguiendo nuestras reglas de arquitectura.

Contexto y Directorios:

• Feature / Módulo: [Ej: SupplierDashboard / Authentication / ProjectManagement]
• Nombre del Componente: [Ej: MaterialCard / SupplierFilter / StepIndicator]

Diseño y Referencias:

• Figma URL / Specs: [Pega aquí la URL exacta del nodo en Figma o describe la UI en detalle]

Requerimientos Específicos:

• [Opcional: Ej: Debe incluir un estado de "Cargando" (Skeleton)]
• [Opcional: Ej: El botón secundario debe abrir un modal, pero por ahora solo haz un console.log]
• [Opcional: Ej: Asume que la data vendrá de esta interfaz: { id: string, name: string, price: number }]

Plan de Acción Esperado:

1. Analiza el diseño provisto.
2. Crea el componente en la ruta: components/features/[Feature]/[NombreDelComponente].tsx (Recuerda: strictly in English, Server Component por defecto, interfaces TypeScript claras).
3. Estiliza usando únicamente tokens de globals.css (Tailwind v4) y primitivos de components/ui/ (Shadcn).
4. Documenta: Crea la página correspondiente en app/ui/[Feature]/[NombreDelComponente]/page.tsx implementando el componente con mocks realistas y mostrando sus variantes (ej. default, hover, disabled).

Buenas Prácticas para el Equipo

• Sé granular: Si el diseño es una vista completa (ej. un Dashboard entero), pídele primero que cree los componentes pequeños (Tarjetas, Tablas) y en un prompt posterior pídele que los ensamble en el Layout.
• Nombres en Inglés: Recuerda que el agente está programado para nombrar todo en inglés, así que intenta que la "Feature" y el "Componente" en el prompt ya vengan en ese idioma para evitar traducciones extrañas.