Antes de que una sola línea de código se escriba, cada pantalla se dibuja como un mockup — el plano. Esta guía muestra la maniobra completa de /design-system: cómo, historia por historia, se produce ese plano con una herramienta de diseño, se entrega a la IA, y se convierte en el contrato visual que guía /sprint-development.
Qué debe hacer el usuario en esa pantalla.
Se dibuja en una herramienta externa. La IA no lo inventa.
La IA mapea el mockup a la historia.
Se construye contra el plano, no a ciegas.
El error más común es mezclar el sistema de diseño con el diseño de pantallas. Son dos artefactos, con dos dueños y dos consumidores distintos — y de hecho, dos "drop zones" físicas distintas en el repo.
Los tokens: paleta, tipografía, espaciado, radios, componentes. La "voz visual" del producto entero.
La spec por pantalla (§4) + el mapa Historia → Pantalla (§8). Dice qué pantalla renderiza cada historia y cómo debe verse.
No se diseñan todas las pantallas de golpe al inicio. Se diseña just-in-time: las pantallas de un feature se dibujan justo antes de su sprint. Así el plano llega fresco y ya alineado con la UI viva.
Cada historia de usuario nueva que renderiza interfaz debería tener su propio mockup — siempre que sea posible. Las historias puramente de backend no tienen pantalla (se marcan con — en el mapa). Cuando /sprint-development topa una historia de UI sin fila en §8, te frena y te manda a diseñar ese mockup primero — es literalmente la Regla 14 (UI Fidelity Contract) del repo.
Tomás una historia de UI. /sprint-development la busca en el mapa Historia → Pantalla (§8 del master design plan).
Sin fila en §8 → el flujo se detiene. Volvés a /design-system para producir el mockup de ese lote de pantallas. Es el patrón universal de handoff (siguiente sección).
La IA lee el mockup, escribe la spec de pantalla (§4) y agrega la fila al mapa (§8). Te muestra la lista de pantallas para que la confirmes antes de guardar.
Recién ahí /sprint-development implementa la historia — abriendo la spec de §4 y respetando los tokens de DESIGN.md. Fidelidad al mockup, sin refactors de backend.
Este handoff es idéntico en su forma para todas las herramientas — lo que cambia es dónde dibujás las pantallas (paso 2) y, para Open Design, quién hace el paso 3 y 4 (vos, o la IA sola vía MCP — ver §05).
Corrés /design-system. La fase de screen-mapping siempre pregunta, nunca corre sola — vía AskUserQuestion, con tres opciones: sí tengo/voy a producir mockups, no (los tokens alcanzan), o todavía no.
vos → "sí, voy a producir mockups para estas historias"La IA escribe BRIEF.md sembrado con los tokens de DESIGN.md (valores reales inline) + las historias y comportamientos visibles. Es el prompt portable que vas a pegar en la herramienta — o que la IA misma va a usar si el camino es MCP-driven.
.context/designs/<proyecto>/<lote>/BRIEF.md
Pegás el brief en Claude Design / Open Design / la que sea, iterás las pantallas conversando, y exportás el resultado. En el camino manual, este paso lo hacés vos. En Open Design con MCP conectado, la IA puede disparar y pollear el run sola — ver Modo A en §05.
Los archivos exportados quedan en la misma carpeta del brief. Esa es la zona de entrega que la IA vigila (o que ella misma llena, en Modo A).
.context/designs/<proyecto>/<lote>/
Le avisás que ya está (o ella misma lo detecta al terminar su run). La IA lee los mockups, enumera pantallas, escribe §4 + §8, y te muestra el mapa para revisar. Listo para el sprint.
vos → "ya dejé los mockups en la carpeta, armá el master design plan"La herramienta de Anthropic (claude.ai/design). Convertís texto en prototipos interactivos HTML/CSS/JS que refinás conversando. Es Path D de las cinco vías de DESIGN.md, y también sirve para screen mockups pegando el BRIEF.md.
Creás un proyecto (hereda el design system de tu org). Le enchufás contexto: repo de GitHub o directorio local, assets existentes. Pegás el BRIEF.md completo como primer mensaje del chat.
Chat para cambios grandes · comentarios inline (clic en un elemento del canvas) · edición directa (arrastrar / redimensionar / alinear) · sliders que Claude genera para espaciado, color y layout.
Un proyecto sostiene el flujo completo (varias pantallas conectadas con navegación). Generá los estados borde — vacío, cargando, error — antes del handoff.
Botón Export (arriba a la derecha): "Send to local coding agent" empuja el bundle directo a tu Claude Code local corriendo en el repo, o "Save as folder" lo descarga como ZIP/carpeta para que vos lo muevas a mano.
Con "Save as folder": descomprimís en .context/designs/<proyecto>/<lote>/. Con "Send to local coding agent": le decís al agente esa misma ruta de destino — el scope de este drop zone es screen mockups, no el bundle de DESIGN.md (ese usa design/handoff/).
La alternativa open source y gratuita a Claude Design (nexu-io/open-design, Apache-2.0). Hoy es una desktop app (no Docker) que usa tu propio agente de código como motor — y puede operarse sola vía MCP.
Con el daemon de Open Design conectado como MCP server, la IA misma llama create_project + start_run con el contenido del BRIEF.md, pollea get_run cada 30–60s en un loop foreground, y al ver status: succeeded ubica el resultado con get_artifact / list_files y lo copia (cp) desde el data root de Open Design a la drop zone del repo — sin que vos toques la ventana.
Si el MCP no está conectado: la IA deja el BRIEF.md y pausa. Abrís la desktop app vos, pegás el brief en Studio → New Project (skill/template + DESIGN.md + brief), iterás, y copiás el archivo final desde la carpeta de datos del proyecto (o corrés od export) a la drop zone, y avisás cuando esté.
En Settings elegís cómo genera: apuntando a tu CLI ya autenticado (Claude Code / Codex / OpenCode — sin key extra) o cargando una API key de cualquier endpoint compatible con la API de OpenAI (BYOK).
Registrás el daemon de Open Design como MCP server en tu coding agent (Claude Code, etc.). Una vez conectado, los 18 tools mcp__open-design__* quedan disponibles y el Modo A se vuelve el camino por defecto.
Skill de OD (para pantallas de aplicación usá frontend-design; a 0.16.x no existen web-prototype ni dashboard como skill — no los cites) + design system (tu DESIGN.md real) + brief en lenguaje natural (el BRIEF.md). Send — a mano en Studio, o vía start_run si es la IA quien dispara.
El agente interno de Open Design emite un HTML completo y auto-contenido; el panel derecho lo streamea como prototipo navegable — botones, tabs y modales funcionan. Cada follow-up crea una nueva versión, las anteriores quedan en el historial.
Modo A: la IA ubica el archivo con get_artifact y lo copia (cp) a la drop zone — el MCP no escribe fuera de su propio data root. Modo B: copiás el archivo (o corrés od export) a .context/designs/<proyecto>/<lote>/ y avisás.
Si vas a operar Open Design vía MCP (Modo A), estas cuatro señales confunden si no las conocés de antemano.
El repo trata como fuente de pantallas cualquier cosa que caiga en la drop zone. Claude Design y Open Design son las recomendadas, pero el patrón universal (§03) también acepta:
Diseñás en Figma como siempre y exportás las pantallas (imágenes / HTML / specs) a la drop zone. La IA las lee como referencia visual. Ideal si tu equipo ya vive en Figma. La contra: no son prototipos vivos HTML, así que la IA infiere layout desde la imagen + tu brief.
Lo escribís vos — a mano, o pegando el output de un chat de IA cualquiera que uses como bloc de notas, en otra sesión, sin conexión con la que está corriendo /design-system. Rápido y sin salir de la terminal. La contra: sin canvas visual para iterar cómodo, el refinamiento es por chat en esa otra sesión y revisando el HTML renderizado.
La opción más rápida cuando no querés levantar ninguna app. Sirve bien para pantallas simples y para iterar rápido antes de pulir en una herramienta visual — siempre que el archivo lo produzcas y lo muevas vos, no la sesión de /design-system.
En otra ventana o sesión (o a mano), un prompt que ancla tres cosas: qué pantalla, qué historia, y que use los tokens de DESIGN.md. Pedís un archivo autocontenido (abrible en el navegador de una).
vos, en esa otra sesión → "Generá un mockup HTML autocontenido de la pantalla de login para la historia BK-14. Usá los tokens de DESIGN.md. Un solo archivo."Copiás el .html resultante a .context/designs/<proyecto>/<lote>/login.html — acción tuya, igual que descomprimir un zip de Claude Design. Lo abrís y lo mirás en el navegador: ese render es tu canvas.
Describís el cambio en palabras allá; esa sesión reescribe el archivo; vos volvés a copiarlo a la drop zone y refrescás el navegador. Repetís hasta que quede.
vos, en esa otra sesión → "el botón primario más grande, agregá el estado de error y un enlace de recuperar contraseña"Pedí explícitamente vacío, cargando y error — no se agregan solos. Son parte del contrato de pantalla.
El archivo ya está en la drop zone (lo pusiste vos en el paso 2). Le pedís a /design-system que arme el plan. Mismo final que Claude Design u Open Design.
vos → "listo el mockup, armá el master design plan para BK-14"| Claude Design | Open Design | Figma | HTML manual | |
|---|---|---|---|---|
| Costo / acceso | Pro+ plan de pago | gratis local | free/pago | incluido |
| Dónde corre | Web (claude.ai/design) | Tu máquina (desktop app, puerto dinámico) | Web / desktop | Otra sesión, aparte del repo |
| Medio | Prototipo vivo HTML/CSS/JS | Prototipo vivo HTML | Diseño vectorial → export | HTML plano |
| Iteración | Chat · inline · drag · sliders | Chat + versiones · MCP Modo A autónomo | Manual (vos diseñás) | Chat aparte + vos copiás el render |
| Usa DESIGN.md | Vía design system de la org | Sí, lo consume directo | Manual (tokens a mano) | Sí, se lo pasás |
| Mejor para | Refinamiento visual rico y rápido | Todo local, sin costo, y automatizable end-to-end | Equipos ya en Figma | Pantallas simples, sin fricción |
Rutas, drop zones, comandos MCP y versión verificados contra .claude/skills/design-system/ de este repo a 2026-07-30 (Open Design v0.16.1, release 2026-07-23). Los mecanismos de interacción de Claude Design (chat / inline / drag / sliders) son conocimiento general de producto, no están documentados en la skill. Features en evolución rápida — confirmá antes de una demo importante.
Toda la maniobra, del lado tuyo, se reduce a unas pocas frases. Esto es lo que tipeás en Claude Code / OpenCode.
Y cuando pregunte por el mapeo de pantallas: "sí, voy a producir los mockups".
La IA deja BRIEF.md en la carpeta del lote. Modo B: lo pegás en Claude Design u Open Design, iterás, exportás el bundle a esa misma carpeta. Modo A (Open Design + MCP): no hace falta que hagas nada más, la IA dispara y pollea sola.
La IA lee, escribe §4 + §8 y te muestra el mapa Historia→Pantalla para que lo confirmes.
Si esa historia no tenía mockup, el propio flujo te devuelve al paso 1 con un brief solo para ese lote de pantallas.
Antes de empezar a producir mockups, tené esto listo:
Runbook literal. Dos caminos según cuánto quieras montar. Los dos parten de abrir Claude Code u OpenCode en la raíz del repo — las skills viven en .claude/skills/ y ambas terminales las leen igual, así que /design-system y /sprint-development están disponibles en cualquiera de las dos.
Cuando vas a diseñar en Claude Design u Open Design y querés el BRIEF sembrado con tus tokens.
La IA deja el BRIEF.md, lo pegás en tu herramienta, exportás el bundle a la drop zone, y cerrás con "armá el master design plan".
El más rápido para arrancar hoy. No levantás nada — pero el archivo lo generás y lo movés vos, en una sesión distinta a la que corre /design-system.
Abrís el .html en el navegador, iterás por chat en esa otra sesión, y recién ahí volvés a la sesión de /design-system y cerrás con "armá el master design plan para BK-XX".