⚡ Guía interactiva para diseñadores UX

Claude Code para
Diseñadores UX

Aprendé a usar Claude Code como tu copiloto de diseño. Desde capturar diseños en Figma hasta construir prototipos funcionales con Andes, todo desde la terminal.

claude — ~/proyecto-ux
🎨

De Figma a Código

Capturá cualquier diseño de Figma y convertilo en un prototipo funcional en minutos, no horas.

📦

Tu librería Andes

Accedé a componentes y tokens del design system de MELI directamente desde tu prompt.

🚀

Iteración rápida

Modificá, probá y refiná prototipos con lenguaje natural. Sin necesidad de saber programar.

1

Qué es Claude Code

Claude Code es un agente de IA que vive en tu terminal. A diferencia de ChatGPT o Claude web, no es solo un chat: tiene acceso directo a tus archivos, puede ejecutar comandos, usar Git, abrir el navegador, y conectarse a herramientas externas como Figma.

Pensalo como un compañero de trabajo que está sentado al lado tuyo y puede tocar tu computadora: lee tus archivos, escribe código, ejecuta comandos, y te muestra los resultados. Vos le decís qué querés y él lo hace.

¿En qué se diferencia?

❌ ChatGPT / Claude Web
- Solo puede chatear
- Vos copiás y pegás código
- No conoce tus archivos
- No puede ejecutar nada
- Cada vez arrancás de cero
✅ Claude Code (Terminal)
- Lee y edita tus archivos
- Ejecuta comandos reales
- Usa Git, npm, etc.
- Se conecta a Figma, Andes
- Conoce el contexto de tu proyecto

¿Cómo funciona?

Vos abrís la terminal, escribís claude y empezás a hablarle en español. Claude analiza tu proyecto, usa herramientas según lo que necesite, y te muestra el resultado.

🧑‍🎨 Diseñador
🤖 Claude Code
🎨 Figma MCP
📦 Andes MCP
🌐 Playwright
💡 Tip
No necesitás saber programar para usar Claude Code. Solo necesitás saber describir lo que querés. El agente se encarga de escribir el código por vos.
2

Setup y Configuración

Todo lo que necesitás para arrancar con Claude Code. Seguí los pasos en orden.

2a Instalación y primer uso

Primero, instalá Claude Code con este comando:

bash
curl -fsSL https://claude.ai/install.sh | bash

Después, navegá a la carpeta de tu proyecto y arrancá Claude:

bash
cd ~/mi-proyecto-ux
claude

La primera vez te va a pedir que te autentiques con tu cuenta de Anthropic. Seguí las instrucciones en pantalla — es un proceso rápido con el navegador.

ℹ️ Requisitos previos
Necesitás tener Node.js 18+ instalado. Si no lo tenés, descargalo de nodejs.org.
2b CLAUDE.md — Tu archivo de instrucciones

El archivo CLAUDE.md es como un manual de instrucciones personal para Claude. Lo ponés en la raíz de tu proyecto y Claude lo lee cada vez que arranca. Ahí definís tu contexto, preferencias y reglas.

Existen tres niveles:

  • Proyecto (./CLAUDE.md): instrucciones específicas para este proyecto
  • Usuario (~/.claude/CLAUDE.md): tus preferencias globales
  • Carpetas (./src/CLAUDE.md): instrucciones para una carpeta específica

Ejemplo CLAUDE.md para UX Designer en MELI

markdown
# Proyecto UX — Mercado Libre

## Rol
Soy diseñador UX/Product en Mercado Libre. No soy programador.
Explicame las cosas de forma simple.

## Stack de prototipos
- HTML + CSS + JS vanilla (archivos standalone)
- Usar componentes de Andes (nuestro design system)
- Los prototipos van en la carpeta /prototipos

## Design System: Andes
- Siempre consultar el MCP de Andes UI Library antes de construir
- Usar los tokens de diseño (colores, tipografías, espaciados)
- Preferir componentes existentes antes de inventar nuevos

## Figma
- Cuando trabaje con Figma, recordar: node-id usa formato X:Y (no X-Y)
- Si falla con nodeId, reintentar sin él

## Preferencias
- Idioma: español rioplatense (vos/voseo)
- Cuando generes HTML, hacelo autocontenido (un solo archivo)
- Abrí los prototipos en el navegador automáticamente
- Explicame qué hiciste después de cada cambio
💡 Tip
Cuanto más contexto le des en el CLAUDE.md, mejores resultados vas a obtener. Es como briefear a un nuevo compañero de equipo.
2c Configuración de MCP Servers

Los MCP Servers (Model Context Protocol) son plugins que le dan superpoderes a Claude. Se configuran en el archivo .mcp.json en la raíz del proyecto.

json
{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "figma-developer-mcp", "--stdio"],
      "env": {
        "FIGMA_API_KEY": "tu-api-key-de-figma"
      }
    },
    "andes-ui-library": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/andes-mcp"],
      "env": {}
    },
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-playwright"]
    }
  }
}
⚠️ API Key de Figma
Para obtener tu API key de Figma: Figma → Settings → Personal Access Tokens → Generate new token. Nunca compartas tu API key ni la subas a Git.
2d Permisos y seguridad básica

Claude Code te pide permiso antes de ejecutar acciones. Hay tres niveles:

  • Leer archivos: siempre permitido
  • Escribir/editar archivos: te pide confirmación
  • Ejecutar comandos (bash): te pide confirmación

Podés configurar qué se permite automáticamente y qué no. Para prototipos UX, generalmente querés permitir que escriba archivos HTML/CSS/JS y que abra el navegador.

bash
# Ver los permisos actuales
claude config list

# Permitir escritura de archivos automáticamente
claude config set autoApprove "write"
💡 Tip
Si no estás seguro, dejá los permisos por defecto. Claude te va a ir pidiendo permiso uno por uno y podés aceptar o rechazar caso a caso.
3

Conceptos Fundamentales

Antes de meternos en las recetas, entendamos cómo piensa y funciona Claude Code.

📋

Plan Mode vs Ejecución

Cuándo planificar y cuándo ejecutar

Claude Code tiene dos modos principales:

  • Plan Mode (Shift+Tab): Claude investiga, lee archivos, y te propone un plan antes de hacer nada. Ideal para tareas complejas o cuando no estás seguro de qué querés.
  • Ejecución directa: Claude directamente lee, escribe y ejecuta. Usalo cuando sabés exactamente lo que querés.
📋 Usá Plan Mode cuando...
- Es un prototipo nuevo y grande
- No sabés por dónde arrancar
- Querés ver opciones antes
- Estás explorando tu design system
⚡ Ejecución directa cuando...
- Es un cambio puntual
- Querés agregar un componente
- Necesitás corregir algo rápido
- Sabés exactamente qué pedirle
💡 Atajo
Presioná Shift+Tab para alternar entre Plan Mode y Ejecución dentro de Claude Code.
🔧

Herramientas que usa Claude

Read, Write, Bash, MCPs y más

Claude Code tiene herramientas internas que usa automáticamente según lo que necesite. No tenés que llamarlas vos — solo describí lo que querés.

Herramienta Qué hace Ejemplo de uso
Read Lee archivos de tu proyecto Leé el archivo index.html
Write Crea o sobreescribe archivos Creá un nuevo prototipo
Edit Modifica partes de un archivo Cambiá el color del botón
Bash Ejecuta comandos en la terminal Abrí el HTML en el browser
Glob/Grep Busca archivos y contenido Buscá todos los prototipos
MCPs Herramientas externas (Figma, Andes...) Mirá el diseño en Figma
💬

Cómo comunicarte con Claude

Prompts buenos vs malos, con ejemplos

La calidad de lo que obtenés depende directamente de cómo le pedís las cosas. Acá van algunos principios:

❌ Prompt vago
"Haceme una página"
✅ Prompt con contexto
"Creá un prototipo HTML del flujo
de checkout de MercadoLibre.
Usá componentes de Andes.
Incluí: carrito, datos de envío,
y confirmación de compra.
Abrilo en el navegador cuando
termines."
❌ Demasiado genérico
"Hacelo lindo"
✅ Específico y accionable
"Cambiá el fondo a #EEEEEE,
hacé el botón primario más grande
(48px de alto), y agregá 24px
de spacing entre las secciones."
💡 Regla de oro
Escribí tus prompts como si estuvieras dándole indicaciones a un diseñador jr. que es muy capaz pero no conoce tu proyecto. Cuanto más contexto, mejor resultado.
🧠

Ventana de contexto

/compact, /clear, y cómo manejar la memoria

Claude tiene una "ventana de contexto" — la cantidad de información que puede tener en mente al mismo tiempo. Pensalo como la memoria de trabajo.

  • /compact — Comprime la conversación actual para liberar espacio. Usalo cuando venís trabajando hace rato y sentís que Claude se empieza a confundir.
  • /clear — Borra toda la conversación y empezás de cero. Útil cuando cambiás de tarea completamente.
💡 Tip
Si una sesión se hace muy larga y Claude empieza a repetirse o confundirse, usá /compact. Si cambiás de proyecto, usá /clear.
4

Integraciones MCP

Los MCPs son el superpoder de Claude Code. Cada uno le da acceso a una herramienta externa. Explorá cada integración en las pestañas.

Figma MCP

Conectá Claude Code con Figma de forma bidireccional: podés leer diseños, capturar screenshots, obtener metadata — y ahora también crear diseños directamente en Figma y generar diagramas en FigJam.

✨ Nuevo: Crear diseños en Figma
Ahora podés pedirle a Claude que cree diseños directamente en Figma. Describí una interfaz y Claude la genera como layers reales de Figma que podés editar. Funciona solo con Claude Code y requiere el servidor MCP remoto de Figma.

Leer y analizar

Acción Prompt de ejemplo
Obtener screenshotget_screenshot Capturá el diseño de esta URL de Figma: [url]
Ver metadataget_metadata Obtené la metadata del componente en Figma: [url]
Contexto de diseñoget_design_context Analizá el contexto de diseño de esta pantalla: [url]
Variablesget_variable_defs Mostrá las variables de diseño del archivo: [url]

Crear y generar

Acción Prompt de ejemplo
Crear diseño en Figmagenerate_figma_design Creá en Figma una pantalla de login con email, contraseña y botón de ingreso. Usá el archivo: [url]
Crear diagrama en FigJamgenerate_diagram Generá un diagrama de flujo del proceso de checkout en FigJam: [url]
Leer diagrama de FigJamget_figjam Leé el diagrama de FigJam y explicame el flujo que muestra: [url]

Code Connect y handoff

Herramientas para conectar componentes de Figma con el código del proyecto, facilitando el handoff entre diseño y desarrollo.

Acción Prompt de ejemplo
Ver mapeos existentesget_code_connect_map Mostrá los mapeos de Code Connect entre Figma y el código: [url]
Detectar mapeos sugeridosget_code_connect_suggestions Analizá los componentes de Figma y sugerí mapeos con el código del proyecto: [url]
Agregar mapeoadd_code_connect_map Conectá el componente Button de Figma con el componente AndesButton del código: [url]
Confirmar mapeossend_code_connect_mappings Confirmá y enviá los mapeos de Code Connect que revisamos

Utilidades

Acción Prompt de ejemplo
Generar reglas de design systemcreate_design_system_rules Generá un archivo de reglas para el design system basado en Figma: [url]
Verificar usuario conectadowhoami ¿Con qué cuenta de Figma estás conectado?
⚠️ Formato de node-id
Las URLs de Figma usan node-id=X-Y (con guión), pero la API necesita X:Y (con dos puntos). Claude hace esta conversión automáticamente si configuraste bien tu CLAUDE.md. Si una llamada falla con nodeId, se reintenta sin él (lo que crea una página nueva).

Andes UI Library MCP

Acceso directo al design system de Mercado Libre. Podés consultar componentes, ver sus props, y construir interfaces usando los tokens oficiales.

¿Qué podés hacer?

  • Consultar componentes disponibles y sus variantes
  • Ver props, tokens de color, tipografía y espaciado
  • Obtener ejemplos de uso de cada componente
  • Generar código que respete el design system
prompt
Consultá en el MCP de Andes cuáles son los componentes
disponibles para formularios. Necesito inputs, selects
y botones. Mostrá las props principales de cada uno
y un ejemplo de uso.
prompt
Usá los tokens de Andes para crear una card de producto
con: imagen, título, precio, y botón de comprar.
Asegurate de usar los colores, tipografías y
espaciados del design system.
💡 Tip
Siempre pedile a Claude que consulte Andes primero antes de construir. Así te asegurás de que use los componentes y tokens correctos, no que invente estilos propios.

Playwright MCP

Playwright le da a Claude la capacidad de abrir un navegador real, tomar screenshots, hacer click en elementos, llenar formularios, y navegar por páginas. Es tu herramienta de preview y testing.

Casos de uso para diseñadores

  • Preview en vivo: Abrí tu prototipo y verificá cómo se ve
  • Screenshots: Capturá el estado actual para compartir
  • Testing de flujos: Simulá clicks y navegación de usuario
  • Responsive: Verificá cómo se ve en distintos tamaños
prompt
Abrí el archivo prototipo.html en el navegador con
Playwright. Tomá un screenshot a 1440px de ancho y
otro a 375px (mobile). Decime si ves algún problema
de layout.

Combinando MCPs — El flujo completo

El verdadero poder aparece cuando combinás los tres MCPs en un flujo integrado. Acá te mostramos el flujo ideal de diseño a prototipo:

1. Capturá de Figma
2. Consultá Andes
3. Claude construye
4. Preview con Playwright
prompt
Necesito crear un prototipo funcional. Seguí estos pasos:

1. Capturá el diseño de Figma: [URL del diseño]
2. Consultá en Andes qué componentes necesitamos
3. Construí el HTML usando los tokens y componentes de Andes
4. Abrí el resultado en el navegador y tomá un screenshot
5. Mostrámelo y decime qué componentes de Andes usaste
💡 Flujo pro
Este es el flujo que más vas a usar. Guardá este prompt como template y adaptalo a cada proyecto. Con práctica, un prototipo completo te puede llevar 15-20 minutos en vez de horas.
5

Recetas / Playbooks

Flujos probados paso a paso. Cada receta incluye los prompts exactos para que copies y pegues.

Intermedio ~15 min

Crear prototipo desde Figma

Capturá un diseño de Figma y convertilo en HTML funcional con Andes.

1
Abrí Claude Code en tu proyecto
Navegá a la carpeta del proyecto y ejecutá claude.
2
Pedile que capture el diseño de Figma
prompt
Mirá este diseño en Figma: [URL].
Capturá el screenshot y analizá la estructura
de la pantalla. Listá los componentes que identificás.
3
Pedile que construya el prototipo
prompt
Ahora creá un HTML autocontenido que reproduzca
este diseño. Consultá Andes para usar los componentes
correctos. Guardalo como prototipo-checkout.html
y abrilo en el navegador.
4
Iterá sobre el resultado
Pedile ajustes puntuales: "Hacé el header más chico", "Cambiá el color del CTA", etc.
Básico ~10 min

Componente con tokens del design system

Construí un componente respetando los tokens de Andes al pie de la letra.

1
Consultá los componentes disponibles
prompt
Consultá en Andes el componente de Card. Decime
qué variantes tiene, sus props, y los tokens de
diseño que usa (colores, tipografía, espaciado,
bordes).
2
Pedile que lo construya
prompt
Creá una card de producto usando exactamente
los tokens que encontraste en Andes. Incluí:
imagen de placeholder, título, precio con
descuento, y botón de agregar al carrito.
3
Verificá el resultado
Pedile que abra el componente en el navegador y compare con el diseño original.
Avanzado ~30 min

Demo interactiva de flujo de usuario

Construí un prototipo navegable multi-paso con transiciones y estados.

1
Definí el flujo completo
prompt
Necesito un prototipo interactivo del flujo de compra
de MercadoLibre. Tiene 4 pasos:
1. Carrito (lista de productos con cantidades)
2. Datos de envío (formulario con dirección)
3. Método de pago (selección entre opciones)
4. Confirmación (resumen + botón confirmar)

Cada paso tiene botón 'Siguiente' y 'Volver'.
Usá componentes de Andes. Hacelo en un solo HTML
autocontenido con transiciones suaves entre pasos.
2
Testeá con Playwright
prompt
Abrí el prototipo en el navegador y simulá el flujo
completo: navegá por los 4 pasos, completá datos
de ejemplo en los formularios, y tomá un screenshot
de cada paso. Decime si encontrás algún problema
de usabilidad.
3
Iterá con feedback visual
Pedí cambios basándote en los screenshots: "En el paso 2, el form se ve muy apretado. Agregá más spacing."
Básico ~10 min

Generación rápida de variantes A/B

Generá múltiples versiones de un componente para comparar y decidir.

1
Pedí las variantes
prompt
Creá 3 variantes de una hero section para la home
de MercadoLibre:

Variante A: Hero con imagen grande de fondo y CTA centrado
Variante B: Hero split layout (texto izq, imagen der)
Variante C: Hero minimalista solo con texto y buscador

Generá 3 archivos HTML separados: variante-a.html,
variante-b.html, variante-c.html. Usá tokens de Andes.
2
Compará visualmente
prompt
Abrí las 3 variantes en el navegador, tomá screenshots
de cada una, y hacé una comparación. ¿Cuál te parece
que tiene mejor jerarquía visual?
Intermedio ~20 min

Prototipos para testing de usabilidad

Armá prototipos interactivos listos para sesiones de user testing.

1
Definí el escenario de testing
prompt
Necesito un prototipo para una sesión de user testing.
El escenario es: 'El usuario quiere cambiar su
dirección de envío en MercadoLibre'.

El prototipo debe:
- Empezar en la pantalla de 'Mi cuenta'
- Tener navegación funcional hasta 'Mis direcciones'
- Permitir editar una dirección existente
- Mostrar confirmación de cambio
- Ser lo más realista posible (datos mock creíbles)

Usá componentes de Andes. Hacelo autocontenido.
2
Verificá el flujo completo
Usá Playwright para recorrer el flujo y verificar que todo funcione antes de la sesión.
3
Ajustá detalles
"Agregá un toast de confirmación cuando se guarde la dirección" o "Hacé que el botón de volver vuelva a la pantalla anterior".
Intermedio ~15 min

Auditoría de accesibilidad

Revisá la accesibilidad de tu prototipo y corregí problemas automáticamente.

1
Pedí la auditoría
prompt
Hacé una auditoría de accesibilidad del archivo
prototipo.html. Verificá:
- Contraste de colores (WCAG AA mínimo)
- Atributos alt en imágenes
- Labels en formularios
- Navegación por teclado
- Roles ARIA correctos
- Jerarquía de headings

Listá los problemas encontrados y corregí
los que puedas automáticamente.
2
Verificá las correcciones
Pedile que abra el prototipo y confirme que las correcciones se aplicaron bien.
6

Tips y Mejores Prácticas

5 principios de prompting efectivo

1️⃣

Sé específico con el resultado esperado

Describí exactamente qué querés obtener
❌ Vago
"Haceme un formulario"
✅ Específico
"Creá un formulario de registro
con: nombre, email, contraseña,
confirmación de contraseña, y
checkbox de términos. Usá
componentes de Andes. Validá
que el email tenga formato
correcto y que las contraseñas
coincidan."
2️⃣

Dá contexto sobre el proyecto

Claude trabaja mejor cuando entiende el panorama completo

Antes de hacer tu pedido, contale el contexto:

  • "Estoy trabajando en el flujo de checkout de MercadoLibre"
  • "Es para una sesión de user testing la semana que viene"
  • "Los usuarios son compradores frecuentes de 25-45 años"

Este contexto ayuda a Claude a tomar mejores decisiones sobre el diseño y la implementación.

3️⃣

Mencioná el design system explícitamente

Pedile que consulte Andes antes de construir

Siempre incluí frases como:

  • "Consultá Andes antes de construir"
  • "Usá los tokens del design system"
  • "Asegurate de usar componentes de Andes, no inventes"

Si no lo mencionás, Claude puede inventar estilos propios que no coincidan con tu design system.

4️⃣

Iterá en pasos chicos

Mejor varios pedidos simples que uno gigante

En vez de pedir todo de una, hacelo en pasos:

  1. Primero: "Armá la estructura base del layout"
  2. Después: "Ahora agregá el header con navegación"
  3. Después: "Agregá el formulario principal"
  4. Después: "Sumá las validaciones"

Esto te da más control y permite corregir el rumbo antes de avanzar.

5️⃣

Pedí que te explique qué hizo

Aprendé mientras trabajás

Después de cada tarea, pedile un resumen:

  • "Explicame qué hiciste y por qué"
  • "¿Qué componentes de Andes usaste?"
  • "¿Qué decisiones de diseño tomaste?"

Esto no solo te ayuda a entender el resultado, también te enseña sobre código y el design system. Con el tiempo, vas a poder hacer pedidos más precisos.

¿Cuándo usar Plan Mode?

¿Es una tarea compleja o con múltiples pasos?
↓ Sí
Usá Plan Mode (Shift+Tab)
↓ No
¿Sabés exactamente qué querés?
↓ Sí
Ejecución directa
↓ No
Usá Plan Mode

Errores comunes y cómo evitarlos

Error Solución
No mencionar el design system Siempre incluí "Consultá/Usá Andes" en tu prompt
Sesiones demasiado largas Usá /compact cada ~30 minutos o cuando notes degradación
No tener CLAUDE.md Creá uno con tu contexto — mejora drásticamente los resultados
Prompts demasiado vagos Incluí: qué, cómo, con qué herramientas, y dónde guardar
No verificar el output Siempre pedí que abra el resultado en el navegador
Pedir todo de una Dividí en pasos: estructura → contenido → interacción → polish

Cheatsheet de atajos y comandos

Shift+Tab Alternar Plan Mode
/compact Comprimir contexto
/clear Limpiar conversación
/help Ver ayuda
Esc Cancelar acción actual
/config Abrir configuración
/cost Ver costo de la sesión
/doctor Diagnosticar problemas

CLAUDE.md avanzado para proyecto UX

Un ejemplo más completo para proyectos de diseño con múltiples prototipos:

markdown
# Proyecto: Redesign Checkout MercadoLibre

## Contexto del proyecto
Estamos rediseñando el flujo de checkout de MercadoLibre.
El objetivo es reducir el abandono de carrito en un 15%.
Target: compradores frecuentes, mobile-first.

## Mi rol
Soy UX Designer. No soy programador.
Explicame las cosas de forma simple y visual.

## Estructura del proyecto
/prototipos/          → HTML autocontenidos
/prototipos/v1/       → Primera iteración
/prototipos/v2/       → Segunda iteración
/screenshots/         → Capturas de referencia
/assets/              → Imágenes y recursos

## Reglas de diseño
- Siempre consultar Andes UI Library MCP antes de construir
- Mobile-first (375px), luego desktop (1440px)
- Usar tokens de Andes para colores, tipografía, spacing
- Los prototipos deben ser autocontenidos (1 archivo HTML)
- Incluir datos mock realistas (nombres argentinos, precios en ARS)

## Flujos a prototipar
1. Carrito → Envío → Pago → Confirmación
2. Editar dirección de envío
3. Aplicar cupón de descuento
4. Error en pago y retry

## Cuando generes prototipos
- Abrí el resultado en el navegador automáticamente
- Tomá un screenshot con Playwright
- Explicame qué componentes de Andes usaste
- Listá cualquier decisión de diseño que hayas tomado

## Figma
- URLs de Figma: node-id usa X:Y (no X-Y)
- Si falla con nodeId, reintentar sin él

## Preferencias
- Idioma: español rioplatense (vos/voseo)
- Preferir componentes simples y claros
- Sin animaciones excesivas en prototipos
- Accesibilidad WCAG AA como mínimo