bitomule/Koubou

Koubou: Gerador de Capturas de Tela para a App Store

Gere capturas de tela profissionais para a App Store usando templates HTML/CSS com mais de 100 molduras reais de dispositivos, localização via xcstrings e dimensões perfeitas da Apple.

Capturas de tela são anúncios, não documentação. Cada slide vende um sentimento, resultado ou solução de ponto de dor.

As instruções do usuário sempre têm prioridade sobre os padrões nesta skill.

A direção criativa é aberta por padrão. Use as regras desta skill para impor impacto, legibilidade e escala consciente da tela, não para fazer cada conjunto parecer igual.

Hierarquia de Regras

Trate as orientações nesta skill nesta ordem:

1. Restrições rígidas — legibilidade, escala, clareza de miniaturas, marketing honesto do produto e consciência real da tela
2. Padrões fortes — variedade, assimetria, sobreposição, ritmo e evitar layouts genéricos
3. Preferências estilísticas — heurísticas anti-banalidade e padrões estilísticos que podem ser quebrados quando uma ideia mais forte melhora claramente o trabalho

Se quebrar um padrão produzir um conjunto de capturas melhor, quebre-o deliberadamente e explique a troca para si mesmo antes de gerar.

Arquivos de referência (leia conforme necessário, não antecipadamente):

• setup.md — Instalação e configuração do runtime HTML
• design-guide.md — Princípios de design, regras de redação, regras CSS, exemplos de templates HTML
• style-intake.md — Como inspecionar a linguagem visual real do aplicativo antes de fazer perguntas
• style-interview.md — Perguntas de estilo curtas e de alto sinal e padrões de conversa
• yaml-reference.md — Formato de config YAML, localização, assets, dispositivos, tamanhos
• capabilities-reference.md — Capacidades completas do koubou (modo de conteúdo, destaques, zoom, gradientes)

Fase 1: Configuração (silenciosa, automática)

Verifique se kou está disponível primeiro. Não reinstale ou mexa em pacotes Python se kou já funcionar.

Ordem preferida:

kou --version 2>/dev/null

Se kou --version for bem-sucedido:

• considere o koubou instalado
• não execute pip, pip3 ou playwright install
• não tente "atualizar" ou "corrigir" o ambiente do usuário proativamente
• sempre execute kou setup-html antes de gerar, porque esta skill é apenas HTML e o comando foi projetado para ser seguro de repetir

Se kou --version falhar, leia setup.md e siga o caminho menos invasivo para o ambiente.

Para suporte à renderização HTML:

• sempre use kou setup-html
• não pule isso só porque o HTML funcionou em uma execução anterior
• não execute playwright install chromium diretamente

Informe o usuário apenas se a configuração falhar. Nunca mude uma instalação funcional.

Fase 2: Leia o Aplicativo, Depois Pergunte

Não comece com um questionário de estilo genérico. Inspecione a linguagem visual real do aplicativo primeiro, depois pergunte apenas o que ainda está faltando ou ambíguo.

Leia style-intake.md antes de fazer perguntas de estilo. Siga esta ordem.

2.1 Descoberta de estilo (obrigatória antes de perguntas de estilo)

Inspecione as fontes do projeto local primeiro. Pesquise automaticamente antes de perguntar ao usuário por direção visual.

Priorize estas fontes:

1. Assets.xcassets, ícones do app, ilustrações, logotipos, assets de cor
2. Pastas de capturas de tela e marketing existentes:
   • .maestro/
   • screenshots/
   • AppStore/
   • fastlane/screenshots/
   • marketing/
3. Documentos e posicionamento do produto:
   • README*
   • CLAUDE.md
   • planos de lançamento, texto da landing page, pastas de documentação
4. Tokens de design e código de UI:
   • Variáveis CSS
   • Cores SwiftUI, gradientes, materiais, escolhas tipográficas
   • arquivos de tema web e constantes de design compartilhadas
5. Artefatos anteriores da App Store, se existirem:
   • templates anteriores
   • campanhas de capturas antigas
   • assets de marketing localizados

Extraia e resuma pelo menos estes sinais:

• cores dominantes e cores de destaque
• contraste geral: escuro, claro, misturado, suave, vívido
• densidade da UI: arejada, equilibrada, densa
• linguagem de formas: nítida, suave, arredondada, pesada em cartões, plana
• estilo de iconografia e ilustração
• direção tipográfica se visível
• tom do texto: calmo, técnico, brincalhão, premium, acolhedor, urgente
• se o aplicativo parece calmo, técnico, acolhedor, energético, polido, brincalhão, etc.

Se o estilo do aplicativo estiver claro:

• resuma os sinais detectados ao usuário em linguagem clara
• confirme que você construirá a partir dessa direção em vez de recomeçar de uma linguagem de template genérica

Se os sinais forem fracos, ausentes ou contraditórios:

• diga o que encontrou
• faça perguntas de acompanhamento focadas na incerteza em vez de fazer um questionário de design amplo

2.2 Entrevista de intenção (curta, de alto sinal)

Leia style-interview.md e pergunte apenas o mínimo necessário. Mantenha-o conversacional. Não despeje todas as perguntas de uma vez.

Perguntas de estilo obrigatórias quando ainda necessárias:

1. Qual sentimento a campanha deve projetar: premium, brincalhão, editorial, utilitário, técnico, acolhedor, etc.?
2. Existem referências da App Store, marcas ou conjuntos de capturas que devem influenciar a direção?
3. O que é visualmente proibido: gradientes chamativos, glassmorfismo, apenas escuro, grades de cartões, estilo excessivamente brincalhão, etc.?
4. Qual traço visual do próprio aplicativo ainda deve ser reconhecível nas capturas?

Perguntas opcionais apenas quando ainda não resolvidas:

5. Direção tipográfica preferida ou personalidade da fonte
6. Viés claro, escuro ou misto
7. Preferência de densidade: mais ar versus mais informação
8. Se o conjunto deve parecer firmemente consistente ou visivelmente variado entre os slides

2.3 Informações do produto (ainda necessárias)

Após o início da descoberta de estilo, colete as entradas de produção restantes naturalmente:

1. App: Nome, o que faz (1 frase), principal proposta de valor
2. Capturas: Onde estão as capturas do app? Pesquise automaticamente primeiro:
   • Se encontrado, mostre o que encontrou e confirme
   • Se não encontrado, pergunte como o usuário as gera
   • Prefira capturas limpas do simulador que mostrem a UI do app claramente. Se o usuário puder escolher, prefira capturas recentes de iPhone 6.1 polegadas como material de origem
3. Recursos a destacar: Lista priorizada de recursos/benefícios (recomende 3-5). Cada slide = 1 recurso
4. Assets heróicos: Ícone do app ou outro asset de marca. Pesquise automaticamente antes de perguntar
5. Número de slides: Quantas capturas (recomende 3-5 para começar, a Apple permite até 10)

Opcional apenas se relevante:

6. Dispositivo: O padrão é iPhone 16 Pro - Black Titanium - Portrait. Só pergunte se iPad/Mac/outro fizer sentido
7. Localização: Apenas se o projeto já tiver xcstrings ou suporte a múltiplos idiomas
8. Assets extras: Elementos de UI flutuantes, medalhas, ilustrações de suporte
9. Restrições adicionais: Alegações obrigatórias, estilos proibidos ou restrições de marketing

2.4 Decisão de estilo (obrigatória antes do HTML)

Antes de criar templates, decida explicitamente e bloqueie internamente estes seis itens:

• sinais da marca detectados
• estilo de campanha escolhido
• voz do texto
• sistema de fundo
• ritmo de composição do dispositivo
• plano de variação entre slides

Cada item deve ser justificado por:

• evidência do aplicativo da descoberta de estilo, ou
• feedback direto do usuário da entrevista

Se você não puder justificar um destes, continue fazendo perguntas focadas antes de projetar.

Derivados (NÃO pergunte a menos que esteja bloqueado)

• Gradientes ou texturas de fundo das cores da marca e do mood da UI
• Distribuição do layout (herói → recurso-topo → recurso-base → alternado)
• Texto do título a partir dos recursos e proposta de valor
• Paleta secundária a partir da paleta real do aplicativo
• Classe da tela a partir de project.device + project.output_size via kou inspect-frame
• Se o nome do aplicativo deve aparecer. Padrão: omita, a menos que adicione valor real de marca em tamanho legível
• Se o ícone do aplicativo deve aparecer. Padrão: use com moderação em slides heróicos ou de encerramento, não como um marcador decorativo minúsculo

Princípio: se o contexto estiver disponível localmente, use-o antes de perguntar. As perguntas de estilo vêm após a inspeção, não antes.

Fase 3: Gerar

Leia design-guide.md antes de gerar templates. Leia yaml-reference.md antes de escrever a configuração.

1. Crie diretório de trabalho (ex.: AppStore/ ou onde fizer sentido para o projeto)

2. Execute kou setup-html

3. Leia project.device e project.output_size do YAML

4. Execute kou inspect-frame "<dispositivo>" --output-size <tamanho> --output json e use essa geometria antes de escrever CSS

5. Crie o arco narrativo e 2-3 opções de título/subtítulo por slide antes de tocar no layout. Escolha o mais forte primeiro. A qualidade do texto vem antes do CSS

6. Traduza a decisão de estilo em um briefing de campanha:

   • como o conjunto deve se sentir
   • quais motivos são permitidos
   • quais motivos são proibidos
   • quanta variação os primeiros 5 slides devem mostrar

7. Crie templates/ com templates HTML — mínimo de 3 layouts distintos, e os primeiros 3 slides não devem repetir o mesmo arquétipo de composição

8. Em cada template HTML, adicione data-kou-id e data-kou-role a estes elementos antes de escrever qualquer CSS:

   • Título principal: data-kou-id="headline" data-kou-role="headline"
   • Texto de apoio: data-kou-id="subtitle" data-kou-role="supporting"
   • Imagem do dispositivo primário: data-kou-id="device" data-kou-role="device"
   • Títulos/subs de recursos (slides de encerramento/recursos): data-kou-id="feature-N-title" data-kou-role="feature-title", data-kou-id="feature-N-sub" data-kou-role="feature-sub"

   Sem estes, o array elements do sidecar de layout ficará vazio e o QA pós-renderização será cego. Veja os exemplos de template em design-guide.md para padrões de anotação corretos.

9. Crie config.yaml com a configuração do koubou (leia yaml-reference.md para o formato)

10. Use CSS que se adapte à tela e ao comprimento do texto: use vw ou clamp() deliberadamente, prefira CSS Grid, sobreposição e camadas posicionadas absolutamente, e verifique a escala final do texto computado na tela real

11. Antes de escrever HTML: planeje zonas de texto/dispositivo para cada slide (qual área possui qual porcentagem da tela). Não comece o CSS até que as zonas estejam claras

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

13. Para cada captura HTML gerada, leia layout_path do resultado JSON e inspecione o sidecar antes de decidir que o layout é aceitável

14. QA pós-renderização (obrigatório — não pule):

    • Revise cada slide gerado visualmente
    • Abra cada *.layout.json sidecar referenciado por layout_path
    • Verifique a lista de rejeição em design-guide.md
    • Verifique se o conjunto renderizado ainda reflete o estilo do aplicativo que você descobriu, em vez de padrões genéricos da App Store
    • Use o layout JSON apenas para geometria objetiva: posições, espaço ocupado, proporções e sobreposições matemáticas
    • Se elements estiver vazio para um slide HTML que deveria ser medido, trate como anotação ausente ou quebrada e corrija o template
    • Verifique: sem ícones emoji, sem grades de cartões idênticas, sem dispositivos descentralizados, sem texto abaixo da escala mínima, sem corte não intencional do dispositivo (topo/notch do dispositivo deve estar visível em slides heróicos; o conteúdo da tela deve ser legível)
    • Aplique o teste de troca de logotipo: esses slides funcionariam para um concorrente?
    • Se algum slide falhar, corrija e regenere antes de mostrar ao usuário

15. Abra a pasta de saída: open <dir_de_saida>

16. Pergunte se o usuário quer ajustes — itere em slides específicos sem regenerar tudo

Regras de Iteração

• Quando o usuário pedir para alterar um slide específico, modifique apenas aquele template + entrada de configuração
• Quando o usuário pedir uma mudança de estilo global (cores, fontes, mood, densidade, ousadia), atualize todos os templates
• Reexecute kou generate config.yaml --output json após as alterações para que os novos valores de layout_path e sidecars permaneçam sincronizados
• Use kou live config.yaml se o usuário quiser pré-visualização em tempo real enquanto edita
• Se um slide parecer pequeno, primeiro aumente a escala ou mude o layout. Não esconda o problema com gradientes ou rótulos extras
• Se o texto forçar letras minúsculas, reescreva o texto ou escolha um layout mais adequado; nunca aceite um slide tímido porque "o texto teve que caber"
• Mantenha a variedade alta: o objetivo é consistência da campanha, não repetição de layout
• Não pare após a primeira renderização bem-sucedida se a saída ainda violar as regras de design ou a lista de verificação de rejeição
• Se o usuário pedir uma mudança de mood, reinterpretar todo o conjunto dentro dos limites de qualidade em vez de defender os padrões anteriores
• Se a captura e o layout JSON discordarem, confie na captura renderizada para o gosto e investigue a anotação ou o tempo de renderização em vez de forçar uma decisão de layout a partir de geometria desatualizada

Regras Rígidas

Restrições rígidas

• Nunca use emoji como ícones — use formas CSS (barras de destaque, pontos) ou apenas texto
• Nunca use frases de texto proibidas — "revolucionário", "perfeito", "desbloqueie", "mudança de jogo", etc.
• Aplique o teste de troca de logotipo — se o nome de um concorrente coubesse, o conjunto é muito genérico
• Cada template HTML deve ter anotações data-kou-id — no mínimo: headline, subtitle e device. Se elements no sidecar de layout estiver vazio após a geração, as anotações estão faltando — corrija o template antes que o QA passe. Não apresente slides não anotados ao usuário.

Escala

• Em iPhone retrato alto (iPhone6_9, iPhone6_7), títulos heróicos devem ser >=10vw, títulos laterais >=10vw, subtítulos >=4.5vw
• Use vw ou clamp() apenas se o tamanho calculado ainda ultrapassar o mínimo na tela alvo
• Em slides de contraste ou encerramento, o cluster de conteúdo deve ocupar 60%+ da altura da tela

Padrões fortes

• Não use a mesma composição de telefone centralizado e reto em slides consecutivos
• Não deixe grandes faixas vazias (>15% da altura da tela) entre o título e o dispositivo
• Evite combinar rotate() + translate() em dispositivos centralizados, a menos que o centro visual ainda pareça intencional após a renderização
• Não use uma simples coluna flexível centralizada quando o slide precisar de sobreposição, cortes nas bordas ou composição em camadas
• Planeje zonas de texto/dispositivo antes de escrever CSS (veja design-guide.md Planejamento de Zona Dispositivo-Texto)
• Se usar grades de cartões, escalone, enfatize ou simplifique-as, a menos que uma grade estrita sirva genuinamente ao conceito

Conteúdo

• Não adicione pequenos rótulos no topo, rótulos de categoria ou cabeçalhos de nome do aplicativo por padrão
• Não renderize o nome do aplicativo como texto decorativo pequeno, a menos que claramente legível

…

[truncado para tradução]