visual-setup

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:

1. Usa Read localmente sobre doc/app/app_prd.md y doc/app/app_spec.md.
2. 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

# Detectar brand kit
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

# Detectar VEG base
ls doc/veg/base/ 2>/dev/null

# Detectar Stitch config
cat .claude/settings.local.json 2>/dev/null | grep -E "stitch|projectId|designSystem"

# Detectar prompt template
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:

1. Llamar mcp__stitch__get_project con ese projectId
2. Si responde OK → reusar proyecto existente
3. 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:

/* Brand Kit — {Nombre del Producto}
 * Generated by /visual-setup
 * Estetica: {estetica}
 */

:root {
  /* === Primary === */
  --color-primary: {primary};
  --color-primary-hover: {primary-600};
  --color-primary-active: {primary-700};
  --color-primary-subtle: {primary-50};
  --color-on-primary: #FFFFFF;

  /* === Secondary === */
  --color-secondary: {secondary};
  --color-secondary-hover: {secondary-600};
  --color-secondary-active: {secondary-700};
  --color-secondary-subtle: {secondary-50};
  --color-on-secondary: #FFFFFF;

  /* === Accent === */
  --color-accent: {accent};
  --color-accent-subtle: {accent-50};

  /* === Semantic === */
  --color-success: #10B981;
  --color-warning: #F59E0B;
  --color-error: #EF4444;
  --color-info: #3B82F6;

  /* === Neutral === */
  --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};

  /* === Surfaces === */
  --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};

  /* === Text === */
  --color-text-primary: #1E293B;
  --color-text-secondary: #64748B;
  --color-text-tertiary: #94A3B8;
  --color-text-inverse: #F1F5F9;

  /* === Typography === */
  --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;

  /* === Sizes === */
  --text-xs: 0.75rem;    /* 12px */
  --text-sm: 0.875rem;   /* 14px */
  --text-base: 1rem;     /* 16px */
  --text-lg: 1.125rem;   /* 18px */
  --text-xl: 1.25rem;    /* 20px */
  --text-2xl: 1.5rem;    /* 24px */
  --text-3xl: 1.875rem;  /* 30px */
  --text-4xl: 2.25rem;   /* 36px */

  /* === Spacing === */
  --space-1: 0.25rem;    /* 4px */
  --space-2: 0.5rem;     /* 8px */
  --space-3: 0.75rem;    /* 12px */
  --space-4: 1rem;       /* 16px */
  --space-6: 1.5rem;     /* 24px */
  --space-8: 2rem;       /* 32px */
  --space-12: 3rem;      /* 48px */
  --space-16: 4rem;      /* 64px */

  /* === Radius === */
  --radius-sm: {radius-sm}px;
  --radius-md: {radius-md}px;
  --radius-lg: {radius-lg}px;
  --radius-full: 9999px;

  /* === Shadows === */
  --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);
}

/* === Dark Mode === */
[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

// Brand Kit — {Nombre del Producto}
// Generated by /visual-setup

/** @type {import('tailwindcss').Config} */
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.