ftc-android

name	ftc-android
description	Pixel-perfect Figma-to-Android implementation loop using ADB and Figma MCP
allowed-tools	["Bash","Read","Glob","Grep","Edit","Write"]

/ftc-android: Pixel-Perfect Android Implementation Loop

Requisitos: Figma MCP configurado, Android Emulator corriendo, ADB disponible.

IMPORTANTE: Figma MCP

Errores y Límites

Si el Figma MCP falla (error, timeout, rate limit), DETENERSE INMEDIATAMENTE.

• NO continuar sin los datos de Figma
• NO intentar "adivinar" o usar valores por defecto
• INFORMAR al usuario del error exacto
• ESPERAR a que el usuario resuelva el problema

❌ MAL:  MCP falla → continuar implementando con valores aproximados
✅ BIEN: MCP falla → STOP → informar al usuario → esperar resolución

El usuario debe saber si Figma no está funcionando. Sin datos de Figma, no hay pixel-perfect.

Optimización de Peticiones

Minimizar llamadas al Figma MCP. Cada petición consume tiempo y recursos.

1. Una sola extracción inicial: Obtener TODO en una llamada combinada cuando sea posible
2. NO repetir peticiones: Si ya tienes el screenshot o metadata, reusarlo
3. Cachear mentalmente: Recordar colores, espaciados y estilos ya extraídos
4. Solo re-fetch si cambió el diseño: No pedir screenshot de Figma en cada iteración

❌ MAL:  get_screenshot → implementar → get_screenshot → comparar → get_screenshot...
✅ BIEN: get_screenshot (1 vez) → implementar → comparar con screenshot guardado → iterar

Phase 0: Project & Device Discovery

1. Android Project Detection

Verificar que estamos en un proyecto Android:

• build.gradle.kts o build.gradle en raíz
• app/src/main/java/ o app/src/main/kotlin/ existe
• AndroidManifest.xml presente

2. Build System Detection

• build.gradle.kts → Kotlin DSL
• build.gradle → Groovy DSL
• Verificar gradle/wrapper/gradle-wrapper.properties para versión

3. Design System Detection

Escanear app/src/main/res/values/:

• colors.xml → paleta de colores
• dimens.xml → spacing/sizing tokens
• themes.xml → tema principal
• styles.xml → estilos de componentes

Escanear dependencias en build.gradle.kts:

• material3 → Material Design 3
• material → Material Design 2
• compose.ui → Jetpack Compose
• XML Views si no hay Compose

4. Emulator Verification & Auto-Start

Paso 1: Verificar si hay emulador corriendo:

adb devices

Paso 2: Si NO hay emulador conectado (solo muestra "List of devices attached" sin dispositivos):

1. Listar AVDs disponibles:

emulator -list-avds

2. Iniciar el primer AVD disponible (o preguntar al usuario si hay varios):

emulator -avd <avd_name> -no-snapshot-load &

3. Esperar a que el emulador esté listo:

adb wait-for-device
adb shell getprop sys.boot_completed  # Esperar hasta que retorne "1"

Paso 3: Obtener info del dispositivo:

adb shell wm size      # Resolución (ej: 1080x2400)
adb shell wm density   # Densidad (ej: 440)

5. Figma MCP Verification (OBLIGATORIO)

Llamar whoami del Figma MCP para verificar autenticación.

Si falla: NO CONTINUAR. Informar al usuario y esperar resolución. Sin Figma MCP funcionando, este skill no puede ejecutarse.

---

Phase 1: Context Gathering

1. App State Check

Verificar si la app está instalada y corriendo:

adb shell pm list packages | grep <package.name>
adb shell pidof <package.name>

2. Build & Launch (si necesario)

./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n <package.name>/<activity.name>

3. User Input

Preguntar al usuario: "Pega el link de Figma del componente/pantalla que quieres implementar"

GUARDAR EL LINK: Escribir el link en un archivo para no perderlo:

echo "https://figma.com/..." > .figma-link

Si se pierde el contexto, leer de .figma-link. Nunca pedir el link dos veces al usuario.

---

Phase 2: Deep Execution

1. Extract from Figma MCP (UNA SOLA VEZ)

Hacer todas las peticiones necesarias al inicio y no repetirlas:

• get_metadata → jerarquía de componentes
• get_design_context → layout, spacing, estilos
• get_variable_defs → design tokens (colores, tipografía)
• get_screenshot → referencia visual (GUARDAR, no volver a pedir)

Guardar el screenshot de Figma para comparaciones posteriores. No volver a llamar get_screenshot a menos que el usuario indique que el diseño cambió.

2. Map Figma → Android

Unidades

Figma	Android
px (a 1x)	dp
px para texto	sp

Fórmula: Si Figma está a 1x, los valores son directamente dp/sp.

Colores

Figma hex → Android:

• colors.xml: <color name="primary">#FF6200EE</color>
• Compose: Color(0xFF6200EE)

Tipografía

Figma	Android XML	Compose
font-family	android:fontFamily	FontFamily
font-size	android:textSize="16sp"	fontSize = 16.sp
font-weight	android:textStyle="bold"	fontWeight = FontWeight.Bold
line-height	android:lineHeight	lineHeight = 24.sp
letter-spacing	android:letterSpacing	letterSpacing = 0.5.sp

Layout

Figma	Android XML	Compose
Auto Layout (vertical)	LinearLayout vertical	Column
Auto Layout (horizontal)	LinearLayout horizontal	Row
Frame	FrameLayout	Box
gap	android:layout_margin	Arrangement.spacedBy()
padding	android:padding	Modifier.padding()

3. Verify ALL Properties

NO ASUMIR NADA. VERIFICAR TODO:

Texto:

• fontFamily, fontSize (sp), fontWeight, lineHeight, letterSpacing
• color (incluyendo alpha)
• textAlign

Contenedores:

• width, height (dp o wrap/match)
• padding (start, top, end, bottom)
• margin
• background (color, drawable, shape)
• cornerRadius
• elevation/shadow

Imágenes/Iconos:

• tamaño exacto (dp)
• tint color (separado del texto!)
• scaleType/contentScale

4. Implement

Escribir el código en:

• Compose: app/src/main/kotlin/.../ui/
• XML: app/src/main/res/layout/

5. Build & Deploy

./gradlew assembleDebug && adb install -r app/build/outputs/apk/debug/app-debug.apk

Hot reload si está disponible (Compose con Live Edit).

6. UI Inspection & Navigation

Si necesitas navegar la app o encontrar elementos, usa los scripts de UIAutomator:

# Listar elementos interactivos de la pantalla
python scripts/ui_list.py

# Tap en elemento por texto
python scripts/ui_tap.py "Continuar"
python scripts/ui_tap.py "Iniciar sesión"

One-liner rápido (para probar sin scripts):

adb shell uiautomator dump /sdcard/ui.xml && adb pull /sdcard/ui.xml /tmp/ui.xml && grep -oP 'text="[^"]*"' /tmp/ui.xml | grep -v 'text=""' | sort -u

6.1 Documentar Navegación (IMPORTANTE)

Guardar un mapa de navegación para no olvidar cómo acceder a cada pantalla:

# Crear/actualizar archivo de navegación
cat >> .app-navigation.md << 'EOF'
## Pantalla: Login
- Desde: Splash (automático después de 2s)
- Tap "Iniciar sesión": bounds=[50,800][350,860] → centro (200, 830)

## Pantalla: Home
- Desde: Login → tap "Entrar"
- Tab "Perfil": bounds=[900,2200][1080,2300] → centro (990, 2250)
- Tab "Buscar": bounds=[360,2200][540,2300] → centro (450, 2250)

## Pantalla: Perfil
- Desde: Home → tab "Perfil"
- Botón "Editar": texto="Editar perfil"
EOF

Cada vez que descubras una ruta de navegación, DOCUMENTARLA. Si se pierde el contexto, leer .app-navigation.md para recordar cómo llegar a cada pantalla.

7. Screenshot del Emulador

adb shell screencap -p /sdcard/screen.png
adb pull /sdcard/screen.png ./screen_android.png
adb shell rm /sdcard/screen.png

8. Compare Screenshots

1. Usar el screenshot de Figma ya guardado (NO volver a llamar get_screenshot)
2. Comparar visualmente con screen_android.png
3. Verificar:
   • Colores exactos
   • Espaciados exactos
   • Tamaños exactos
   • Alineación
   • Tipografía

---

Phase 3: Recursive Refinement

Si hay CUALQUIER discrepancia (incluso 1dp):

1. Identificar exactamente qué está mal
2. Explicar la diferencia encontrada
3. Corregir el código
4. Rebuild: ./gradlew assembleDebug && adb install -r ...
5. Re-screenshot y comparar de nuevo
6. Repetir hasta perfección

Common Android Gotchas

• includeFontPadding en TextView (default true, puede agregar espacio extra)
• clipToPadding y clipChildren en contenedores
• System bars (status bar, navigation bar) afectan el layout
• windowSoftInputMode puede mover contenido
• Diferentes densidades requieren múltiples assets o vector drawables

---

Phase 4: User Review

Mostrar screenshot final y preguntar: "Este es el resultado. ¿Coincide con tu expectativa?"

Si el usuario da otro link de Figma → volver a Phase 2. Si el usuario reporta diferencias → investigar y corregir.

---

Commands Reference

ADB Essentials

# Dispositivos conectados
adb devices

# Screenshot
adb shell screencap -p /sdcard/s.png && adb pull /sdcard/s.png && adb shell rm /sdcard/s.png

# Tap en coordenadas
adb shell input tap <x> <y>

# Escribir texto
adb shell input text "<texto>"

# Scroll/Swipe
adb shell input swipe <x1> <y1> <x2> <y2> <duration_ms>

# Presionar botón
adb shell input keyevent <code>  # BACK=4, HOME=3, ENTER=66

# Info de pantalla
adb shell wm size
adb shell wm density

# Abrir app
adb shell am start -n <package>/<activity>

# Cerrar app
adb shell am force-stop <package>

# Instalar APK
adb install -r <path.apk>

# Logcat filtrado
adb logcat -s <TAG>

UIAutomator Scripts

Scripts para navegación de UI. Ver scripts/ para implementación.

# Listar elementos interactivos
python scripts/ui_list.py

# Tap por texto
python scripts/ui_tap.py "Texto del botón"

Propiedades del XML de UIAutomator:

• text - texto visible
• resource-id - ID único (ej: com.app:id/btn)
• bounds - coordenadas [left,top][right,bottom]
• clickable, enabled - estados

Gradle Essentials

# Build debug
./gradlew assembleDebug

# Build release
./gradlew assembleRelease

# Clean build
./gradlew clean assembleDebug

# Run tests
./gradlew test

# Lista de tareas
./gradlew tasks

---

ULTRA-THINK MODE: Tomarse el tiempo necesario. Perfección sobre velocidad. Un dp de diferencia es inaceptable.