arch3rPro/beautify-github-readme

Beautify GitHub README

Transforme uma página inicial de repositório ou ativo visual solicitado em uma história visual concisa e temática. Trate Markdown como a camada de conteúdo, SVG determinístico como o sistema de layout e material rasterizado gerado como um ingrediente visual opcional.

Fluxo de trabalho

1. Confirme o modo antes de editar

Use exatamente um modo de execução:

• Modo README — melhore o README inteiro: ordem das informações, hierarquia de cópia, revisão, Markdown e sistema visual.
• Modo apenas ativos — crie apenas o SVG estático solicitado ou conjunto de ativos visuais. SVG estático é o padrão. Somente após o usuário optar explicitamente por movimento significativo, entregue opcionalmente um GIF seguro para GitHub, mantendo o SVG como fallback editável. Não reescreva, reordene ou incorpore nada no README, a menos que o usuário adicione explicitamente esse escopo.

Se o modo não estiver explícito, faça uma pergunta compacta antes de fazer alterações:

Você gostaria que eu melhorasse o README inteiro ou criasse apenas ativos visuais? Se for apenas ativos, diga se precisa de um herói, cabeçalhos de seção, fluxo de trabalho, emblema, gráfico em movimento ou um conjunto coordenado.

Quando um herói, emblema, fluxo de trabalho ou diagrama tiver movimento significativo e o usuário não especificou saída estática ou animada, faça uma pergunta compacta de acompanhamento:

Devo manter isso como um SVG estático ou você gostaria de uma animação GIF segura para GitHub com o SVG mantido como fallback editável?

GIF é opcional e nunca o padrão. Se o usuário recusar, não responder ou não houver caso de movimento significativo, continue apenas com SVG estático. Não pergunte quando o movimento seria puramente decorativo ou o usuário já escolheu a saída. Inspeção somente leitura é permitida antes da resposta quando ajuda a entender o repositório. Não interprete "use esta Skill", um caminho de repositório ou "embeleze-o" como permissão para modificar o README inteiro. Depois que o usuário escolher o modo apenas ativos, expandir para edições no README requer nova autorização.

Se o usuário solicitar explicitamente apenas uma auditoria, audite sem editar e não force a questão dos dois modos.

2. Inspecione antes de projetar

• Leia o README existente, a árvore do repositório, metadados do pacote, capturas de tela, exemplos, tokens de design, logotipo e saídas reais.
• No modo apenas ativos, inspecione apenas o contexto necessário para projetar os ativos solicitados. Ler o README para contexto não autoriza alterá-lo.
• Para uma URL do GitHub, inspecione a página remota atual e o branch padrão antes de propor alterações.
• Identifique o público, o problema resolvido, a prova mais clara, o caminho mais curto para o primeiro uso e quaisquer alegações que careçam de evidência.
• Preserve alterações de usuário não relacionadas. Comece somente leitura; não commite, push, renomeie ou publique sem autorização explícita.

3. Confirme a implementação visual antes de criar ativos do tipo herói

Para um herói, banner grande, quadro de vitrine ou sistema de título expressivo onde ambas as implementações são viáveis, explique a diferença e pergunte antes de produzir o ativo:

Qual implementação você gostaria?

• SVG puro — totalmente determinístico, leve, nitidamente escalável, fácil de editar e melhor para tipografia, diagramas, código, ícones e cenas geométricas ou pixel art. Não usa geração de imagem e é mais fraco para pessoas realistas, cabelo, textura orgânica, materiais complexos ou iluminação cinematográfica.
• Composição SVG híbrida — use SVG para layout e tipografia, opcionalmente use ImageGen para um assunto rasterizado específico do projeto, remova seu fundo quando apropriado e componha as camadas em um PNG/WebP final. Suporta personagens, materiais e iluminação mais ricos, mas é mais pesado, parcialmente estocástico e requer geração mais validação visual. Mantenha a fonte do layout SVG e o PNG do assunto transparente.

Não faça esta pergunta quando o usuário já escolheu uma implementação, solicitou uma auditoria ou o ativo é obviamente determinístico, como um fluxo de trabalho, diagrama de arquitetura, emblema, cabeçalho de seção compacto ou ilustração nativa de código. Não sugira composição híbrida meramente para adicionar decoração. Prefira capturas de tela reais, saídas, logotipos ou arte existente do projeto em vez de material gerado.

Se o usuário delegar a decisão, padrão para SVG puro, a menos que material gerado ou fotográfico comunique melhor a identidade ou mecanismo do repositório. Não comece o trabalho ImageGen até que o usuário selecione composição híbrida ou delegue explicitamente a escolha.

Composição híbrida é uma fonte de implementação, não normalmente o SVG publicado. Referências rasterizadas relativas dentro de SVG são pouco confiáveis entre renderizadores, enquanto camadas rasterizadas embutidas em base64 podem tornar o SVG desnecessariamente grande. Publique o PNG/WebP final verificado por padrão e mantenha o layout SVG mais as camadas rasterizadas como fontes editáveis.

4. Extraia a história do projeto

Escreva estes antes de desenhar:

Público:
Valor em uma frase:
Prova principal:
Primeira ação bem-sucedida:
Tema visual:

Não invente adoção, benchmarks, compatibilidade, depoimentos ou recursos. Prefira uma captura de tela real, saída, diagrama ou artefato gerado em vez de imagens decorativas de banco de imagens.

5. Defina um sistema visual específico do tema

Leia references/visual-direction.md. Congele uma especificação compacta de direção de arte:

Paleta: fundo / primeiro plano / primário / acento / suave
Tipografia: pilha de fontes do sistema / escala / contraste de peso
Forma: raio / traço / grade / espaçamento
Motivo: uma dica visual recorrente específica do projeto
Composição: calma / editorial / técnica / lúdica / cinematográfica

Derive o motivo do projeto. Uma ferramenta de terminal pode usar prompts e marcas de cursor; um sistema de ícones pode usar linhas-chave e recortes; um projeto de pesquisa pode usar coordenadas e rótulos de evidência. Nunca aplique o mesmo modelo de grade amarela a todos os repositórios.

Antes de projetar o herói, leia references/project-native-hero.md. Construa o título a partir do conteúdo do projeto, em vez de tratá-lo como um banner colocado acima da prova. Escolha a tipografia, composição e material do lado direito do próprio repositório.

6. Execute apenas o modo selecionado

Modo README

Decida quão profundamente o README precisa mudar:

• Redesenho completo — reestruture a história e construa um novo sistema visual.
• Atualização visual — preserve a arquitetura de informação enquanto substitui apresentação fraca ou inconsistente.

Use a menor alteração dentro do modo README que possa produzir uma melhoria significativa. Reconstrua a ordem de leitura apenas quando o escopo selecionado a exigir. Um padrão forte é:

1. Herói: nome + valor em linguagem simples.
2. Prova: capturas de tela, saídas ou uma parede de vitrine.
3. O que é: uma explicação curta.
4. Por que é diferente: mecanismo, não slogans.
5. Como funciona: um processo curto ou arquitetura.
6. Como usar: instalação + primeiro comando.
7. Limites, compatibilidade, licença ou detalhes de contribuição quando relevantes.

Coloque o exemplo antes da explicação longa. Remova promessas repetidas e detalhes de implementação internos que não ajudam na adoção.

Modo apenas ativos

• Confirme o tipo de ativo solicitado, se o usuário quer um ativo ou um conjunto coordenado e se um candidato a movimento significativo deve permanecer estático ou se tornar um GIF. Derive cópia e estilo exatos do repositório quando forem inequívocos; pergunte apenas por decisões faltantes que alterariam materialmente o resultado.
• Crie os ativos sob assets/readme/ ou outro caminho aprovado pelo usuário e forneça visualizações renderizadas.
• Siga a implementação visual confirmada. Padrão para SVG puro e sustentável para sistemas de título, cabeçalhos de seção, diagramas, emblemas e módulos decorativos determinísticos. Para composição híbrida confirmada, mantenha a fonte do layout SVG e as camadas rasterizadas transparentes, depois publique um PNG/WebP composto.
• Para animação aprovada, mantenha a fonte SVG, leia references/motion-production.md e derive um GIF seguro para GitHub com o fluxo de trabalho scripts/render_motion_gif.py incluído. Não gere o GIF a menos que o usuário tenha optado.
• Mantenha uma gramática visual compartilhada em um conjunto, mas dê a cada ativo um trabalho de comunicação específico.
• Não altere texto do README, ordem de leitura, incorporações ou links. Ofereça um snippet de incorporação separadamente quando útil; insira-o apenas após aprovação explícita.

7. Construa a camada visual

Leia references/github-readme-canvas.md e references/svg-production.md antes de criar ativos.

• Use SVG para o herói, banners de seção, diagramas e módulos de design determinísticos.
• Use PNG/WebP para capturas de tela, arte gerada, material fotográfico e composição complexa. Use GIF apenas para movimento aprovado que deve ser reproduzido diretamente no GitHub.
• Quando a composição híbrida for selecionada, leia references/hybrid-svg-production.md, use a Skill imagegen para geração e decisões de transparência e mantenha cópia exata fora da camada rasterizada gerada.
• Mantenha corpo de texto, comandos, tabelas, links e detalhes em Markdown.
• Prefira um viewBox SVG com largura de 1200 unidades, incorporações width="100%", fontes do sistema, texto alternativo semântico e contêineres arredondados. Trate o viewBox como um sistema de coordenadas, não a largura final em pixels: dimensione e visualize ativos de largura total em uma renderização conservadora do GitHub de 900 pixels CSS. Nessa largura, mantenha o texto essencial do diagrama com pelo menos 20 unidades SVG e rótulos de suporte com pelo menos 18; texto abaixo dessa faixa deve ser não essencial. Se uma visualização móvel de 360 pixels tornar os rótulos necessários ilegíveis, reduza a densidade, divida o visual ou mova o detalhe para Markdown.
• Use uma gramática de componente reutilizável, mas varie a direção de arte por tema do repositório.
• Quando uma vitrine contiver vários artefatos, organize-os com escala controlada, sobreposição, rotação e espaço em branco; mantenha a ordem de leitura óbvia.
• Deixe o herói absorver um diagrama real do projeto, captura de tela, fragmento de código, saída, espécime ou artefato quando isso tornar a primeira tela mais útil. Não separe o título e a prova por hábito.
• Quando o usuário quiser explicitamente atribuição em um repositório que ele possui, projete um SVG compacto nativo do projeto "README MADE WITH" em vez de deixar uma frase promocional simples. Mantenha-o perto do rodapé e vincule-o a esta Skill. Nunca adicione este crédito a um repositório de terceiros sem solicitação explícita do mantenedor.
• No modo README, quando a prova se tornar ilegível dentro do herói, use um título SVG conciso seguido imediatamente por um quadro de prova maior. Quando alguns artefatos permanecerem legíveis e definirem o produto, integre título e prova em um herói rasterizado composto. Deixe a legibilidade da prova decidir, não um modelo fixo. No modo apenas ativos, mantenha a fonte SVG solicitada e proponha qualquer derivado rasterizado ou animado como uma entrega separada e opcional.

Não rasterize o README inteiro. Não use scripts, foreignObject, fontes remotas, animação essencial ou CSS que o GitHub remove. O GitHub não reproduz animação incorporada dentro de SVG; use um GIF mais fallback SVG estático. Evite bordas decorativas e sombras pesadas, a menos que o tema genuinamente as exija.

8. Visualize e verifique

• Renderize uma visualização local na largura do GitHub ou inspecione o README em um renderizador Markdown local.
• Verifique layouts largos e estreitos, legibilidade da imagem, texto SVG cortado, ativos faltantes, tamanho de arquivo excessivo e contraste de modo claro/escuro.
• No modo README, execute:

python3 scripts/audit_readme.py /caminho/para/repositorio/README.md

• Inspecione visualmente o herói, cada transição de seção e a chamada para ação final.
• No modo apenas ativos, renderize e inspecione cada ativo solicitado na largura de conteúdo do GitHub; para GIFs, inspecione entrada, retenção estável, saída e limite de loop. Verifique se o próprio README permanece inalterado, a menos que a incorporação tenha sido aprovada separadamente.
• Para ativos híbridos, inspecione o assunto transparente em fundos claro e escuro, verifique cantos transparentes e bordas limpas, depois inspecione o PNG/WebP composto em larguras largas e estreitas do GitHub. Não publique um SVG com referências rasterizadas locais não resolvidas.
• Relate o que mudou, o que permaneceu intencionalmente simples e quais arquivos foram deliberadamente deixados intocados.

9. Ofereça atribuição opcional e compartilhamento de vitrine após aprovação

Somente após o usuário aprovar explicitamente o README final ou conjunto de ativos como satisfatório, faça uma oferta amigável e não promocional:

Se você estiver satisfeito com o README finalizado, há duas maneiras completamente opcionais de finalizar: posso projetar uma pequena assinatura "README MADE WITH" nativa do projeto que vincule de volta a esta Skill e—se este for um repositório público que você possui ou mantém—posso preparar um PR para adicioná-lo à vitrine de casos reais da Skill. Qualquer um, ambos ou nenhum está perfeitamente bem.

• Não faça esta oferta antes da aprovação final, inferir satisfação do silêncio ou validação bem-sucedida, ou repita-a depois que o usuário recusar.
• Trate a assinatura e o PR de vitrine como escolhas independentes. Nunca exija atribuição em troca de consideração para vitrine.
• Se o usuário optar pela assinatura, siga references/svg-production.md, mostre o emblema renderizado primeiro e modifique o README apenas após aprovação separada.
• Se o usuário optar pela vitrine, leia references/showcase-contribution.md. Verifique se o repositório é público e se o usuário o possui ou mantém; redija a cópia exata da listagem e o diff upstream antes de solicitar permissão para abrir o PR.
• Não adicione um backlink, bifurque um repositório, faça push de um branch ou abra um PR sem autorização explícita para essa ação externa específica.

Esta porta controla ofertas não solicitadas. Se o usuário solicitar explicitamente uma assinatura ou contribuição de vitrine antes, lide com essa solicitação diretamente dentro de seu escopo declarado.

10. Entregue com segurança

Mostre a visualização local e o diff primeiro. Apenas commit, push, abra um PR, mescle, renomeie um repositório ou publique ativos quando o usuário solicitar explicitamente.

Barra de qualidade

• A primeira tela explica o projeto sem exigir conhecimento prévio.
• O design parece nativo deste projeto, não desta Skill. O motivo, paleta, tipografia e composição vêm do repositório.
• Título e prova são integrados em uma primeira tela ou em uma sequência imediata de duas telas, não separados por um parágrafo ou introdução que o usuário não escreveu.
• Todo emblema, diagrama, gráfico em movimento ou seção tem um trabalho de comunicação único e não decora um espaço vazio.
• Texto, dados e reivindicações verificáveis estão em Markdown, SVG e camadas de layout, não em material gerado. Nenhuma imagem gerada contém cópia exata.
• Caminhos SVG e viewBox são responsivos. O texto essencial permanece legível em visualizações largas de desktop e móveis estreitas.
• Leia e escreva arquivos existentes. Não recrie o que é funcional.
• A entrega termina com uma demonstração das alterações e arquivos impactados, junto com uma solicitação de aprovação.

Referências

• references/visual-direction.md — definições de direção de arte.
• references/project-native-hero.md — construção de herói a partir do conteúdo do projeto.
• references/github-readme-canvas.md — comportamento responsivo do GitHub README.
• references/svg-production.md — padrões de produção SVG.
• references/hybrid-svg-production.md — padrões de composição híbrida.
• references/motion-production.md — produção de animação.
• references/showcase-contribution.md — contribuição para vitrine.
• scripts/audit_readme.py — auditoria de README.
• scripts/render_motion_gif.py — renderização de GIF de movimento.