Stitch CLI: Google trae el diseño de UI a la terminal (y a tu agente)

Google presentó Stitch CLI, una herramienta de línea de comandos (@google/stitch) que lleva el diseño de UI generativo de Stitch a la terminal y a tu agente de código. La promesa oficial: "you can go from a blank folder to a live, interactive design on localhost in a couple of minutes". - Fuente: Stitch CLI Overview

No es solo un generador de pantallas. El CLI cubre tres frentes: generar y editar pantallas, mantener un sistema de diseño legible por agentes (DESIGN.md), y conectar tu repositorio real para prototipar sobre tu producto. Esta es la guía completa, condensada desde toda la documentación.

Imagen: Google (Stitch)

Instalación y login

Requiere Node.js 20 o superior.

# terminal
npm install -g @google/stitch
stitch --version

Si prefieres no instalarlo, corre npx @google/stitch. Para autenticarte, un solo login de Google OAuth habilita tanto tus proyectos del Canvas como los flujos de workspace:

stitch login

En entornos headless o CI no hay navegador: define STITCH_API_KEY o guarda una API key en la config global (stitch config set apiKey "tu_api_key" --global). El estado de sesión lo consultas con stitch status. - Fuente: Stitch CLI Overview

El skill /stitch: el CLI dentro de tu agente

Esta es la pieza más interesante del lanzamiento. El CLI trae un skill empaquetado para que tu agente de código sepa manejarlo por ti:

stitch agent-skills add --user

Funciona con Claude Code, Cursor, Gemini CLI y Antigravity. Una vez instalado, invocas /stitch dentro del chat del agente para generar pantallas, extraer y sincronizar un DESIGN.md, o auditar tu app corriendo:

/stitch Create a new Stitch project called "Checkout Redesign" and generate a clean desktop order summary screen.

• Fuente: Stitch CLI Overview

Tu primera pantalla desde la terminal

Todo lo que hace /stitch también lo puedes hacer a mano. Empiezas creando un proyecto y pinning el directorio para no repetir --project:

stitch create project --title "Checkout Redesign"
stitch config set project <project-id>

Luego generas una pantalla desde un prompt:

stitch generate screen \
  --title "Order Summary" \
  --device DESKTOP \
  --prompt "A clean two-column checkout summary on warm paper (#FAF8F5) with itemized billing, shipping selector, and a primary payment button"

Y para ver el resultado: stitch serve levanta un servidor de preview local y stitch open project abre el Canvas en el navegador. - Fuente: Stitch CLI Overview

Variaciones y edición dirigida

Cuando exploras, conviene pedir varias opciones de golpe. stitch generate variants genera de 1 a 5 variantes y controla dos ejes:

• Creative Range (--creative-range): REFINE para ajustes finos (fuente, espaciado, color), EXPLORE o REIMAGINE para cambios grandes.
• Aspects (--aspects): LAYOUT, COLOR_SCHEME, IMAGES, TEXT_FONT, TEXT_CONTENT.

stitch generate variants \
  --screen <screen-id> \
  --count 3 \
  --creative-range EXPLORE \
  --aspects LAYOUT,COLOR_SCHEME \
  --prompt "Explore a compact high-density layout and a high-contrast dark theme"

Cuando ya tienes una pantalla que te gusta, cambias de exploración a precisión. La regla es un cambio a la vez, específico:

stitch edit screen <screen-id> \
  --prompt "Replace the top KPI cards with a compact single-line horizontal ticker and add a date-range selector in the top-right header."

Para bajar el HTML a tu proyecto: stitch get screen <screen-id> --code --output ./screens/overview.html. - Fuente: Generate & Edit Screens

El flujo real con tu agente: ancla, encuadre, interacción

La documentación es explícita sobre por qué los resultados genéricos salen genéricos: si empiezas de un prompt en blanco, obtienes una paleta de colores genérica. El flujo que ellos recomiendan tiene tres tiempos.

1. Ancla con artwork real. Genera primero la imagen que va dentro de tu interfaz con Gemini 3 Pro Image (gemini-3-pro-image) en Google AI Studio, en relación 1:1 y pidiendo que llene el marco de borde a borde. Luego la subes al proyecto:

stitch upload screen ./hudson-album-art.png --title "Late Sun on the Hudson"

Pasar la URL de esa imagen en el prompt hace que Stitch la incruste píxel por píxel en vez de inventar un placeholder.

2. Encuadra en el primer prompt. Cuando pides "una app entera", el modelo llena cada esquina de status dots y badges falsos. La receta de la doc es un prompt de cuatro tiempos: [Canvas] (qué va y qué no), [Principles] (cada elemento debe ganarse su lugar), [Artwork] (tu imagen subida) y [Playback]/contenido (los datos exactos).

3. Hazlo interactivo en localhost. Como Stitch entrega HTML, CSS y JavaScript reales, no te quedas en el layout estático. Levantas stitch serve y pides interacción sobre el DOM vivo: que al hacer clic en una canción cambie la carátula, el color del vinilo y la barra de progreso.

Imagen: Google (Iterate with Coding Agents)

• Fuente: Iterate with Coding Agents

DESIGN.md: el sistema de diseño que tu agente puede leer

La idea más fuerte del lanzamiento tiene que ver con la identidad visual. Tu identidad vive en un Figma, un PDF de marca o la cabeza de un diseñador. Ninguno de esos es legible por un agente. DESIGN.md lo cambia: es un documento de sistema de diseño en texto plano que humanos y agentes pueden leer, editar y hacer cumplir.

La doc lo plantea como el "tercer archivo" del proyecto:

Es un artefacto vivo, no un config estático: el agente lo genera, tú lo refinas, y se re-aplica a las pantallas mientras iteras. Hay tres caminos para crearlo, de lo más fácil a lo más preciso: dejarlo generar por el agente desde una descripción de vibe, derivarlo de tu branding (le das una URL o una imagen y extrae paleta, tipografía y patrones), o escribirlo a mano. - Fuente: DESIGN.md Overview

La especificación de DESIGN.md

Un DESIGN.md tiene dos capas: YAML front matter con los tokens (valores exactos que el agente usa) y un cuerpo markdown con la razón de ser de esos valores. Los tokens manda; la prosa da contexto.

---
version: alpha
name: Daylight Prestige
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
rounded:
  sm: 4px
  md: 8px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    rounded: "{rounded.md}"
    padding: 12px
---

Puntos clave de la spec:

• Tipos de token: color (# + hex sRGB), dimensión (48px, -0.02em), referencia a otro token ({colors.primary}) y tipografía (objeto compuesto con fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation).
• Referencias: cualquier token puede apuntar a otro con {ruta.del.token}. Dentro de components sí se permite referenciar valores compuestos (por ejemplo {typography.label-md}).
• Orden de secciones canónico: Overview (o Brand & Style), Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Puedes omitir las que no apliquen, y añadir secciones propias del dominio.
• Extensible por diseño: la spec dice ser "una base, no una prescripción". Una sección desconocida (## Iconography), un color con nombre raro o un valor de spacing no válido se aceptan; el único error fatal es un heading de sección duplicado.
• Nombres recomendados: colores primary, secondary, tertiary, neutral, surface, on-surface, error; tipografía headline-*, body-*, label-*; radios none, sm, md, lg, xl, full.
• Fuente: DESIGN.md Specification

Validar, comparar y exportar con @google/design.md

La spec tiene su propio CLI, que valida contra el formato, detecta referencias rotas, chequea contraste WCAG y exporta tokens. Todo devuelve JSON estructurado que un agente puede accionar.

# lint: valida estructura y corre 8 reglas
npx @google/design.md lint DESIGN.md

# diff: qué tokens cambiaron entre dos versiones y si hay regresión
npx @google/design.md diff DESIGN.md DESIGN-v2.md

# export: tokens a Tailwind o a DTCG (W3C Design Tokens)
npx @google/design.md export --format tailwind DESIGN.md
npx @google/design.md export --format dtcg DESIGN.md

El linter corre 8 reglas:

También existe como librería TypeScript (accedes a report.findings, report.summary, report.designSystem, report.tailwindConfig). - Fuente: Validate with the CLI y Linting Rules

Captura tu app real

Si vas a rediseñar una página existente, no empieces de un canvas en blanco: sube tu UI real. La captura y la subida están separadas a propósito, para que inspecciones en disco antes de mandar nada.

# app client-rendered (React, Next.js, Vite, Vue) en headless Chrome
stitch capture browser --url "http://localhost:3000/checkout" --wait-for "#checkout-root" -o .stitch/checkout.html

# HTML servido por HTTP o un build estático
stitch capture port --port 5173 --route "/dashboard" -o .stitch/dashboard.html
stitch capture file ./dist/index.html -o .stitch/index.html

Pasar -o escribe dos archivos: el HTML normalizado y un screenshot de verificación de 1280x800.

Pasar un login sin tocar tu código tiene tres opciones, todas limpias:

1. Iniciar sesión en la pestaña abierta y congelarla sin recargar: stitch capture browser --page 1 -o .stitch/dashboard.html.
2. Pasar cookies y localStorage guardados: --storage .stitch/storage.json.
3. Correr un script de login antes del snapshot: --prepare .stitch/signin.js.

Y al subir, marcas la ruta como referencia canónica: stitch upload screen .stitch/checkout.html --route "/checkout" --title "Checkout". - Fuente: Capture Live Apps

Design review local

Aquí el CLI se vuelve un linter de diseño. Compara tu app corriendo contra tu DESIGN.md y todo corre local, sin llamadas a la nube:

stitch capture browser --url "http://localhost:5173/dashboard" -o .stitch/captured-dom.html

En vez de consejos vagos, obtienes una lista priorizada de hallazgos anclados a tus selectores CSS, regiones del screenshot y reglas del DESIGN.md. El agente pausa para que elijas qué arreglar primero. Cuatro chequeos clave: tokens de color y superficie (¿se colaron grises arbitrarios?), tipografía y numerales, ritmo espacial (grid de 4px/8px) y contención visual (¿aparecieron status dots o pills donde sobraba texto plano?). Si la auditoría destapa un problema de layout, subes el snapshot al Canvas y pruebas opciones antes de tocar tu app. - Fuente: Audit App UI

Workspaces: cuando el diseño mira tu repositorio

Generar pantallas sueltas sirve para empezar algo nuevo. Para que Stitch entienda tu app real (rutas, navegación, componentes), conectas el repo a un Workspace. Primero habilitas la feature una vez:

stitch enable loop

Esto desbloquea todos los comandos de workspace (workspace, priority, insight, solution, context, upload code, upload file, connect, github) y actualiza el skill /stitch con el playbook de onboarding. Luego, en tres pasos:

stitch create workspace --title "Acme Web App"
stitch config set workspace <workspace-id>

stitch upload code .                 # sube tu working tree sin instalar GitHub App
# o conecta GitHub:
stitch github login && stitch github repos
stitch edit workspace <workspace-id> --add-repo https://github.com/<owner>/<repo>

stitch loop link --project <project-id>   # ata el Canvas al workspace

Si tu equipo guarda contexto en otras herramientas, stitch connect --list muestra el catálogo de integraciones y webhooks. - Fuente: Connect a Repository

Priorities y contexto

En un Workspace, una priority no es un ticket ("cambia el botón a azul"). Es un objetivo de diseño permanente que le dice a Stitch qué tipo de mejoras de UX buscar en todas tus rutas. El CLI trae una plantilla lista:

stitch create priority --template ui-prototyping

Esto hace dos cosas a la vez: crea la priority con autonomía CREATE_SUGGESTIONS (Stitch propone insights, specs y prompts de diseño de forma continua) y sincroniza tres skills del workspace (design-synthesis, insight-guidelines, assessment-guidelines) para enfocar a los agentes en prototipado visual en vez de lints genéricos de código. Puedes afinar el objetivo con --objective:

stitch create priority --template ui-prototyping \
  --objective "Transform passive schedule and booking tables across /schedule and /venues into tactile, direct-manipulation surfaces."

La doc es clara con el criterio: apunta a resultados que atraviesan varias rutas, no a tareas de una línea. Y para dar contexto, subes specs y notas: stitch upload file ./specs/checkout-prd.pdf o stitch create context --title "Checkout Flow Goals" --description "...". - Fuente: Priorities & Context

Prototipos desde tu codebase

Con el repo conectado y una priority activa, Stitch analiza tus rutas en segundo plano para encontrar lecturas pasivas, cuellos de botella de flujo y oportunidades de layout. La síntesis inicial tarda unos 15 minutos.

stitch find insights          # oportunidades ancladas a rutas
stitch get insight <insight-id>
stitch find solutions         # cada insight produce una o más soluciones
stitch get solution <solution-id>

Cada solución es una spec completa: metáfora de dominio, reglas del DESIGN.md y un prompt calibrado anclado a tu pantalla de referencia. Tomas ese prompt y generas el prototipo en el Canvas:

stitch generate screen \
  --title "Interactive Schedule Workbench" \
  --device DESKTOP \
  --prompt "<prompt from stitch get solution>"

• Fuente: Codebase Prototypes

La referencia de comandos (lo esencial)

El CLI expone verbos de recurso (find, get, create, edit, delete, generate, open, url) más los comandos de Canvas, captura y configuración. En total, 23 comandos:

Tres detalles útiles:

• stitch url imprime la URL canónica del Canvas (la doc advierte: "never guess URLs").
• stitch mcp arranca el servidor MCP del CLI (mcp start por stdio) o lo registra en tu editor (mcp install).
• --model en edit/generate deja elegir entre GEMINI_3_8_FLASH y GEMINI_3_5_FLASH_LITE.

Casi todo comando acepta los flags globales: --json, --format, --workspace/-w, --project/-p, --debug, --trace (traza HTTP y reproducción cURL), --fields, --no-cache y --dry-run en las mutaciones. - Fuente: CLI Command Reference

Por qué importa

Tres lecturas de todo esto:

1. DESIGN.md convierte el diseño en algo versionable y legible por máquinas. Es el mismo movimiento que AGENTS.md hizo con las instrucciones de código, pero para la identidad visual. Que un linter valide contraste WCAG y referencias rotas en CI es un cambio real de categoría.
2. Local-first por defecto. El design review corre sin llamadas a la nube y la captura es tuya en disco antes de subir nada. Para equipos con restricciones de datos, eso importa.
3. El puente web × AI. El CLI no compite con tu agente: lo alimenta. Con /stitch, MCP y DESIGN.md, el diseño entra al mismo flujo donde ya viven tu código y tus tests.

Para cerrar

Stitch CLI es más que un generador de pantallas: es una apuesta a que el diseño viva donde vive el código, en texto plano y con un agente capaz de leerlo. Si ya usas un agente de código, el primer paso es stitch agent-skills add --user y pedirle /stitch que extraiga un DESIGN.md de tu repo actual.

Fuente original: Stitch CLI Overview (documentación oficial de Google Stitch).

¿Probarías DESIGN.md en tu proyecto, o lo ves como otra capa de configuración que se va a desincronizar? Cuéntame en los comentarios.

---