README Screenshots
Transformez un projet fonctionnel en un projet documenté et visuel : exécutez l'application, capturez de vraies captures d'écran de ses surfaces, et composez un README.md dynamique et propre autour d'elles. Le résultat doit ressembler à la page d'accueil d'un projet open-source apprécié.
Non-négociables, quelle que soit la plateforme :
- Les captures d'écran sont de VRAIES captures de l'application en cours d'exécution. Ne jamais dessiner, simuler ou falsifier une image.
- Elles se trouvent dans le dépôt (
docs/screenshots/) et le README les référence avec des chemins relatifs pour qu'elles s'affichent sur GitHub. - Rien de destructif : ne jamais modifier le code source du projet pour réaliser une capture — injecter l'état de démonstration au moment de l'exécution si nécessaire, puis le mentionner.
Workflow
Phase 1 — Détection de la plateforme
Recherchez ces signaux à la racine du projet, puis chargez UN guide depuis references/ :
| Signaux | → Guide |
|---|---|
package.json avec un script dev/start, ou index.html, ou un frontend web pur dans un dossier src/public | references/web.md |
manifest.json (WebExtension/MV3/V2) | references/web.md (section extension) |
Android : build.gradle(.kts), AndroidManifest.xml, settings.gradle, sources d'app Kotlin/Java | references/android.md |
iOS : *.xcodeproj, *.xcworkspace, Info.plist, code d'application en Swift | references/ios.md |
Flutter : pubspec.yaml avec flutter: et lib/main.dart | references/flutter.md |
| Plusieurs plates-formes (ex : Flutter + natif, ou un monorepo) | documenter d'abord la plateforme de l'interface phare ; mentionner les autres dans le README |
Si la plateforme est véritablement ambiguë, demandez à l'utilisateur une seule fois avec votre meilleure analyse du dépôt. Si le projet n'a AUCUNE interface visible par l'utilisateur (bibliothèque/CLI pure), ne simulez pas de captures d'interface — optez pour une démonstration en terminal, un diagramme soigné, ou une bannière générée, et produisez toujours un excellent README.
Phase 2 — Exécution de l'application selon le guide
Chaque guide indique :
- Ce qui doit déjà exister sur cette machine (vérification de la chaîne d'outils, commande reproductible en une ligne).
- Comment démarrer l'application pour que son interface s'affiche.
- Comment capturer les pixels (script intégré dans
scripts/ou commande de capture native). - Comment réagir quand quelque chose est vide (« attendre le rendu » vaut mieux que « réessayer à l'aveugle »).
Phase 3 — Capture
Conventions applicables sur chaque plateforme :
- Enregistrer dans
<repo>/docs/screenshots/, noms en kebab-case qui décrivent le moment (hero-dashboard.png,settings-screen.png), jamais l'outil (screenshot-2026-01-04-14-22.png). - Capturer chaque surface dans sa forme naturelle : boîtes de dialogue/popups à leur taille native, pages à 1280×800 ou en page entière. Sur les téléphones, capturer l'écran de l'appareil tel quel (sa propre résolution fait partie de l'histoire).
- Privilégier le mode sombre pour la capture principale si l'application en propose un — les interfaces sombres ressortent dans les README — mais seulement si elle a un véritable thème sombre ; ne pas en forcer un.
- L'état de démonstration scénarisé est autorisé (compteurs vides, placeholders « Chargement… » paraissent cassés dans les captures promotionnelles), mais il doit être injecté au moment de l'exécution, pas écrit dans le code du projet, et vous devez le divulguer à l'utilisateur dans votre résumé.
- Un écran vide ou qui clignote est un bug de temporisation, pas un défaut de l'application : attendre le chargement + un temps pour les polices/icônes/transitions, réessayer une fois avec un temps d'attente plus long.
Phase 4 — Composition du README
Écrire (ou réécrire) README.md à la racine du dépôt. Si un contenu README riche existe déjà (git-readme.md, un fichier en prose, docs), exploitez TOUS ses faits — vous améliorez la présentation, vous ne supprimez jamais d'informations.
Structure cible (adaptez librement, gardez-la lisible) :
# <Nom du projet>
<p align="center"><img src="docs/screenshots/hero.png" width="…"></p>
> Phrase d'accroche d'une ligne avec de la personnalité.
badges : licence, langage, lien d'installation
## Pourquoi il existe ← le problème, 2–4 lignes, chiffres en gras si réels
## Ce qu'il fait ← ✨ liste de fonctionnalités serrée (+ captures à côté de leurs fonctionnalités)
## Visite guidée des captures d'écran ← galerie avec légendes d'une ligne
## Comment ça marche ← architecture en termes simples ; tableaux plutôt que prose
## Installation ← numérotée, copiable
## Configuration ← tableau de paramètres si l'application a des réglages
## Confidentialité / Sécurité ← seulement quand c'est pertinent
## Licence
Règles de style :
- Image principale au-dessus de la ligne de flottaison, largeur explicite (
width="400"pour les captures de téléphone, sous ~728px pour le bureau) pour un bon rendu sur GitHub. - Une idée par section ; paragraphes courts ; gras uniquement pour faciliter le balayage.
- Tableaux pour les matrices de compatibilité et les réglages — ils sont plus efficaces que la prose.
- Emoji minimaliste et de bon goût dans les en-têtes (⏱ 🎨 🚀) est acceptable ; ne pas en mettre à chaque ligne.
- Chemins d'images relatifs avec texte alternatif, toujours.
- Ne jamais décrire le processus de capture d'écran dans le README ; cela donne l'impression que le projet lui-même l'a écrit.
Phase 5 — Vérification
- Chaque chemin d'image dans le README pointe vers un fichier existant.
- Aucune capture d'écran ne dépasse ~1,5 Mo ; compresser (PNG → WebP ou réduire la résolution) si plus grosse.
- Informer l'utilisateur : où se trouve le README, quelles captures existent, lesquelles contiennent des valeurs injectées par la démonstration, et proposer de changer le choix de l'image principale, le thème ou l'ordre.
Politique de chaîne d'outils (gestion des dépendances manquantes)
La compétence utilise la chaîne d'outils déjà présente sur la machine et n'installe JAMAIS silencieusement des SDK de plateforme (Android SDK, Xcode, émulateurs Android — téléchargements de plusieurs Go auxquels l'utilisateur doit consentir). Si la vérification de la chaîne d'outils d'un guide échoue, arrêtez-vous proprement avec exactement cette forme :
Les captures d'écran [Plateforme] nécessitent [outil], qui n'est pas installé. Pour l'activer :
<commande ou étape d'installation exacte>. Installez-le, puis dites « réessayer » et je continuerai — le travail déjà effectué (détection, squelette du README) est sauvegardé.
iOS est un cas particulier : si l'hôte n'est pas macOS, dites-le en une phrase et passez — aucun réessai ne peut l'activer sous Windows/Linux. Proposez à l'utilisateur l'option de fournir des captures d'écran qu'il a prises lui-même.