Koubou

Koubou: Generador de Capturas de Pantalla para la App Store

Genera capturas de pantalla profesionales para la App Store usando plantillas HTML/CSS con más de 100 marcos de dispositivos reales, localización mediante xcstrings y dimensiones precisas de Apple.

Las capturas de pantalla son anuncios, no documentación. Cada diapositiva vende un sentimiento, un resultado o la solución a un punto de dolor.

Las instrucciones del usuario siempre tienen prioridad sobre los valores predeterminados en esta habilidad.

La dirección creativa está abierta por defecto. Usa las reglas de esta habilidad para imponer impacto, legibilidad y escala consciente del lienzo, no para hacer que todos los conjuntos se vean iguales.

Jerarquía de Reglas

Trata las directrices de esta habilidad en este orden:

1. Restricciones estrictas — legibilidad, escala, claridad de miniatura, marketing veraz del producto y conciencia real del lienzo
2. Valores predeterminados sólidos — variedad, asimetría, superposición, ritmo y evitar diseños genéricos
3. Preferencias de gusto — heurísticas anti-basura y valores predeterminados estilísticos que pueden romperse cuando una idea más fuerte mejora claramente el trabajo

Si romper un valor predeterminado produce un mejor conjunto de capturas, rómpelo deliberadamente y explica la compensación a ti mismo antes de generar.

Archivos de referencia (léelos según sea necesario, no de antemano):

• setup.md — Instalación y configuración del entorno de ejecución HTML
• design-guide.md — Principios de diseño, reglas de redacción, reglas CSS, ejemplos de plantillas HTML
• style-intake.md — Cómo inspeccionar el lenguaje visual real de la aplicación antes de hacer preguntas
• style-interview.md — Preguntas de estilo cortas y de alta señal y patrones de conversación
• yaml-reference.md — Formato de configuración YAML, localización, assets, dispositivos, tamaños
• capabilities-reference.md — Capacidades completas de koubou (modo de contenido, destacados, zoom, degradados)

Fase 1: Configuración (silenciosa, automática)

Verifica primero si kou está disponible. No reinstales ni toques el empaquetado de Python si kou ya funciona.

Orden preferido:

kou --version 2>/dev/null

Si kou --version tiene éxito:

• trata koubou como instalado
• no ejecutes pip, pip3 o playwright install
• no intentes "actualizar" o "arreglar" el entorno del usuario de manera proactiva
• siempre ejecuta kou setup-html antes de generar, porque esta habilidad es solo HTML y el comando está diseñado para ser seguro de repetir

Si kou --version falla, lee setup.md y sigue la ruta menos invasiva para el entorno.

Para soporte de renderizado HTML:

• siempre usa kou setup-html
• no lo omitas solo porque HTML funcionó en una ejecución anterior
• no ejecutes playwright install chromium directamente

Solo informa al usuario si la configuración falla. Nunca modifiques una instalación que funciona.

Fase 2: Lee la Aplicación, Luego Pregunta

No comiences con un cuestionario de estilo genérico. Primero inspecciona el lenguaje visual real de la aplicación, luego pregunta solo lo que aún falta o es ambiguo.

Lee style-intake.md antes de hacer preguntas de estilo. Sigue este orden.

2.1 Descubrimiento de estilo (obligatorio antes de las preguntas de estilo)

Primero inspecciona las fuentes del proyecto local. Busca automáticamente antes de preguntar al usuario por dirección visual.

Prioriza estas fuentes:

1. Assets.xcassets, iconos de aplicación, ilustraciones, logotipos, assets de color
2. Capturas de pantalla existentes y carpetas de marketing:
   • .maestro/
   • screenshots/
   • AppStore/
   • fastlane/screenshots/
   • marketing/
3. Documentación del producto y posicionamiento:
   • README*
   • CLAUDE.md
   • planes de lanzamiento, texto de páginas de destino, carpetas de documentación
4. Tokens de diseño y código de UI:
   • Variables CSS
   • Colores de SwiftUI, degradados, materiales, opciones tipográficas
   • archivos de tema web y constantes de diseño compartidas
5. Artefactos anteriores de la App Store si existen:
   • plantillas anteriores
   • campañas de capturas antiguas
   • assets de marketing localizados

Extrae y resume al menos estas señales:

• colores dominantes y colores de acento
• contraste general: oscuro, claro, mixto, apagado, vívido
• densidad de UI: aireada, equilibrada, densa
• lenguaje de formas: afilado, suave, redondeado, con muchas tarjetas, plano
• estilo de iconografía e ilustración
• dirección tipográfica si es visible
• tono del texto: tranquilo, técnico, juguetón, premium, cálido, urgente
• si la aplicación se siente tranquila, técnica, cálida, enérgica, pulida, juguetona, etc.

Si el estilo de la aplicación es claro:

• resume las señales detectadas al usuario en lenguaje sencillo
• confirma que construirás a partir de esa dirección en lugar de reiniciar desde un lenguaje de plantilla genérico

Si las señales son débiles, faltan o son contradictorias:

• di lo que encontraste
• haz preguntas de seguimiento enfocadas sobre la incertidumbre en lugar de preguntar un cuestionario de diseño amplio

2.2 Entrevista de intención (corta, de alta señal)

Lee style-interview.md y pregunta solo lo mínimo necesario. Mantenlo conversacional. No vuelques todas las preguntas a la vez.

Preguntas de estilo requeridas cuando aún sean necesarias:

1. ¿Qué sentimiento debe proyectar la campaña: premium, juguetón, editorial, utilitario, técnico, cálido, etc.?
2. ¿Hay referencias de la App Store, marcas o conjuntos de capturas que deban influir en la dirección?
3. ¿Qué está visualmente prohibido: degradados llamativos, glassmorfismo, solo oscuro, cuadrículas de tarjetas, estilo demasiado juguetón, etc.?
4. ¿Qué rasgo visual de la aplicación en sí debe seguir siendo reconocible en las capturas de pantalla?

Preguntas opcionales solo cuando aún no estén resueltas:

5. Dirección tipográfica preferida o personalidad de la fuente
6. Sesgo claro, oscuro o mixto
7. Preferencia de densidad: más aire vs más información
8. Si el conjunto debe sentirse estrictamente consistente o visiblemente variado entre diapositivas

2.3 Información del producto (aún requerida)

Después de que comience el descubrimiento de estilo, recopila las entradas de producción restantes de forma natural:

1. Aplicación: Nombre, qué hace (1 frase), propuesta de valor principal
2. Capturas de pantalla: ¿Dónde están las capturas de la aplicación? Busca automáticamente primero:
   • Si se encuentran, muestra lo que encontraste y confirma
   • Si no se encuentran, pregunta cómo las genera el usuario
   • Prefiere capturas limpias del simulador que muestren la UI de la aplicación claramente. Si el usuario puede elegir, prefiere capturas recientes de iPhone de 6.1 pulgadas como material de origen
3. Funciones a destacar: Lista priorizada de funciones/beneficios (recomienda 3-5). Cada diapositiva = 1 función
4. Activos principales: Icono de la aplicación u otro activo de marca. Busca automáticamente antes de preguntar
5. Número de diapositivas: Cuántas capturas de pantalla (recomienda 3-5 para empezar, Apple permite hasta 10)

Opcional solo si es relevante:

6. Dispositivo: El valor predeterminado es iPhone 16 Pro - Black Titanium - Portrait. Solo pregunta si iPad/Mac/otro tiene sentido
7. Localización: Solo si el proyecto ya tiene xcstrings o soporte para múltiples idiomas
8. Activos adicionales: Elementos de UI flotantes, insignias, ilustraciones de apoyo
9. Restricciones adicionales: Afirmaciones requeridas, estilos prohibidos o restricciones de marketing

2.4 Decisión de estilo (obligatoria antes de HTML)

Antes de redactar plantillas, decide explícitamente y bloquea internamente estos seis elementos:

• señales de marca detectadas
• estilo de campaña elegido
• voz del texto
• sistema de fondo
• ritmo de composición del dispositivo
• plan de variación entre diapositivas

Cada elemento debe estar justificado por:

• evidencia de la aplicación del descubrimiento de estilo, o
• comentarios directos del usuario de la entrevista

Si no puedes justificar uno de estos, sigue haciendo preguntas enfocadas antes de diseñar.

Derivado (NO preguntes a menos que estés bloqueado)

• Degradados de fondo o texturas a partir de los colores de la marca y el estado de ánimo de la UI
• Distribución del diseño (héroe → función-superior → función-inferior → alternado)
• Texto del titular a partir de las funciones y la propuesta de valor
• Paleta secundaria a partir de la paleta real de la aplicación
• Clase de lienzo a partir de project.device + project.output_size mediante kou inspect-frame
• Si el nombre de la aplicación debe aparecer o no. Valor predeterminado: omítelo a menos que agregue valor real de marca en un tamaño legible
• Si el icono de la aplicación debe aparecer. Valor predeterminado: úsalo con moderación en diapositivas héroe o de cierre, no como un marcador decorativo pequeño

Principio: si el contexto está disponible localmente, úsalo antes de preguntar. Las preguntas de estilo vienen después de la inspección, no antes.

Fase 3: Generar

Lee design-guide.md antes de generar plantillas. Lee yaml-reference.md antes de escribir la configuración.

1. Crea un directorio de trabajo (por ejemplo, AppStore/ o donde tenga sentido para el proyecto)

2. Ejecuta kou setup-html

3. Lee project.device y project.output_size del YAML

4. Ejecuta kou inspect-frame "<dispositivo>" --output-size <tamaño> --output json y usa esa geometría antes de escribir CSS

5. Redacta el arco narrativo y 2-3 opciones de titular/subtítulo por diapositiva antes de tocar el diseño. Elige primero el más fuerte. La calidad del texto es antes que el CSS

6. Traduce la decisión de estilo a un resumen de campaña:

   • cómo debería sentirse el conjunto
   • qué motivos están permitidos
   • qué motivos están prohibidos
   • cuánta variación deben mostrar las primeras 5 diapositivas

7. Crea templates/ con plantillas HTML — mínimo 3 diseños distintos, y las primeras 3 diapositivas no deben repetir el mismo arquetipo de composición

8. En cada plantilla HTML, agrega data-kou-id y data-kou-role a estos elementos antes de escribir cualquier CSS:

   • Titular principal: data-kou-id="headline" data-kou-role="headline"
   • Texto de apoyo: data-kou-id="subtitle" data-kou-role="supporting"
   • Imagen del dispositivo principal: data-kou-id="device" data-kou-role="device"
   • Títulos/subs de funciones (diapositivas de cierre/características): data-kou-id="feature-N-title" data-kou-role="feature-title", data-kou-id="feature-N-sub" data-kou-role="feature-sub"

   Sin estos, el array elements del sidecar de diseño estará vacío y el control de calidad posterior al renderizado estará ciego. Consulta los ejemplos de plantilla en design-guide.md para patrones de anotación correctos.

9. Crea config.yaml con la configuración de koubou (lee yaml-reference.md para el formato)

10. Usa CSS que se adapte al lienzo y la longitud del texto: usa vw o clamp() deliberadamente, prefiere CSS Grid, superposición y capas posicionadas absolutamente, y verifica la escala de texto final calculada en el lienzo real

11. Antes de escribir HTML: planifica zonas de texto/dispositivo para cada diapositiva (qué área posee qué porcentaje del lienzo). No comiences CSS hasta que las zonas estén claras

12. Ejecuta: kou generate config.yaml --output json

13. Para cada captura HTML generada, lee layout_path del resultado JSON e inspecciona el sidecar antes de decidir que el diseño es aceptable

14. Control de calidad posterior al renderizado (obligatorio — no lo omitas):

    • Revisa visualmente cada diapositiva generada
    • Abre cada archivo *.layout.json del sidecar referenciado por layout_path
    • Verifica contra la lista de rechazo en design-guide.md
    • Verifica que el conjunto renderizado aún refleje el estilo de la aplicación que descubriste en lugar de los valores predeterminados genéricos de la App Store
    • Usa el JSON de diseño solo para geometría objetiva: posiciones, espacio ocupado, proporciones y superposiciones matemáticas
    • Si elements está vacío para una diapositiva HTML que debería medirse, trata eso como una anotación faltante o rota y corrige la plantilla
    • Verifica: sin iconos emoji, sin cuadrículas de tarjetas idénticas, sin dispositivos descentrados, sin texto por debajo de la escala mínima, sin recorte de dispositivo no intencional (la parte superior/muesca del dispositivo debe ser visible en diapositivas héroe; el contenido de la pantalla debe ser legible)
    • Aplica la prueba de intercambio de logotipos: ¿funcionarían estas diapositivas para un competidor?
    • Si alguna diapositiva falla, corríge y regenera antes de mostrar al usuario

15. Abre la carpeta de salida: open <directorio_salida>

16. Pregunta si el usuario desea ajustes — itera en diapositivas específicas sin regenerar todo

Reglas de Iteración

• Cuando el usuario pida cambiar una diapositiva específica, solo modifica esa plantilla + entrada de configuración
• Cuando el usuario pida un cambio de estilo global (colores, fuentes, estado de ánimo, densidad, negrita), actualiza todas las plantillas
• Vuelve a ejecutar kou generate config.yaml --output json después de los cambios para que los nuevos valores de layout_path y sidecars se mantengan sincronizados
• Usa kou live config.yaml si el usuario desea una vista previa en tiempo real mientras edita
• Si una diapositiva se siente pequeña, primero aumenta la escala o cambia el diseño. No ocultes el problema con degradados o etiquetas adicionales
• Si el texto fuerza un tamaño de letra pequeño, reescribe el texto o elige un diseño más adecuado; nunca aceptes una diapositiva tímida porque "el texto tenía que caber"
• Mantén la variedad alta: el objetivo es la consistencia de la campaña, no la repetición del diseño
• No te detengas después del primer renderizado exitoso si la salida aún viola las reglas de diseño o la lista de verificación de rechazo
• Si el usuario pide un cambio de estado de ánimo, reinterpreta todo el conjunto dentro de los límites de calidad en lugar de defender los valores predeterminados anteriores
• Si la captura de pantalla y el JSON de diseño no están de acuerdo, confía en la captura renderizada para el gusto e investiga la anotación o el tiempo de renderizado en lugar de forzar una decisión de diseño desde una geometría obsoleta

Reglas Estrictas

Restricciones estrictas

• Nunca uses emoji como iconos — usa formas CSS (barras de acento, puntos) o solo texto
• Nunca uses frases de texto prohibidas — "revolucionario", "sin interrupciones", "desbloquear", "innovador", etc.
• Aplica la prueba de intercambio de logotipos — si el nombre de un competidor encajaría, el conjunto es demasiado genérico
• Cada plantilla HTML debe tener anotaciones data-kou-id — como mínimo: headline, subtitle y device. Si elements en el sidecar de diseño está vacío después de la generación, faltan anotaciones — corrige la plantilla antes de que pase el control de calidad. No presentes diapositivas sin anotaciones al usuario.

Escala

• En iPhone vertical alto (iPhone6_9, iPhone6_7), los titulares héroe deben ser >=10vw, titulares de diseño lateral >=10vw, subtítulos >=4.5vw
• Usa vw o clamp() solo si el tamaño calculado aún supera el mínimo en el lienzo objetivo
• En diapositivas de contraste o cierre, el clúster de contenido debe ocupar el 60%+ de la altura del lienzo

Valores predeterminados sólidos

• No uses la misma composición de teléfono vertical y centrada en diapositivas consecutivas
• No dejes grandes bandas vacías (>15% de la altura del lienzo) entre el titular y el dispositivo
• Evita combinar rotate() + translate() en dispositivos centrados a menos que el centro visual aún se sienta intencional después del renderizado
• No uses una simple columna flexible centrada cuando la diapositiva necesite superposición, recortes que rompan el borde o composición en capas
• Planifica zonas de texto/dispositivo antes de escribir CSS (consulta la Planificación de Zonas Dispositivo-Texto en design-guide.md)
• Si usas cuadrículas de tarjetas, escalona, enfatiza o simplifícalas a menos que una cuadrícula estricta sirva genuinamente al concepto

Contenido

• No agregues pequeñas etiquetas superiores, etiquetas de categoría o encabezados de nombre de aplicación por defecto
• No renderices el nombre de la aplicación como texto decorativo pequeño a menos que sea claramente legible