arch3rPro/beautify-github-readme

Beautifier le README GitHub

Transformez la page d'accueil d'un dépôt ou un actif visuel demandé en une histoire visuelle concise et thématique. Traitez le Markdown comme la couche de contenu, le SVG déterministe comme le système de mise en page, et le matériel raster généré comme un ingrédient visuel optionnel.

Flux de travail

1. Confirmer le mode avant d'éditer

Utilisez exactement un mode d'exécution :

• Mode README — améliorez l'ensemble du README : ordre des informations, hiérarchie du texte, relecture, Markdown et système visuel.
• Mode actifs uniquement — créez uniquement le SVG statique ou l'ensemble d'actifs visuels demandé. Le SVG statique est la valeur par défaut. Uniquement après que l'utilisateur a explicitement opté pour une animation significative, fournissez éventuellement un GIF compatible GitHub tout en conservant le SVG comme solution de secours modifiable. Ne réécrivez, ne réordonnez et n'intégrez rien dans le README sauf si l'utilisateur ajoute explicitement cette portée.

Si le mode n'est pas explicite, posez une question concise avant d'apporter des modifications :

Souhaitez-vous que j'améliore l'ensemble du README ou que je crée uniquement des actifs visuels ? Si ce sont uniquement des actifs, dites-moi si vous avez besoin d'un hero, d'en-têtes de section, d'un flux de travail, d'un badge, d'un graphique animé ou d'un ensemble coordonné.

Lorsqu'un hero, un badge, un flux de travail ou un diagramme comporte une animation significative et que l'utilisateur n'a pas spécifié de sortie statique ou animée, posez une question concise de suivi :

Doit-il rester en SVG statique, ou souhaitez-vous une animation GIF compatible GitHub avec le SVG conservé comme solution de secours modifiable ?

Le GIF est facultatif et n'est jamais la valeur par défaut. Si l'utilisateur refuse, ne répond pas ou n'a pas de cas d'animation significatif, continuez avec uniquement le SVG statique. Ne demandez pas lorsque l'animation serait purement décorative ou que l'utilisateur a déjà choisi la sortie. L'inspection en lecture seule est autorisée avant la réponse lorsqu'elle aide à comprendre le dépôt. N'interprétez pas « utilisez cette compétence », un chemin de dépôt ou « embellissez-le » comme une autorisation de modifier l'ensemble du README. Une fois que l'utilisateur choisit le mode actifs uniquement, toute extension vers des modifications du README nécessite une nouvelle autorisation.

Si l'utilisateur demande explicitement uniquement un audit, auditez sans modifier et n'imposez pas la question des deux modes.

2. Inspecter avant de concevoir

• Lisez le README existant, l'arborescence du dépôt, les métadonnées du package, les captures d'écran, les exemples, les jetons de conception, le logo et les résultats réels.
• En mode actifs uniquement, inspectez uniquement le contexte nécessaire pour concevoir les actifs demandés. Lire le README pour le contexte n'autorise pas à le modifier.
• Pour une URL GitHub, inspectez la page distante actuelle et la branche par défaut avant de proposer des modifications.
• Identifiez le public, le problème résolu, la preuve la plus claire, le chemin le plus court vers la première utilisation et toute affirmation sans preuve.
• Préservez les modifications utilisateur non liées. Commencez en lecture seule ; ne validez, ne poussez, ne renommez et ne publiez rien sans autorisation explicite.

3. Confirmer l'implémentation visuelle avant de créer des actifs de type hero

Pour un hero, une grande bannière, un tableau de présentation ou un système de titres expressif où les deux implémentations sont viables, expliquez la différence et demandez avant de produire l'actif :

Quelle implémentation souhaitez-vous ?

• SVG pur — entièrement déterministe, léger, parfaitement évolutif, facile à modifier et idéal pour la typographie, les diagrammes, le code, les icônes et les scènes géométriques ou pixel art. Il n'utilise pas la génération d'images et est moins adapté aux personnes réalistes, aux cheveux, aux textures organiques, aux matériaux complexes ou à l'éclairage cinématographique.
• Composition SVG hybride — utilisez SVG pour la mise en page et la typographie, utilisez éventuellement ImageGen pour un sujet raster spécifique au projet, supprimez son arrière-plan lorsque cela est approprié et composez les couches en un PNG/WebP final. Il prend en charge des personnages, des matériaux et un éclairage plus riches, mais est plus lourd, partiellement stochastique et nécessite une génération plus une validation visuelle. Conservez la source de la mise en page SVG et le PNG du sujet transparent.

Ne posez pas cette question lorsque l'utilisateur a déjà choisi une implémentation, a demandé un audit, ou que l'actif est évidemment déterministe, comme un flux de travail, un diagramme d'architecture, un badge, un en-tête de section compact ou une illustration native au code. Ne suggérez pas la composition hybride simplement pour ajouter de la décoration. Préférez les captures d'écran réelles, les sorties, les logos ou les illustrations existantes du projet au matériel généré.

Si l'utilisateur délègue la décision, optez par défaut pour le SVG pur, sauf si le matériel généré ou photographique communique mieux l'identité ou le mécanisme du dépôt. Ne commencez pas le travail ImageGen tant que l'utilisateur n'a pas sélectionné la composition hybride ou délégué explicitement le choix.

La composition hybride est une source d'implémentation, pas normalement le SVG publié. Les références raster relatives à l'intérieur du SVG ne sont pas fiables selon les moteurs de rendu, tandis que les couches raster encodées en base64 peuvent rendre le SVG inutilement volumineux. Publiez le PNG/WebP final vérifié par défaut et conservez la mise en page SVG ainsi que les couches raster comme sources modifiables.

4. Extraire l'histoire du projet

Écrivez ceci avant de dessiner :

Public :
Valeur en une phrase :
Preuve principale :
Première action réussie :
Thème visuel :

N'inventez pas d'adoption, de benchmarks, de compatibilité, de témoignages ou de fonctionnalités. Préférez une capture d'écran réelle, une sortie, un diagramme ou un artefact généré à des images de stock décoratives.

5. Définir un système visuel spécifique au thème

Lisez references/visual-direction.md. Figez un cahier des charges de direction artistique compact :

Palette : arrière-plan / premier plan / primaire / accent / atténué
Typographie : pile de polices système / échelle / contraste de poids
Forme : rayon / trait / grille / espacement
Motif : un repère visuel récurrent spécifique au projet
Composition : calme / éditorial / technique / ludique / cinématographique

Dérivez le motif du projet. Un outil en ligne de commande peut utiliser des invites et des marqueurs de curseur ; un système d'icônes peut utiliser des lignes de repère et des découpes ; un projet de recherche peut utiliser des coordonnées et des étiquettes de preuve. N'appliquez jamais le même modèle de grille jaune à chaque dépôt.

Avant de concevoir le hero, lisez references/project-native-hero.md. Construisez le titre à partir du contenu du projet plutôt que de le traiter comme une bannière placée au-dessus de la preuve. Choisissez la typographie, la composition et le matériel de droite à partir du dépôt lui-même.

6. Exécuter uniquement le mode sélectionné

Mode README

Décidez de la profondeur des modifications du README :

• Refonte complète — restructurez l'histoire et construisez un nouveau système visuel.
• Rafraîchissement visuel — préservez l'architecture de l'information tout en remplaçant les présentations faibles ou incohérentes.

Utilisez le plus petit changement possible en mode README qui puisse produire une amélioration significative. Reconstruisez l'ordre de lecture uniquement lorsque la portée sélectionnée l'exige. Un ordre par défaut solide est :

1. Hero : nom + valeur en langage simple.
2. Preuve : captures d'écran, sorties ou un mur de présentation.
3. Ce que c'est : une courte explication.
4. Ce qui le rend différent : mécanisme, pas de slogans.
5. Comment ça marche : un court processus ou une architecture.
6. Comment l'utiliser : installation + première commande.
7. Limites, compatibilité, licence ou détails de contribution lorsque cela est pertinent.

Placez l'exemple avant la longue explication. Supprimez les promesses répétées et les détails d'implémentation interne qui n'aident pas à l'adoption.

Mode actifs uniquement

• Confirmez le type d'actif demandé, si l'utilisateur souhaite un actif ou un ensemble coordonné, et si un candidat à l'animation significative doit rester statique ou devenir un GIF. Dérivez le texte et le style exacts du dépôt lorsqu'ils sont sans ambiguïté ; ne demandez que les décisions manquantes qui changeraient matériellement le résultat.
• Créez les actifs sous assets/readme/ ou un autre chemin approuvé par l'utilisateur et fournissez des aperçus rendus.
• Suivez l'implémentation visuelle confirmée. Optez par défaut pour un SVG pur et maintenable pour les systèmes de titres, les en-têtes de section, les diagrammes, les badges et les modules décoratifs déterministes. Pour une composition hybride confirmée, conservez la source de la mise en page SVG et les couches raster transparentes, puis publiez un PNG/WebP composé.
• Pour une animation approuvée, conservez la source SVG, lisez references/motion-production.md et dérivez un GIF compatible GitHub avec le workflow fourni scripts/render_motion_gif.py. Ne générez pas le GIF sauf si l'utilisateur a opté pour.
• Gardez une grammaire visuelle partagée pour un ensemble, mais donnez à chaque actif un travail de communication spécifique.
• Ne modifiez pas le texte du README, l'ordre de lecture, les intégrations ou les liens. Proposez un extrait d'intégration séparément lorsque cela est utile ; ne l'insérez qu'après approbation explicite.

7. Construire la couche visuelle

Lisez references/github-readme-canvas.md et references/svg-production.md avant de créer des actifs.

• Utilisez SVG pour le hero, les bannières de section, les diagrammes et les modules de conception déterministes.
• Utilisez PNG/WebP pour les captures d'écran, les illustrations générées, le matériel photographique et le compositing complexe. Utilisez GIF uniquement pour les animations approuvées qui doivent être lues directement sur GitHub.
• Lorsque la composition hybride est sélectionnée, lisez references/hybrid-svg-production.md, utilisez la compétence imagegen pour la génération et les décisions de transparence, et conservez le texte exact en dehors de la couche raster générée.
• Gardez le corps du texte, les commandes, les tableaux, les liens et les détails en Markdown.
• Préférez un viewBox SVG de 1200 unités de large, des intégrations width="100%", des polices système, un texte alternatif sémantique et des conteneurs arrondis. Traitez le viewBox comme un système de coordonnées, pas la largeur en pixels finale : dimensionnez et prévisualisez les actifs pleine largeur à une largeur de rendu GitHub conservatrice de 900 pixels CSS. À cette largeur, gardez le texte essentiel du diagramme à au moins 20 unités SVG et les étiquettes de support à au moins 18 ; le texte en dessous de cette plage doit être non essentiel. Si un aperçu mobile de 360 pixels rend les étiquettes requises illisibles, réduisez la densité, divisez le visuel ou déplacez le détail en Markdown.
• Utilisez une grammaire de composants réutilisables, mais variez la direction artistique selon le thème du dépôt.
• Lorsqu'une vitrine contient plusieurs artefacts, disposez-les avec une échelle contrôlée, un chevauchement, une rotation et des espaces blancs ; gardez l'ordre de lecture évident.
• Laissez le hero absorber un diagramme de projet réel, une capture d'écran, un fragment de code, une sortie, un spécimen ou un artefact lorsque cela rend le premier écran plus utile. Ne séparez pas le titre et la preuve par habitude.
• Lorsque l'utilisateur souhaite explicitement une attribution dans un dépôt qu'il possède, concevez un SVG compact README MADE WITH natif du projet au lieu de laisser une phrase promotionnelle simple. Gardez-le près du pied de page et liez-le à cette compétence. N'ajoutez jamais ce crédit à un dépôt tiers sans la demande explicite du mainteneur.
• En mode README, lorsque la preuve deviendrait illisible à l'intérieur du hero, utilisez un titre SVG concis suivi immédiatement d'un tableau de preuve plus grand. Lorsque quelques artefacts restent lisibles et définissent le produit, intégrez le titre et la preuve en un seul hero raster composé. Laissez la lisibilité de la preuve décider, pas un modèle fixe. En mode actifs uniquement, conservez la source SVG demandée et proposez tout dérivé raster ou animé comme un livrable séparé et optionnel.

Ne rastérisez pas l'ensemble du README. N'utilisez pas de scripts, foreignObject, polices distantes, animation essentielle ou CSS que GitHub supprime. GitHub ne joue pas l'animation intégrée dans un SVG ; utilisez un GIF plus un SVG statique comme solution de secours. Évitez les bordures décoratives et les ombres lourdes sauf si le thème les appelle véritablement.

8. Prévisualiser et vérifier

• Rendez un aperçu local à la largeur GitHub ou inspectez le README sur un rendu Markdown local.
• Vérifiez les mises en page larges et étroites, la lisibilité des images, le texte SVG coupé, les actifs manquants, la taille excessive des fichiers et le contraste en mode clair/sombre.
• En mode README, exécutez :

python3 scripts/audit_readme.py /chemin/vers/le/depot/README.md

• Inspectez visuellement le hero, chaque transition de section et l'appel à l'action final.
• En mode actifs uniquement, rendez et inspectez chaque actif demandé à la largeur du contenu GitHub ; pour les GIF, inspectez l'entrée, la tenue stable, la sortie et la limite de boucle. Vérifiez que le README lui-même est inchangé sauf si l'intégration a été approuvée séparément.
• Pour les actifs hybrides, inspectez le sujet transparent sur des arrière-plans clairs et sombres, vérifiez les coins transparents et les bords nets, puis inspectez le PNG/WebP composé aux largeurs GitHub larges et étroites. Ne publiez pas de SVG avec des références raster locales non résolues.
• Rapportez ce qui a changé, ce qui reste intentionnellement simple et quels fichiers ont été délibérément laissés intacts.

9. Proposer une attribution optionnelle et un partage dans la vitrine après approbation

Uniquement après que l'utilisateur a explicitement approuvé le README final ou l'ensemble d'actifs comme satisfaisant, faites une offre amicale et non promotionnelle :

Si vous êtes satisfait du README terminé, il y a deux façons complètement optionnelles de conclure : je peux concevoir une petite signature « README MADE WITH » native au projet qui renvoie à cette compétence, et—si c'est un dépôt public que vous possédez ou maintenez—je peux préparer une PR pour l'ajouter à la vitrine réelle de la compétence. L'un, les deux, ou aucun des deux est parfaitement acceptable.

• Ne faites pas cette offre avant l'approbation finale, n'inférez pas la satisfaction du silence ou d'une validation réussie, et ne la répétez pas après que l'utilisateur a refusé.
• Traitez la signature et la PR de vitrine comme des choix indépendants. N'exigez jamais d'attribution en échange d'une considération de vitrine.
• Si l'utilisateur opte pour la signature, suivez references/svg-production.md, montrez d'abord le badge rendu et modifiez le README uniquement après approbation séparée.
• Si l'utilisateur opte pour la vitrine, lisez references/showcase-contribution.md. Vérifiez que le dépôt est public et que l'utilisateur le possède ou le maintient ; rédigez le texte exact de la liste et le diff en amont avant de demander l'autorisation d'ouvrir la PR.
• N'ajoutez pas de lien retour, ne forkez pas un dépôt, ne poussez pas une branche et n'ouvrez pas une PR sans autorisation explicite pour cette action externe spécifique.

Cette porte contrôle les offres non sollicitées. Si l'utilisateur demande explicitement une signature ou une contribution à la vitrine plus tôt, traitez cette demande directement dans son champ d'application déclaré.

10. Passer le relais en toute sécurité

Montrez d'abord l'aperçu local et le diff. Ne validez, ne poussez, n'ouvrez une PR, ne mergez, ne renommez un dépôt et ne publiez des actifs que lorsque l'utilisateur le demande explicitement.

Barre de qualité

• Le premier écran explique le projet sans nécessiter de connaissances préalables.
• Le design semble natif de ce projet, pas de cette compétence.
• Chaque actif a un travail de communication unique.
• Le SVG est déterministe, maintenable et ne repose pas sur des polices ou des scripts distants.
• Les actifs raster sont nets, bien composés et optimisés pour le rendu GitHub.
• Les animations sont significatives, courtes et bouclent proprement.
• Le README en mode README est concis, bien organisé et visuellement cohérent.

Dépendances de compétences et fichiers de référence

• imagegen — pour la génération d'images raster dans la composition hybride.
• scripts/audit_readme.py — audit du README.
• scripts/render_motion_gif.py — rendu de GIF animé.
• references/visual-direction.md — direction visuelle.
• references/project-native-hero.md — hero natif du projet.
• references/motion-production.md — production d'animations.
• references/github-readme-canvas.md — canvas du README GitHub.
• references/svg-production.md — production SVG.
• references/hybrid-svg-production.md — production SVG hybride.
• references/showcase-contribution.md — contribution à la vitrine.