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.
Scanned 6/1/2026
Install via CLI
Skills Directoryopenskills install EmbedBuild/specbox-engine---
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
```
```bash
# 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:
```markdown
## 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
```bash
mkdir -p doc/brand/brand_kit
```
### 2.2 Generar `variables.css`
Archivo con CSS custom properties para light y dark mode:
```css
/* 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`
```javascript
// 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.
```markdown
# 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)
```markdown
# {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)
```markdown
# {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 3: Configurar Google Stitch
### 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:
```markdown
# {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
```bash
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):
```markdown
# 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:
```json
{
"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`
```bash
mkdir -p doc/design
```
```markdown
# 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
```bash
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:
```markdown
## 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:
```bash
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
```markdown
## /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](../../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`:
```json
{"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.
No comments yet. Be the first to comment!
