Ryuki0x1/capturas-para-readme

Capturas de Tela para README

Transforme um projeto funcional em um projeto documentado e visual: execute o aplicativo, capture capturas de tela reais de suas superfícies e componha um README.md vibrante e limpo ao redor delas. O resultado deve parecer a página inicial de um projeto open source bem amado.

Itens inegociáveis, independentemente da plataforma:

• As capturas de tela são CAPTURAS REAIS do aplicativo em execução. Nunca desenhe, faça mockup ou falsifique uma imagem.
• Elas residem no repositório (docs/screenshots/) e o README as referencia com caminhos relativos para que sejam renderizadas no GitHub.
• Nada destrutivo: nunca modifique o código fonte do projeto para fazer uma captura de tela acontecer — injete o estado de demonstração em tempo de execução, se necessário, e então informe.

Fluxo de Trabalho

Fase 1 — Detectar a plataforma

Procure por estes sinais na raiz do projeto e então carregue UM guia de execução de references/:

Sinais	→ Guia de Execução
package.json com um script dev/start, ou index.html, ou um frontend web puro em uma pasta src/public	references/web.md
manifest.json (WebExtension/MV3/V2)	references/web.md (seção de extensão)
Android: build.gradle(.kts), AndroidManifest.xml, settings.gradle, fontes de aplicativos Kotlin/Java	references/android.md
iOS: *.xcodeproj, *.xcworkspace, Info.plist, código do aplicativo em Swift	references/ios.md
Flutter: pubspec.yaml com flutter: e lib/main.dart	references/flutter.md
Múltiplas plataformas (ex.: Flutter + nativo, ou um monorepo)	documente a plataforma da interface principal primeiro; anote as outras no README

Se a plataforma for genuinamente ambígua, pergunte ao usuário uma vez com sua melhor interpretação do repositório apresentada. Se o projeto NÃO tiver interface visível para o usuário (biblioteca pura/CLI), não invente capturas de interface — recorra a uma demonstração de terminal, um diagrama refinado ou um banner gerado, e ainda assim produza um ótimo README.

Fase 2 — Executar o aplicativo conforme o guia de execução

Cada guia de execução informa:

1. O que já deve existir nesta máquina (verificação da cadeia de ferramentas, comando repetível de uma linha).
2. Como iniciar o aplicativo para que sua interface seja renderizada.
3. Como realmente capturar pixels (script incluído em scripts/ ou um comando de captura nativo).
4. Como se recuperar quando algo estiver em branco ("aguardar a renderização" é melhor do que "tentar novamente às cegas").

Fase 3 — Capturar

Convenções que se aplicam em todas as plataformas:

• Salve em <repo>/docs/screenshots/, nomes em kebab-case que descrevam o momento (hero-dashboard.png, settings-screen.png), nunca a ferramenta (screenshot-2026-01-04-14-22.png).
• Capture cada superfície em seu formato natural: diálogos/popups em seu tamanho nativo, páginas em 1280×800 ou página inteira. Em telefones, capture a tela do dispositivo como está (sua própria resolução faz parte da história).
• Prefira o modo escuro para a captura principal quando o aplicativo tiver um — interfaces escuras se destacam em READMEs — mas apenas se ele tiver um tema escuro real; não force um.
• O estado de demonstração encenado é permitido (contadores vazios, placeholders "Carregando…" parecem quebrados em imagens de marketing), mas deve ser injetado em tempo de execução, não escrito no código do projeto, e você deve informar o usuário em seu resumo.
• Um quadro em branco ou piscando é um bug de temporização, não culpa do aplicativo: aguarde o carregamento + uma pausa para fontes/ícones/transições, tente novamente uma vez com uma espera mais longa.

Fase 4 — Compor o README

Escreva (ou reescreva) README.md na raiz do repositório. Se um conteúdo rico de README já existir (git-readme.md, um arquivo de texto, docs), extraia TODOS os seus fatos — você está melhorando a apresentação, nunca deletando informações.

Estrutura alvo (adapte livremente, mantenha escaneável):

# <Nome do Projeto>
<p align="center"><img src="docs/screenshots/hero.png" width="…"></p>
> Descrição de uma frase com personalidade.
badges: licença, linguagem, link de instalação
## Por que existe         ← a dor, 2–4 linhas, números em negrito se reais
## O que faz              ← ✨ lista de recursos concisa (+ capturas ao lado de seus recursos)
## Tour de capturas       ← galeria com legendas de uma linha
## Como funciona          ← arquitetura em palavras simples; tabelas em vez de prosa
## Instalação             ← numerada, copiável
## Configuração           ← tabela de parâmetros se o aplicativo tiver configurações
## Privacidade / Segurança ← apenas quando significativo
## Licença

Regras de estilo:

• Captura principal acima da dobra, largura explícita (width="400" para capturas de telefone, abaixo de ~728px para desktop) para que seja bem distribuída no GitHub.
• Uma ideia por seção; parágrafos curtos; negrito apenas para auxiliar a varredura.
• Tabelas para matrizes de compatibilidade e configurações — elas são melhores que prosa.
• Emojis mínimos e de bom gosto nos cabeçalhos (⏱ 🎨 🚀) são aceitáveis; não coloque sal em cada linha.
• Caminhos de imagem relativos com texto alternativo, sempre.
• Nunca narre o processo de captura de tela no README; ele deve soar como se o próprio projeto o tivesse escrito.

Fase 5 — Verificar

• Cada caminho de imagem no README resolve para um arquivo existente.
• Nenhuma captura de tela com mais de ~1.5 MB; comprima (PNG → WebP ou reduza a escala) se for maior.
• Informe ao usuário: onde está o README, quais capturas existem, quais carregam valores injetados de demonstração e ofereça para trocar a escolha da captura principal, tema ou ordem.

Política de cadeia de ferramentas (manipulação de dependências ausentes)

A skill usa qualquer cadeia de ferramentas que já exista na máquina e NUNCA instala silenciosamente SDKs de plataforma (Android SDK, Xcode, emuladores Android — downloads multigigabytes aos quais o usuário deve consentir). Se a verificação da cadeia de ferramentas de um guia de execução falhar, pare de forma limpa exatamente com este formato:

As capturas de tela de [Plataforma] precisam de [ferramenta], que não está instalada. Para habilitá-la: <comando ou etapa de instalação exata>. Instale-a, então diga "tentar novamente" e continuarei — o trabalho feito até agora (detecção, esqueleto do README) está salvo.

iOS é um caso especial: se o host não for macOS, informe em uma frase e pule — nenhuma tentativa pode habilitá-lo no Windows/Linux. Ofereça ao usuário a opção de fornecer capturas de tela que ele mesmo capturou.