| name | visual-setup |
| description | Configure complete visual identity for a project before development. Use when the user says "visual setup", "setup design", "configure brand", "design system", "visual identity", "brand kit", or wants to set up Stitch + VEG + brand tokens before running /plan.
|
| context | direct |
/visual-setup (Global)
Configura la identidad visual completa de un proyecto ANTES de empezar a desarrollar: Brand Kit + Google Stitch Design System + VEG base + Multi-Form-Factor + Prompt Template. Tras ejecutar este skill, /plan y /implement generan disenos consistentes con la marca sin intervencion adicional.
Uso
/visual-setup # Modo interactivo completo
/visual-setup calm-enterprise # Preset de estetica
/visual-setup --from doc/brand/ # Parsear brand kit existente
Posicion en el pipeline
/prd → PRD + Trello/Plane
↓
/visual-setup → Brand Kit + Stitch DS + VEG + Multi-FF ← ESTE SKILL
↓
/plan → Plan tecnico + Disenos Stitch (ya con brand)
↓
/implement → Codigo con design-to-code fiel a la marca
Paso 0.0 — Leer documentos canónicos (v5.29.0 + v6.0.1 content-passing)
ANTES de cualquier otro paso:
- Usa
Read localmente sobre doc/app/app_prd.md y doc/app/app_spec.md.
- Llama a la tool MCP con el contenido:
get_inheritable_values_tool(
app_prd_content=<contenido o null>,
app_spec_content=<contenido o null>,
)
v6.0.1: get_inheritable_values_tool y read_app_docs_tool dejaron de aceptar project_path — el cliente lee localmente y pasa el contenido.
Si app_spec.md ya define identidad visual (brand_visual zone con valores reales — no plantilla):
| Flag | Si es True, salta el paso |
|---|
veg_archetype definido | Paso 1 (recopilar identidad estética) — la dirección visual está fijada a nivel de proyecto |
veg_mode_known | Paso 1 (modo VEG) — heredado |
En ese caso, pregunta solo:
He detectado en doc/app/app_spec.md:
- VEG arquetipo: {valor}
- Modo VEG: {valor}
¿Quieres usarlos para esta sesión de visual-setup, o prefieres redefinir?
[s] usar app_spec [r] redefinir [c] cancelar
Si el usuario responde r, el flujo legacy de Paso 1 se activa. Si responde s, salta directamente a generación de tokens (Paso 2 si existe, o el paso equivalente del flujo).
0.0.1 — Política de Autopilot aplicable a /visual-setup
Antes de cada confirmación, llama a evaluateDecision(decision_key, context) desde .claude/hooks/lib/autopilot.mjs:
| Pregunta del skill | decision_key | Default si auto |
|---|
| "¿Quieres actualizar o empezar de cero?" (Paso 0 si COMPLETO) | design_system_update_check | equilibrado+: conservar existente |
| Dirección estética (Paso 1, 7 opciones) | feature_aesthetic_direction | equilibrado+: hereda de app_spec.md cuando hasAppSpec=true |
| "¿Confirmas estos tokens?" (Paso 2.X) | tokens_confirmation | conservador+: auto-confirma siempre |
| Stitch API key faltante | stitch_api_key_missing | siempre ask |
Tras cada auto-confirmación visible al usuario:
ℹ️ Tokens auto-confirmados (autopilot: equilibrado, decision_key: tokens_confirmation)
Paso 0: Detectar Estado Actual
0.1 Verificar artefactos existentes
¿Que existe ya?
├── doc/brand/brand_kit/SKILL.md → Brand Kit completo
├── doc/brand/brand_kit/variables.css → Tokens CSS
├── doc/brand/brand_briefing.md → Briefing parcial
├── doc/veg/base/ → VEG base existente
├── doc/design/stitch-prompt-template.md → Prompt template
└── .claude/settings.local.json → Config Stitch/VEG
ls doc/brand/brand_kit/SKILL.md 2>/dev/null
ls doc/brand/brand_kit/variables.css 2>/dev/null
ls doc/brand/brand_briefing.md 2>/dev/null
ls doc/veg/base/ 2>/dev/null
cat .claude/settings.local.json 2>/dev/null | grep -E "stitch|projectId|designSystem"
ls doc/design/stitch-prompt-template.md 2>/dev/null
0.2 Evaluar estado
Estado detectado:
├── COMPLETO → Todo existe (brand kit + stitch + VEG + template)
│ └── INFO: "El proyecto ya tiene identidad visual configurada."
│ └── Preguntar: "¿Quieres actualizar algo o empezar de cero?"
│
├── PARCIAL → Algunos artefactos existen
│ └── INFO: "Se encontraron artefactos parciales. Se completara lo que falta."
│ └── Listar que existe y que falta
│ └── Continuar desde el paso que corresponda
│
└── VACIO → Nada existe
└── INFO: "Proyecto sin identidad visual. Iniciando configuracion completa."
└── Continuar con Paso 1
0.3 Detectar proyecto Stitch existente
Si hay stitch.projectId en .claude/settings.local.json:
- Llamar
mcp__stitch__get_project con ese projectId
- Si responde OK → reusar proyecto existente
- Si falla → crear nuevo en Paso 3
Paso 1: Recopilar Identidad Visual
1.1 Arbol de decision de fuentes de datos
¿De donde vienen los tokens?
├── doc/brand/brand_kit/SKILL.md existe
│ └── Parsear SKILL.md y extraer:
│ ├── Nombre del producto
│ ├── Dominio/sector
│ ├── Colores (primary, secondary, accent, neutral)
│ ├── Tipografia (heading, body, mono)
│ ├── Roundness
│ ├── Shadows
│ └── Dispositivo principal
│ └── Confirmar con usuario: "He extraido estos tokens del brand kit existente: [tabla]. ¿Correcto?"
│
├── doc/brand/brand_briefing.md existe
│ └── Parsear briefing y extraer tokens parciales
│ └── Completar datos faltantes con preguntas al usuario
│
└── No hay fuentes → Modo interactivo completo (1.2)
1.2 Modo interactivo
Preguntar al usuario en este orden. Mostrar las opciones como tabla para facilitar la eleccion.
Pregunta 1: Nombre y dominio
¿Cual es el nombre del producto y su dominio?
Ejemplo: "McProfit — fintech para gestion de inversiones"
Pregunta 2: Estetica
Mostrar tabla de presets disponibles:
| # | Estetica | Primary | Secondary | Font | Roundness | Referentes |
|---|
| 1 | Calm Enterprise | #4F46E5 (Indigo) | #8B5CF6 (Violet) | GEIST | Rounded (12px) | Linear, Stripe |
| 2 | Bold Startup | #7C3AED (Violet) | #EC4899 (Pink) | DM_SANS | Medium (8px) | Notion, Figma |
| 3 | Minimal Tool | #171717 (Neutral) | #525252 (Gray) | INTER | Sharp (4px) | GitHub, Vercel |
| 4 | Financial Pro | #0F172A (Slate) | #0EA5E9 (Sky) | PLUS_JAKARTA_SANS | Medium (8px) | Stripe, Wise |
| 5 | Health & Care | #059669 (Emerald) | #14B8A6 (Teal) | MANROPE | Full/Pill | Calm, Headspace |
| 6 | Developer DX | #F97316 (Orange) | #EAB308 (Yellow) | SPACE_GROTESK | Medium (8px) | Vercel, Railway |
| 7 | Custom | (preguntar) | (preguntar) | (preguntar) | (preguntar) | — |
¿Que estetica se acerca mas a tu producto? (1-7)
Si elige 1-6 → cargar preset completo, confirmar con usuario, permitir override de cualquier campo.
Si elige 7 (Custom) → continuar con preguntas 3-7.
Pregunta 3: Color primario (solo si Custom)
¿Color primario? (hex, ej: #4F46E5)
Puedo sugerir uno si me dices el sector del producto.
Pregunta 4: Color secundario (solo si Custom)
¿Color secundario? (hex, ej: #8B5CF6)
Si no tienes uno, puedo derivarlo del primario (complementario o analogo).
Pregunta 5: Tipografia (solo si Custom)
Mostrar tabla de fuentes soportadas por Stitch:
| # | Fuente | Estilo | Recomendada para |
|---|
| 1 | GEIST | Modern, clean, Vercel-style | SaaS, tech products, calm enterprise |
| 2 | INTER | Neutral, versatile | Universal, safe choice |
| 3 | DM_SANS | Geometric, friendly | Startups, consumer products |
| 4 | PLUS_JAKARTA_SANS | Elegant, modern | Fintech, premium SaaS |
| 5 | SPACE_GROTESK | Technical, distinctive | Developer tools, data products |
| 6 | SORA | Geometric, balanced | Modern apps, dashboards |
| 7 | IBM_PLEX_SANS | Corporate, reliable | Enterprise, B2B |
| 8 | MANROPE | Warm, rounded | Health, education, HR |
| 9 | RUBIK | Soft, approachable | Consumer, mobile-first |
| 10 | SOURCE_SANS_THREE | Clean, readable | Content-heavy, documentation |
| 11 | MONTSERRAT | Bold, impactful | Marketing, landing pages |
| 12 | WORK_SANS | Professional, balanced | Business tools, enterprise |
¿Tipografia? (1-12, o nombre directamente)
Pregunta 6: Roundness (solo si Custom)
| # | Nombre | CSS radius | Stitch enum | Efecto |
|---|
| 1 | Sharp | 4px | ROUND_FOUR | Profesional, tecnico |
| 2 | Medium | 8px | ROUND_EIGHT | Balanceado, moderno |
| 3 | Rounded | 12px | ROUND_TWELVE | Amigable, suave |
| 4 | Full/Pill | 9999px | ROUND_FULL | Jugueton, bold |
¿Roundness? (1-4)
Pregunta 7: Dispositivo principal (solo si Custom)
¿Desktop-first o mobile-first?
1.3 Derivar colores complementarios
A partir de los colores primario y secundario, derivar automaticamente:
Paleta completa:
├── primary: {color elegido}
├── secondary: {color elegido}
├── accent: {derivar — triadic o split-complementary del primary}
├── success: #10B981 (Emerald 500 — standard)
├── warning: #F59E0B (Amber 500 — standard)
├── error: #EF4444 (Red 500 — standard)
├── info: #3B82F6 (Blue 500 — standard)
├── neutral-50 a neutral-900: {escala de grises derivada}
├── surface-light: #FFFFFF
├── surface-dark: #0F172A
├── text-primary-light: #1E293B
├── text-primary-dark: #F1F5F9
├── text-secondary-light: #64748B
└── text-secondary-dark: #94A3B8
1.4 Mapear tipografia a Stitch enum
Mapeo de fuentes:
├── headlineFont: {fuente elegida} (para titulos h1-h3)
├── bodyFont: {fuente elegida} (para texto body)
├── labelFont: {fuente elegida} (para labels, captions, buttons)
└── monoFont: "JetBrains Mono" o "Fira Code" (para code blocks — solo CSS, no Stitch)
REGLA: Las 3 fuentes de Stitch (headline, body, label) usan la MISMA familia por defecto. Solo separar si el usuario lo pide explicitamente o si la estetica lo requiere (ej: serif para headlines + sans para body).
1.5 Confirmar tokens con el usuario
Antes de generar cualquier artefacto, mostrar resumen completo:
## Identidad Visual — {Nombre del Producto}
| Token | Valor |
|-------|-------|
| Nombre | {nombre} |
| Dominio | {dominio} |
| Estetica | {nombre preset o "Custom"} |
| Primary | {hex} ████ |
| Secondary | {hex} ████ |
| Accent | {hex} ████ |
| Font Headline | {FONT_ENUM} |
| Font Body | {FONT_ENUM} |
| Roundness | {nombre} ({Npx}) |
| Device | {desktop-first / mobile-first} |
¿Confirmas estos tokens? (si / ajustar campo)
IMPORTANTE: No avanzar al Paso 2 sin confirmacion explicita del usuario.
Paso 2: Generar Brand Kit
Solo si no existe doc/brand/brand_kit/ o el usuario pidio regenerar.
2.1 Crear estructura de directorios
mkdir -p doc/brand/brand_kit
2.2 Generar variables.css
Archivo con CSS custom properties para light y dark mode:
:root {
--color-primary: {primary};
--color-primary-hover: {primary-600};
--color-primary-active: {primary-700};
--color-primary-subtle: {primary-50};
--color-on-primary: #FFFFFF;
--color-secondary: {secondary};
--color-secondary-hover: {secondary-600};
--color-secondary-active: {secondary-700};
--color-secondary-subtle: {secondary-50};
--color-on-secondary: #FFFFFF;
--color-accent: {accent};
--color-accent-subtle: {accent-50};
--color-success: #10B981;
--color-warning: #F59E0B;
--color-error: #EF4444;
--color-info: #3B82F6;
--color-neutral-50: {neutral-50};
--color-neutral-100: {neutral-100};
--color-neutral-200: {neutral-200};
--color-neutral-300: {neutral-300};
--color-neutral-400: {neutral-400};
--color-neutral-500: {neutral-500};
--color-neutral-600: {neutral-600};
--color-neutral-700: {neutral-700};
--color-neutral-800: {neutral-800};
--color-neutral-900: {neutral-900};
--color-neutral-950: {neutral-950};
--color-surface: #FFFFFF;
--color-surface-raised: {neutral-50};
--color-surface-overlay: rgba(0, 0, 0, 0.5);
--color-border: {neutral-200};
--color-border-strong: {neutral-300};
--color-text-primary: #1E293B;
--color-text-secondary: #64748B;
--color-text-tertiary: #94A3B8;
--color-text-inverse: #F1F5F9;
--font-heading: '{font-name}', system-ui, sans-serif;
--font-body: '{font-name}', system-ui, sans-serif;
--font-label: '{font-name}', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', 'Fira Code', monospace;
--text-xs: 0.75rem;
--text-sm: 0.875rem;
--text-base: 1rem;
--text-lg: 1.125rem;
--text-xl: 1.25rem;
--text-2xl: 1.5rem;
--text-3xl: 1.875rem;
--text-4xl: 2.25rem;
--space-1: 0.25rem;
--space-2: 0.5rem;
--space-3: 0.75rem;
--space-4: 1rem;
--space-6: 1.5rem;
--space-8: 2rem;
--space-12: 3rem;
--space-16: 4rem;
--radius-sm: {radius-sm}px;
--radius-md: {radius-md}px;
--radius-lg: {radius-lg}px;
--radius-full: 9999px;
--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
--shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1);
}
[data-theme="dark"], .dark {
--color-primary: {primary-400};
--color-primary-hover: {primary-300};
--color-primary-active: {primary-200};
--color-primary-subtle: {primary-950};
--color-on-primary: #0F172A;
--color-secondary: {secondary-400};
--color-secondary-hover: {secondary-300};
--color-secondary-active: {secondary-200};
--color-secondary-subtle: {secondary-950};
--color-on-secondary: #0F172A;
--color-accent: {accent-400};
--color-accent-subtle: {accent-950};
--color-surface: #0F172A;
--color-surface-raised: #1E293B;
--color-surface-overlay: rgba(0, 0, 0, 0.7);
--color-border: #334155;
--color-border-strong: #475569;
--color-text-primary: #F1F5F9;
--color-text-secondary: #94A3B8;
--color-text-tertiary: #64748B;
--color-text-inverse: #1E293B;
}
Reglas de derivacion de radius por roundness:
| Roundness | radius-sm | radius-md | radius-lg |
|---|
| Sharp (ROUND_FOUR) | 2 | 4 | 6 |
| Medium (ROUND_EIGHT) | 4 | 8 | 12 |
| Rounded (ROUND_TWELVE) | 6 | 12 | 16 |
| Full (ROUND_FULL) | 8 | 16 | 9999 |
2.3 Generar tailwind.config.js
export default {
theme: {
extend: {
colors: {
primary: {
DEFAULT: 'var(--color-primary)',
hover: 'var(--color-primary-hover)',
active: 'var(--color-primary-active)',
subtle: 'var(--color-primary-subtle)',
},
secondary: {
DEFAULT: 'var(--color-secondary)',
hover: 'var(--color-secondary-hover)',
active: 'var(--color-secondary-active)',
subtle: 'var(--color-secondary-subtle)',
},
accent: {
DEFAULT: 'var(--color-accent)',
subtle: 'var(--color-accent-subtle)',
},
success: 'var(--color-success)',
warning: 'var(--color-warning)',
error: 'var(--color-error)',
info: 'var(--color-info)',
surface: {
DEFAULT: 'var(--color-surface)',
raised: 'var(--color-surface-raised)',
},
border: {
DEFAULT: 'var(--color-border)',
strong: 'var(--color-border-strong)',
},
},
fontFamily: {
heading: 'var(--font-heading)',
body: 'var(--font-body)',
label: 'var(--font-label)',
mono: 'var(--font-mono)',
},
borderRadius: {
sm: 'var(--radius-sm)',
md: 'var(--radius-md)',
lg: 'var(--radius-lg)',
full: 'var(--radius-full)',
},
boxShadow: {
sm: 'var(--shadow-sm)',
md: 'var(--shadow-md)',
lg: 'var(--shadow-lg)',
xl: 'var(--shadow-xl)',
},
},
},
};
2.4 Generar SKILL.md (resumen compacto para agentes)
Este archivo es lo que los sub-agentes (AG-02, AG-06) reciben en su contexto. Maximo ~600 tokens.
# Brand: {Nombre del Producto}
> {Dominio} — Estetica: {nombre estetica}
## Paleta
| Rol | Hex | Uso |
|-----|-----|-----|
| Primary | {hex} | CTAs, links, focus rings, active states |
| Secondary | {hex} | Secondary buttons, tags, badges |
| Accent | {hex} | Highlights, notifications, progress |
| Neutral | {neutral-500} | Borders, dividers, disabled states |
## Tipografia
- **Heading**: {font-name} (bold/semibold)
- **Body**: {font-name} (regular, 16px base)
- **Label**: {font-name} (medium, 14px)
- **Mono**: JetBrains Mono (code blocks)
## Forma
- **Radius**: {roundness-name} ({N}px base)
- **Shadows**: {subtle/moderate/elevated} — usar shadow-sm por defecto, shadow-md para cards elevadas
- **Borders**: 1px solid neutral-200 (light) / neutral-700 (dark)
## Reglas
1. Primary solo para CTAs principales y elementos interactivos primarios
2. Secondary para acciones secundarias, nunca para texto
3. Neutral-50 para fondos de cards, neutral-100 para fondos de seccion
4. Mantener contraste minimo 4.5:1 (AA) para texto
5. Dark mode usa las variantes -400 de primary/secondary (mas brillantes sobre fondo oscuro)
6. Espaciado consistente: multiplos de 4px (space-1 a space-16)
2.5 Generar light.md (especificaciones tema claro)
# {Nombre} — Light Theme
## Surfaces
- Background: #FFFFFF
- Card: {neutral-50}
- Section alt: {neutral-100}
- Sidebar: #FFFFFF border-r neutral-200
## Text
- Primary: #1E293B
- Secondary: #64748B
- Disabled: #CBD5E1
## Interactive
- Button primary: bg {primary}, text white, hover {primary-600}
- Button secondary: bg white, border {neutral-300}, hover bg {neutral-50}
- Input: bg white, border {neutral-300}, focus ring {primary}/20%
- Link: {primary}, hover {primary-700}, underline on hover
## Feedback
- Success: bg #ECFDF5, border #10B981, text #065F46
- Error: bg #FEF2F2, border #EF4444, text #991B1B
- Warning: bg #FFFBEB, border #F59E0B, text #92400E
- Info: bg #EFF6FF, border #3B82F6, text #1E40AF
2.6 Generar dark.md (especificaciones tema oscuro)
# {Nombre} — Dark Theme
## Surfaces
- Background: #0F172A
- Card: #1E293B
- Section alt: #334155
- Sidebar: #0F172A border-r #334155
## Text
- Primary: #F1F5F9
- Secondary: #94A3B8
- Disabled: #475569
## Interactive
- Button primary: bg {primary-400}, text #0F172A, hover {primary-300}
- Button secondary: bg #1E293B, border #475569, hover bg #334155
- Input: bg #1E293B, border #475569, focus ring {primary-400}/20%
- Link: {primary-400}, hover {primary-300}, underline on hover
## Feedback
- Success: bg #064E3B, border #10B981, text #A7F3D0
- Error: bg #7F1D1D, border #EF4444, text #FECACA
- Warning: bg #78350F, border #F59E0B, text #FDE68A
- Info: bg #1E3A5F, border #3B82F6, text #BFDBFE
2.7 Confirmar Brand Kit generado
Brand Kit generado en doc/brand/brand_kit/:
├── SKILL.md — Resumen para agentes (~600 tokens)
├── variables.css — Tokens CSS (light + dark)
├── tailwind.config.js — Configuracion Tailwind con CSS vars
├── light.md — Specs tema claro
└── dark.md — Specs tema oscuro
¿Quieres revisar o ajustar algun archivo antes de continuar?
Paso 2.9: Seleccionar proveedor visual del VEG (US-29)
Antes de configurar Stitch, decide qué proveedor(es) visual(es) usará el VEG.
El resultado se escribe en veg.providers de .claude/settings.local.json.
decision_key: visual_provider_selection (siempre ask — elección del usuario).
2.9.1 Detectar si hay design-system compilado
Resolver el sitio por topología y comprobar la precondición (gate de UC-2903):
mcp__SpecBox-MCP__claude_design_status(
project="{project-slug}",
project_root="{ruta absoluta del repo}"
)
El status devuelve gate_ready (hay package.json + dist//Storybook en el sitio
resuelto — orquestador en multirepo, repo en monorepo), role, site y login_active.
2.9.2 Preguntar proveedor(es)
¿Qué proveedor visual quieres para este proyecto?
├── [1] Claude Design — diseña con tus componentes reales (1:1 a código).
│ Requiere design-system compilado. RECOMENDADO si gate_ready=true.
├── [2] Stitch — text-to-mockup. Útil en fase temprana sin código.
└── [3] Ambos — Claude Design preferido cuando hay design-system; Stitch fallback.
- Si
gate_ready=true, recomendar Claude Design por defecto (JR-CD.6). Si false,
recomendar Stitch y explicar que Claude Design quedará pending hasta que exista el
design-system compilado (no bloquea).
- Escribir el resultado en
veg.providers con MERGE (no sobrescribir el resto del
JSON), p. ej. ["claude_design"], ["stitch"] o ["stitch","claude_design"].
2.9.3 Configurar Claude Design (si se eligió)
Claude Design usa el login de claude.ai de esta máquina (vía la tool DesignSync).
No se pide ni se guarda ninguna API key; el consumo se factura a la suscripción
del usuario logueado. Respeta los prompts de permiso de DesignSync (create_project,
finalize_plan, write_files) — no asumir auto-aprobación.
Si veg.providers incluye "claude_design":
1. Verificar login activo (claude_design_status → login_active). Si no hay login,
informar que la capacidad queda pending hasta iniciar sesión en claude.ai.
2. Si no hay veg.claude_design.projectId y el usuario quiere crearlo ahora:
mcp__SpecBox-MCP__claude_design_create_project(project, project_root, name)
→ el agente ejecuta DesignSync.create_project (PROMPT de permiso) y el engine
ancla el projectId devuelto en veg.claude_design.projectId.
3. Si solo se eligió Claude Design, se puede SALTAR el Paso 3 (Stitch).
Borrado: no hay borrado programático de proyectos Claude Design. Para eliminar uno,
hazlo manualmente en claude.ai.
Paso 3: Configurar Google Stitch
Saltar este paso si veg.providers == ["claude_design"] (solo Claude Design).
3.1 Verificar API Key de Stitch
¿Hay API Key de Stitch configurada?
├── stitch_set_api_key ya ejecutado → Continuar
├── stitch.apiKey en settings.local.json → Usar esa
└── No hay key → Preguntar al usuario:
"Necesito tu API Key de Google Stitch para crear el proyecto y design system.
Puedes obtenerla en: https://stitch.withgoogle.com/settings
Introduce tu API Key:"
Si el usuario proporciona API Key, configurarla via MCP:
mcp__SpecBox-MCP__stitch_set_api_key(
project="{project_path}",
api_key="{api_key}"
)
3.2 Crear proyecto en Stitch
Solo si no hay stitch.projectId valido en settings.
mcp__stitch__create_project(
title="{Nombre del Producto}"
)
Guardar el projectId retornado para el siguiente paso.
3.3 Crear Design System en Stitch
CRITICO: El designMd es el campo mas importante. Stitch lo lee para guiar TODA la generacion visual. Debe ser un resumen denso y completo del brand kit.
mcp__stitch__create_design_system(
projectId="{stitch_project_id}",
designSystem={
"displayName": "{Nombre del Producto} Design System",
"theme": {
"colorMode": "LIGHT",
"headlineFont": "{FONT_ENUM}",
"bodyFont": "{FONT_ENUM}",
"labelFont": "{FONT_ENUM}",
"roundness": "{ROUND_FOUR|ROUND_EIGHT|ROUND_TWELVE|ROUND_FULL}",
"customColor": "{primary_hex}",
"overridePrimaryColor": "{primary_hex}",
"overrideSecondaryColor": "{secondary_hex}",
"overrideTertiaryColor": "{accent_hex}",
"overrideNeutralColor": "{neutral_500_hex}",
"colorVariant": "{color_variant}",
"designMd": "{design_md_content}"
}
}
)
Mapeo de estetica a colorVariant:
| Estetica | colorVariant | Razon |
|---|
| Calm Enterprise | TONAL_SPOT | Palette armonica, profesional |
| Bold Startup | VIBRANT | Colores saturados, energeticos |
| Minimal Tool | NEUTRAL | Palette restringida, funcional |
| Financial Pro | FIDELITY | Fidelidad al color elegido |
| Health & Care | TONAL_SPOT | Armonia natural, confianza |
| Developer DX | EXPRESSIVE | Colores distintos, personalidad |
| Custom | TONAL_SPOT | Default seguro |
Contenido del designMd (~2000 palabras max):
Generar un Markdown denso que incluya:
# {Nombre del Producto} — Design Guidelines
## Brand Identity
- Product: {nombre} — {dominio}
- Aesthetic: {estetica} ({referentes})
- Visual tone: {profesional/energetico/minimal/calido/tecnico}
## Color System
- Primary: {hex} — Use for CTAs, active states, focus rings, primary actions
- Secondary: {hex} — Use for secondary buttons, tags, badges, supporting elements
- Accent: {hex} — Use for highlights, notifications, progress indicators
- Semantic: Success #10B981, Warning #F59E0B, Error #EF4444, Info #3B82F6
- Neutrals: Scale from {neutral-50} (lightest bg) to {neutral-900} (darkest text)
- RULE: Primary buttons are solid primary bg with white text. Secondary buttons are outlined with neutral border.
- RULE: Card backgrounds use neutral-50. Section alternating backgrounds use neutral-100.
## Typography
- Headings: {font-name}, bold, sizes 36/30/24/20px (h1/h2/h3/h4)
- Body: {font-name}, regular, 16px base, line-height 1.5
- Labels: {font-name}, medium, 14px, letter-spacing 0.01em
- RULE: Maximum 2 font weights per page. Bold for headings, regular for body.
## Shape & Spacing
- Border radius: {N}px base ({roundness-name})
- Buttons: {radius-md}px radius
- Cards: {radius-lg}px radius
- Inputs: {radius-md}px radius
- Spacing: 4px grid. Minimum padding inside cards: 16px. Section gaps: 48px.
- RULE: All interactive elements have at least 44px tap target.
## Component Patterns
- Cards: white bg, {radius-lg}px radius, shadow-sm, 1px border neutral-200, 24px padding
- Buttons: {radius-md}px radius, 14px font, 500 weight, 12px 24px padding
- Inputs: {radius-md}px radius, 1px border neutral-300, 12px 16px padding, focus ring 2px primary/20%
- Tables: header bg neutral-50, rows alternate white/neutral-50, 1px border-b neutral-200
- Navigation: fixed top, white bg, shadow-sm, 64px height
- Sidebar: 280px width, white bg, border-r neutral-200
## Layout Principles
- Max content width: 1280px (centered)
- Grid: 12 columns with 24px gap
- Responsive breakpoints: sm 640px, md 768px, lg 1024px, xl 1280px
- {desktop-first|mobile-first} approach
## Visual Hierarchy
1. Page title (h1) — largest, bold, primary text color
2. Section title (h2) — medium, semibold
3. Card title (h3) — smaller, semibold
4. Body text — regular weight, secondary text for descriptions
## Do NOT
- Use gradients on backgrounds (flat colors only)
- Use more than 2 font sizes in a single card
- Stack more than 3 CTAs in one viewport
- Use shadows heavier than shadow-md on cards
- Mix rounded and sharp corners in the same view
3.4 Guardar asset ID del Design System
Tras la creacion, create_design_system retorna un name con formato assets/{asset_id}.
Extraer el asset_id y guardar para siguiente paso.
3.5 Aplicar Design System al proyecto
Inmediatamente despues de crear el Design System, llamar a update_design_system para activarlo:
mcp__stitch__update_design_system(
name="assets/{asset_id}",
projectId="{stitch_project_id}",
designSystem={...mismo objeto que en create...}
)
3.6 Confirmar con usuario
Google Stitch configurado:
├── Proyecto: "{Nombre}" (ID: {stitch_project_id})
├── Design System: "{Nombre} Design System" (Asset: {asset_id})
├── Color Mode: LIGHT (dark mode se implementa en codigo)
├── Font: {font_name}
├── Roundness: {roundness_name}
└── Color Variant: {variant}
¿Todo correcto?
3.7 Generar DESIGN.md canónico (v5.31.0)
Una vez configurado el Design System de Stitch, materializar también un
DESIGN.md canónico — formato oficial de Google
(github.com/google-labs-code/design.md) que Stitch lee como contexto
persistente en cada generación. Sin esto, las pantallas tienden a
derivar visualmente entre sí.
generate_design_md_tool(
project="{project-slug}",
project_root="{absolute_path_a_la_raiz_del_proyecto}",
project_name="{Nombre Visible}",
archetype_override=None # opcional: corporate|startup|creative|consumer|gen_z|gov
)
Esto crea doc/design/DESIGN.md con:
- YAML front-matter con
colors, typography, rounded, spacing, components (todos en hex codes o token references — nunca nombres de color)
- Body Markdown con secciones
Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts
El generador lee el Brand Kit recién creado (doc/brand/brand_kit.md),
el VEG si ya existe, y los documentos canónicos doc/app/app_prd.md /
doc/app/app_spec.md. Si falta cualquier input, completa con el
arquetipo VEG más cercano (default startup).
Inmediatamente después, registrar el DESIGN.md frente al proyecto Stitch:
upload_design_md_to_stitch(
project="{project-slug}",
stitch_project_id="{stitch_project_id}",
project_root="{absolute_path}"
)
Hoy esto registra DESIGN.md en meta.json con modo inline-prefix:
las herramientas de generación posteriores (Phase 4 fallback +
batched build) anteponen el contenido al prompt automáticamente. El
día que Google añada un endpoint nativo de attach, el comportamiento
upgradea sin requerir cambio del skill.
3.8 Confirmar DESIGN.md
DESIGN.md canónico generado:
├── Path: doc/design/DESIGN.md
├── Signature: {sha256_first_8}
├── Archetype detectado: {auto|override}
├── Secciones presentes: {sections_list}
└── Registrado en proyecto Stitch: {stitch_project_id} (modo inline-prefix)
A partir de ahora, /plan y /implement leerán este DESIGN.md como fuente
de verdad visual. Si modificas el Brand Kit, vuelve a correr este skill
o `generate_design_md_tool` para regenerarlo (idempotente).
Paso 4: Configurar VEG Base
Solo si no existe doc/veg/base/ o el usuario pidio regenerar.
4.1 Crear estructura
mkdir -p doc/veg/base
4.2 Generar VEG base
Crear doc/veg/base/veg-{project-slug}.md derivando TODAS las directivas del brand kit (no inventar):
# VEG: {Nombre del Producto} — Base
> Feature: Global (base para todas las features)
> Modo: uniforme
> Generado: {fecha}
## Contexto del Target
- **Quien**: {derivar del dominio — ej: "Profesionales financieros que gestionan inversiones"}
- **Referentes visuales**: {referentes de la estetica elegida}
- **Tolerancia visual**: {minimal / balanced / expressive — derivar de estetica}
- **Plataforma primaria**: {desktop-first / mobile-first}
## Pilar 1: Imagenes
### Estrategia de imagen
| Campo | Valor |
|-------|-------|
| Tipo | {derivar de estetica y dominio} |
| Mood | {derivar de estetica} |
| Paleta | {derivar de colores elegidos} |
| Sujetos | {derivar de dominio} |
### Prompts de imagen por seccion
| Seccion | Tipo | Prompt |
|---------|------|--------|
| Hero | {tipo} | "{prompt contextualizado al dominio y estetica}" |
| Features | {tipo} | "{prompt}" |
| Empty states | {tipo} | "{prompt}" |
| Backgrounds | {tipo} | "{prompt}" |
## Pilar 2: Motion
### Estrategia de motion
| Campo | Valor |
|-------|-------|
| Nivel | {derivar de estetica: calm→subtle, bold→moderate, minimal→subtle} |
| Personalidad | {derivar de estetica} |
### Catalogo de animaciones
| Tipo | Animacion | Duracion | Easing |
|------|-----------|----------|--------|
| page_enter | {derivar} | {N}ms | {derivar} |
| scroll_reveal | {derivar} | {N}ms | {derivar} |
| scroll_stagger_delay | — | {N}ms | — |
| hover_buttons | {derivar} | {N}ms | — |
| loading | {derivar} | — | — |
| transitions_pages | {derivar} | {N}ms | — |
| transitions_modals | {derivar} | {N}ms | — |
| feedback_success | {derivar} | — | — |
| feedback_error | {derivar} | — | — |
**Reglas de nivel:**
- subtle: SOLO page_enter + loading. Skip scroll, hover, feedback.
- moderate: Todos excepto feedback.
- expressive: Catalogo completo.
## Pilar 3: Diseno
### Estrategia de diseno
| Campo | Valor |
|-------|-------|
| Densidad | {derivar de estetica} |
| Whitespace | {derivar de estetica} |
| Separacion de secciones | {derivar de estetica} |
### Tipografia
| Campo | Valor |
|-------|-------|
| Heading weight | {derivar} |
| Body spacing | {derivar} |
| Hero scale | {derivar} |
### Jerarquia visual
| Campo | Valor |
|-------|-------|
| Estilo | {derivar de estetica y dominio} |
| CTA prominence | {derivar} |
| Data presentation | {derivar de dominio} |
## Form Factor Adaptations
### Desktop (>= 1024px)
- Layout: {derivar — ej: sidebar + main content area}
- Grid: 12 columnas, gap 24px
- Max width: 1280px centered
- Navigation: {top bar / sidebar / combined}
### Tablet (768px - 1023px)
- Layout: {derivar — ej: collapsible sidebar, stack secondary panels}
- Grid: 8 columnas, gap 16px
- Navigation: {hamburger / bottom tabs / collapsible sidebar}
### Mobile (< 768px)
- Layout: {derivar — ej: single column, bottom sheet for details}
- Grid: 4 columnas, gap 12px
- Navigation: {bottom tabs / hamburger}
- Touch targets: minimo 44px
## Resumen para inyeccion en sub-agentes (~400 tokens)
> Este bloque es lo que viaja a los sub-agentes dentro del context budget.
VEG [uniforme] Base: {Nombre del Producto}
Images: {type}, mood {mood}, palette {palette}
Motion: level {level}, personality {personality}
- page_enter: {animation} {duration}ms {easing}
- scroll: {animation} stagger {delay}ms
- loading: {style}
- transitions: {pages} {duration}ms
Design: density {density}, whitespace {whitespace}
- hierarchy: {style}, CTA {prominence}
- typography: heading {weight}, body {spacing}, hero {scale}
Form factors: {desktop-first|mobile-first}, breakpoints 640/768/1024/1280
Brand: {primary} + {secondary}, font {font-name}, radius {N}px
Reglas de derivacion por estetica:
| Estetica | Densidad | Whitespace | Motion Level | Hierarchy | CTA |
|---|
| Calm Enterprise | balanced | generous | subtle | card-based | medium |
| Bold Startup | balanced | moderate | moderate | full-bleed | high |
| Minimal Tool | compact | moderate | subtle | minimal | subtle |
| Financial Pro | compact | moderate | subtle | dashboard | medium |
| Health & Care | spacious | generous | moderate | card-based | medium |
| Developer DX | compact | moderate | subtle | dashboard | medium |
Paso 5: Configurar Multi-Form-Factor y Prompt Template
5.1 Actualizar settings.local.json
Leer .claude/settings.local.json actual (o crear si no existe) y MERGE con:
{
"stitch": {
"projectId": "{stitch_project_id}",
"designSystemAssetId": "{asset_id}",
"deviceType": "{DESKTOP|MOBILE}",
"modelId": "GEMINI_3_PRO",
"multiFormFactor": true,
"formFactors": ["DESKTOP", "TABLET", "MOBILE"],
"brandContextFile": "doc/brand/brand_kit/SKILL.md"
}
}
REGLA: Hacer MERGE con el JSON existente, no sobrescribir. Preservar todas las keys existentes (trello, plane, acceptance, etc.).
5.2 Generar doc/design/stitch-prompt-template.md
mkdir -p doc/design
# Stitch Prompt Template — {Nombre del Producto}
> Generado por /visual-setup — usar como base para TODAS las generaciones de pantalla.
> Design System Asset: {asset_id}
> Stitch Project: {stitch_project_id}
## Estructura del Prompt
Cada generacion de pantalla via `mcp__stitch__generate_screen_from_text` debe seguir esta estructura:
---
### Template
[SCREEN NAME]
{UC-XXX}: {nombre del use case}
[PURPOSE]
{descripcion funcional de la pantalla — que hace el usuario aqui}
[VISUAL DIRECTION]
{Pegar aqui el bloque "Resumen para inyeccion" del VEG base o del VEG de la feature}
[LAYOUT]
- Device: {DESKTOP|TABLET|MOBILE}
- Structure: {descripcion del layout — ej: "sidebar left 280px + main content area"}
- Sections: {enumerar secciones de arriba a abajo}
[CONTENT]
- Header: {que muestra}
- Main: {contenido principal}
- Sidebar/Secondary: {si aplica}
- Footer/Actions: {botones, acciones}
[COMPONENTS]
- {componente 1}: {especificacion — ej: "data table with 5 columns, sortable, paginated"}
- {componente 2}: {especificacion}
[INTERACTIONS]
- {interaccion 1}: {ej: "click row → expand detail panel right"}
- {interaccion 2}: {ej: "filter dropdown → update table in place"}
[RULES]
- ALWAYS use LIGHT MODE (dark mode is handled in code via CSS variables)
- Follow the Design System applied to this project (asset {asset_id})
- Use brand colors: primary {primary_hex}, secondary {secondary_hex}
- Font: {font_name} for all text
- Radius: {roundness_name} ({N}px)
- Minimum touch target: 44px on mobile
- Maintain 4.5:1 contrast ratio for all text
---
## Multi-Form-Factor Protocol
Para cada pantalla que requiera responsive, generar 3 versiones:
| # | Form Factor | Stitch deviceType | Nombre archivo |
|---|------------|-------------------|----------------|
| 1 | Desktop | DESKTOP | `{uc-id}_{screen-name}_desktop.html` |
| 2 | Tablet | TABLET | `{uc-id}_{screen-name}_tablet.html` |
| 3 | Mobile | MOBILE | `{uc-id}_{screen-name}_mobile.html` |
**Reglas:**
- Generar SIEMPRE desktop primero (es la referencia principal)
- Tablet y mobile se generan con el mismo prompt + adaptaciones de layout
- Para tablet: colapsar sidebar, reducir columnas de grid, reorganizar panels
- Para mobile: single column, bottom sheet para detalles, bottom tabs para nav
- Guardar en: `doc/design/{feature}/{uc-id}/`
## Seleccion de Modelo
| Complejidad | Modelo | Cuando usar |
|-------------|--------|-------------|
| Simple | GEMINI_3_FLASH | Pantallas con 1-3 secciones, formularios simples, paginas de confirmacion |
| Compleja | GEMINI_3_PRO | Dashboards, tablas de datos, multi-panel, pantallas con >3 secciones |
## Referencia Rapida
| Parametro | Valor |
|-----------|-------|
| Stitch Project ID | `{stitch_project_id}` |
| Design System Asset | `{asset_id}` |
| Primary Color | `{primary_hex}` |
| Secondary Color | `{secondary_hex}` |
| Font | `{font_name}` |
| Roundness | `{roundness_name}` |
| Color Mode | LIGHT (siempre) |
| Brand Context | `doc/brand/brand_kit/SKILL.md` |
| VEG Base | `doc/veg/base/veg-{slug}.md` |
Paso 6: Actualizar CLAUDE.md del Proyecto
6.1 Buscar CLAUDE.md del proyecto
ls CLAUDE.md 2>/dev/null
Si no existe → WARNING: "No se encontro CLAUDE.md en la raiz del proyecto. Creando seccion de diseno standalone en doc/brand/README.md."
6.2 Insertar seccion "Sistema de Diseno"
Buscar en CLAUDE.md un lugar apropiado para insertar (despues de "Stack" o "Estructura", antes de "Para contribuir"). Si ya existe una seccion de diseno, REEMPLAZARLA.
Insertar:
## Sistema de Diseno
> Configurado via `/visual-setup` — {fecha}
### Identidad Visual
| Campo | Valor |
|-------|-------|
| Estetica | {nombre estetica} ({referentes}) |
| Dominio | {dominio} |
| Primary | `{primary_hex}` |
| Secondary | `{secondary_hex}` |
| Font | {font_name} |
| Roundness | {roundness_name} ({N}px) |
| Device | {desktop-first / mobile-first} |
### Google Stitch
| Campo | Valor |
|-------|-------|
| Project ID | `{stitch_project_id}` |
| Design System | `{asset_id}` |
| Color Mode | LIGHT (dark mode via CSS vars) |
| Multi-Form-Factor | DESKTOP + TABLET + MOBILE |
### Brand Kit
| Archivo | Ruta |
|---------|------|
| Resumen agentes | `doc/brand/brand_kit/SKILL.md` |
| CSS Tokens | `doc/brand/brand_kit/variables.css` |
| Tailwind Config | `doc/brand/brand_kit/tailwind.config.js` |
| Light Theme | `doc/brand/brand_kit/light.md` |
| Dark Theme | `doc/brand/brand_kit/dark.md` |
### VEG & Design
| Archivo | Ruta |
|---------|------|
| VEG Base | `doc/veg/base/veg-{slug}.md` |
| Prompt Template | `doc/design/stitch-prompt-template.md` |
### Reglas de Diseno
1. Stitch genera SIEMPRE en Light Mode — dark mode se implementa en codigo con tokens CSS
2. Todo prompt de Stitch debe seguir `doc/design/stitch-prompt-template.md`
3. Cada pantalla genera 3 form factors (desktop, tablet, mobile) si `multiFormFactor: true`
4. El Design System Asset se aplica automaticamente a todas las pantallas generadas
5. El brand kit se inyecta como contexto en sub-agentes (AG-02, AG-06)
6.3 Actualizar estructura del monorepo en CLAUDE.md
Si CLAUDE.md tiene una seccion de estructura de archivos/carpetas, agregar:
├── doc/
│ ├── brand/
│ │ ├── brand_kit/
│ │ │ ├── SKILL.md ← Resumen compacto para agentes
│ │ │ ├── variables.css ← Tokens CSS (light + dark)
│ │ │ ├── tailwind.config.js ← Config Tailwind
│ │ │ ├── light.md ← Specs tema claro
│ │ │ └── dark.md ← Specs tema oscuro
│ │ └── brand_briefing.md ← (opcional) briefing original
│ ├── veg/
│ │ └── base/
│ │ └── veg-{slug}.md ← VEG base global
│ └── design/
│ └── stitch-prompt-template.md ← Template de prompts Stitch
Paso 7: Resumen y Validacion
7.1 Verificar completitud
Ejecutar checklist:
Verificacion de /visual-setup:
├── [x] Brand Kit generado en doc/brand/brand_kit/
│ ├── [x] SKILL.md (resumen agentes)
│ ├── [x] variables.css (tokens CSS)
│ ├── [x] tailwind.config.js
│ ├── [x] light.md
│ └── [x] dark.md
├── [x] Stitch configurado
│ ├── [x] Proyecto creado (ID: {id})
│ ├── [x] Design System creado (Asset: {id})
│ └── [x] settings.local.json actualizado
├── [x] VEG base generado
│ └── [x] doc/veg/base/veg-{slug}.md
├── [x] Multi-Form-Factor configurado
│ ├── [x] settings.local.json → multiFormFactor: true
│ └── [x] doc/design/stitch-prompt-template.md
├── [x] CLAUDE.md actualizado
│ ├── [x] Seccion "Sistema de Diseno"
│ └── [x] Estructura de archivos
└── [ ] Sin campos vacios en ningun archivo
7.2 Validar que no hay campos vacios
Buscar placeholders sin resolver:
grep -r "{.*}" doc/brand/brand_kit/ doc/veg/base/ doc/design/stitch-prompt-template.md 2>/dev/null
Si hay campos con {placeholder} → ERROR: listar y pedir al usuario los valores faltantes.
7.3 Mostrar resumen final
## /visual-setup completado
### Identidad Visual: {Nombre del Producto}
| Artefacto | Estado | Ubicacion |
|-----------|--------|-----------|
| Brand Kit | Generado | `doc/brand/brand_kit/` |
| Stitch Project | Creado | ID: `{stitch_project_id}` |
| Design System | Aplicado | Asset: `{asset_id}` |
| VEG Base | Generado | `doc/veg/base/veg-{slug}.md` |
| Prompt Template | Generado | `doc/design/stitch-prompt-template.md` |
| settings.local.json | Actualizado | `.claude/settings.local.json` |
| CLAUDE.md | Actualizado | `CLAUDE.md` |
### Siguiente paso
El proyecto esta listo para `/plan`. Al ejecutar `/plan`:
- Los disenos de Stitch usaran el Design System configurado
- El VEG base se inyectara como "Visual Direction" en cada prompt
- Los 3 form factors se generaran automaticamente (si multiFormFactor: true)
- Los sub-agentes (AG-02, AG-06) recibiran el brand kit como contexto
Manejo de Errores
Stitch API no disponible
¿Stitch responde?
├── SI → Continuar normalmente
└── NO → Generar TODOS los artefactos locales (brand kit, VEG, template)
└── WARNING: "Stitch no responde. Se generaron todos los artefactos locales.
Cuando Stitch este disponible, ejecuta /visual-setup de nuevo
para crear el proyecto y design system remotos."
└── Marcar en settings.local.json: "stitch.pendingSetup": true
Brand Kit parcial
¿El brand kit existente esta completo?
├── Tiene SKILL.md + variables.css → Completo, reusar
├── Solo tiene SKILL.md → Generar variables.css, tailwind, light.md, dark.md
├── Solo tiene variables.css → Generar SKILL.md, light.md, dark.md
└── Solo tiene briefing → Parsear y generar todo
Usuario cancela en medio
Todos los artefactos generados hasta el punto de cancelacion se mantienen. El usuario puede re-ejecutar /visual-setup y el skill detectara lo que ya existe (Paso 0) y completara lo que falta.
Referencia de Enums Stitch
Fuentes (headlineFont, bodyFont, labelFont)
| Enum | Nombre | Estilo |
|---|
| GEIST | Geist | Modern, clean, Vercel |
| INTER | Inter | Neutral, versatile |
| DM_SANS | DM Sans | Geometric, friendly |
| PLUS_JAKARTA_SANS | Plus Jakarta Sans | Elegant, modern |
| SPACE_GROTESK | Space Grotesk | Technical, distinctive |
| SORA | Sora | Geometric, balanced |
| IBM_PLEX_SANS | IBM Plex Sans | Corporate, reliable |
| MANROPE | Manrope | Warm, rounded |
| RUBIK | Rubik | Soft, approachable |
| SOURCE_SANS_THREE | Source Sans 3 | Clean, readable |
| MONTSERRAT | Montserrat | Bold, impactful |
| WORK_SANS | Work Sans | Professional, balanced |
| BE_VIETNAM_PRO | Be Vietnam Pro | Modern, geometric |
| EPILOGUE | Epilogue | Contemporary, editorial |
| LEXEND | Lexend | Readable, accessibility |
| NEWSREADER | Newsreader | Serif, editorial |
| NOTO_SERIF | Noto Serif | Classic, serif |
| PUBLIC_SANS | Public Sans | Government, neutral |
| SPLINE_SANS | Spline Sans | Clean, tech |
| DOMINE | Domine | Serif, formal |
| LIBRE_CASLON_TEXT | Libre Caslon Text | Serif, elegant |
| EB_GARAMOND | EB Garamond | Serif, classic |
| LITERATA | Literata | Serif, reading |
| SOURCE_SERIF_FOUR | Source Serif 4 | Serif, versatile |
| METROPOLIS | Metropolis | Geometric, urban |
| NUNITO_SANS | Nunito Sans | Rounded, friendly |
| ARIMO | Arimo | Neutral, Arial-like |
| HANKEN_GROTESK | Hanken Grotesk | Clean, modern |
Roundness
| Enum | CSS | UI Name |
|---|
| ROUND_FOUR | 4px | Sharp |
| ROUND_EIGHT | 8px | Medium |
| ROUND_TWELVE | 12px | Rounded |
| ROUND_FULL | 9999px | Full/Pill |
Color Variant
| Enum | Descripcion | Mejor para |
|---|
| TONAL_SPOT | Harmonious palette from seed | Default seguro, enterprise |
| VIBRANT | Saturated, energetic | Startups, consumer |
| NEUTRAL | Restrained, functional | Minimal, tools |
| FIDELITY | True to chosen color | Financial, brand-strict |
| EXPRESSIVE | Distinct, personality | Developer, creative |
| MONOCHROME | Single hue variations | Ultra-minimal |
| CONTENT | Derived from content | Media, galleries |
| RAINBOW | Full spectrum | Playful, kids |
| FRUIT_SALAD | Colorful, varied | Fun, casual |
Color Mode
| Enum | Nota |
|---|
| LIGHT | SIEMPRE usar LIGHT — Stitch solo genera bien en light mode |
| DARK | No usar — dark mode se implementa en codigo con CSS vars |
Device Type
| Enum | Breakpoint |
|---|
| DESKTOP | >= 1024px |
| TABLET | 768px - 1023px |
| MOBILE | < 768px |
AGNOSTIC aparecía en versiones previas de la documentación pero no existe en el MCP real de Stitch (verificado vía tools/list en v6.4.0). Usar DESKTOP como fallback.
Modo --migrate-stitch (v6.5.0)
Sub-comando que migra un proyecto del contrato legacy inline_prefix_v1 al chain nativo native_v2 (DESIGN.md → create_design_system_from_design_md → apply_design_system). Documentado end-to-end en doc/migrations/v7_stitch_native_chain.md. Cutover duro previsto para v7.0.
Cuándo usarlo
- El usuario dice "migrar stitch", "pasar a chain nativa", "migrate stitch", "actualizar contrato stitch".
upgrade_project emitió un hint stitch_migration_pending.- Antes de empezar a trabajar en un proyecto v5.x con Stitch ya cableado.
Pasos
0. Pre-check
- Lee
.claude/settings.local.json del proyecto cliente (no del MCP).
- Lee
doc/design/DESIGN.md si existe.
- Cuenta los HTML generados en
doc/design/{feature}/*.html (estimación del nº de pantallas previas).
- Llama:
detect_stitch_migration_case(
project="<slug>",
settings_local_json=<text>,
design_md_content=<text>,
generated_screens_count=<int>
)
- Toma el
case (A-F) y el recommended_action.
1. Pide la recipe
migrate_project_to_native_v2(
project="<slug>",
case="<A|B|C|D|E|F>",
settings_local_json=<text>,
design_md_content=<text>
)
Devuelve {actions, files_to_write, stitch_calls, settings_patch, confirmation_required, notes}.
2. Presenta el plan al usuario
- Muestra
actions en orden + notes.
- Si
confirmation_required no es null, dile al usuario el literal exacto que debe escribir (e.g., MIGRATE-RETROACTIVE para case D, APPLY-PROPOSAL para case E).
- Si el caso es
A, sal sin hacer nada.
3. Ejecuta cada action en orden
| Action ID | Operación |
|---|
noop | Nada |
set_contract_native_v2 | Aplica settings_patch a .claude/settings.local.json |
backup_design_md / backup_design_md_if_present | Renombra DESIGN.md → DESIGN.md.pre-migration.bak |
regenerate_design_md_as_native_v2 | Llama generate_design_md_tool(contract="native_v2", ...) |
create_stitch_project_if_missing | Llama stitch_create_project si no hay stitch.projectId |
upload_design_md_via_rest_batch_create | Llama stitch_upload_design_md (auto-elige REST si >5KB) |
create_design_system_from_design_md | Llama stitch_create_design_system_from_design_md |
list_design_systems | Llama stitch_list_design_systems |
list_screens | Llama stitch_list_screens (para case D) |
preview_apply_design_system | Toma 3 screens representativas + fetch_screen_image antes y después, presenta al usuario |
WAIT_FOR_LITERAL_CONFIRMATION | Bloquea hasta que el usuario escriba el literal exacto |
apply_design_system_to_all_screens | Loop stitch_apply_design_system por instance |
generate_mapping_proposal_material3 | Construye Material 3 candidate desde el DESIGN.md custom |
WRITE_PROPOSAL_FOR_REVIEW | Escribe doc/design/migration_proposal_material3.md |
delegate_to_orchestrator | Para case F satellite: terminar y dirigir al orchestrator |
4. Telemetría
Tras cada acción exitosa, append a .quality/logs/stitch-migration.jsonl:
{"ts": "<iso>", "project": "<slug>", "case": "<A-F>", "action": "<id>", "outcome": "ok|fail|skipped"}
5. Rollback
Si una acción falla a mitad:
- DESIGN.md.pre-migration.bak permanece (paso 3 lo creó primero).
settings.local.json no se ha modificado hasta set_contract_native_v2 (último step).- Stitch project queda en estado intermedio: el usuario puede borrarlo desde la UI Stitch o ejecutar de nuevo
--migrate-stitch (la recipe es idempotente).
Casos resumidos
- A: ya en
native_v2 → no-op.
- B: Stitch configurado sin uso → flip de marker, no migración real.
- C: DESIGN.md sin Stitch project → backup + regen + bootstrap.
- D: Stitch project con screens → backup + regen + bootstrap + preview + literal
MIGRATE-RETROACTIVE + apply a todas las instances.
- E: DESIGN.md custom → genera mapping_proposal_material3.md + literal
APPLY-PROPOSAL.
- F: Multirepo → solo orchestrator migra.
