Confier l'annotation de mes captures d'écran pour la doc à un agent
- La question
- Puis-je donner à un agent un dossier de captures d'écran sans nom, lui demander d'identifier leur contenu et obtenir en retour les figures annotées nécessaires pour une page de documentation ?
- Le résultat
- Oui pour la lecture et le dessin. Le placement de la légende reste une question de jugement, et cela dépend de l'espace blanc disponible dans l'interface.
Ce que je voulais découvrir
Quand je rédige de la documentation, je prends des captures d’écran au fur et à mesure, et elles atterrissent sur mon bureau avec des noms comme Screenshot 2026-09-14 at 18.03.12.png. Vient ensuite la partie fastidieuse : ouvrir chaque fichier, déterminer à quelle étape il correspond, le recadrer, tracer un cadre autour du bouton, et écrire la légende là où elle ne cache pas l’élément désigné.
La question était de savoir si je pouvais sauter toutes ces étapes. Donner le dossier à l’agent, le laisser analyser les images pour comprendre le sujet, l’aider pour le texte, puis lui faire produire les figures annotées. Pas de Figma, pas d’allers-retours pour savoir où placer un cadre.
Je pensais que le dessin serait la partie difficile. Ce ne fut pas le cas.
Comment cela a été testé
Une annotation est un module JavaScript, pas un dessin. Elle définit une image source et une liste de formes exprimées en pourcentages du cadre, puis un moteur de rendu les superpose à la capture d’écran dans Chrome et re-photographie la page avec Playwright.
Tout le secret réside dans Chrome. Les coins arrondis, les ombres, le rendu du texte et le flou sont gérés par le navigateur : rien n’a besoin d’être réimplémenté, et le résultat est un PNG aux dimensions exactes de la source.
- 1Import de la captureQuel que soit le nom donné par l’outil de capture
- 2Rendu de la grilleUne superposition de pourcentages sur l’image
- 3Lecture des coordonnéesRegarder une fois, noter les valeurs
- 4Écriture de la specUn fichier JS : cadres, flèches, notes, recadrages
- 5RenduChrome compose, Playwright capture
L’étape trois est celle où l’expérience a failli échouer. À qui on demande de placer un cadre autour d’un bouton à l’œil, l’agent se trompe d’environ 2 %, ce qui est négligeable sur le papier mais flagrant sur l’image. La solution a été d’arrêter de lui demander d’estimer : une grille de pourcentages est d’abord rendue sur la capture, il lit les chiffres sur cette grille une seule fois, et chaque cadre suivant tombe pile sur le pixel.
Six primitives couvrent les besoins d’une figure de documentation.
| Primitive | Fonction |
|---|---|
box | Le cadre arrondi et son halo, avec un numéro et une légende optionnels |
arrow | Une flèche courbe, orientée vers la pointe, pour un seul “cliquez ici” |
note | Une carte de texte : un titre et une ligne de corps de texte |
spotlight | Assombrit tout sauf les zones découpées |
zoom | Une loupe : un recadrage, agrandi, placé dans un espace vide |
redact | Floute une région |
Les résultats
La lecture des captures d’écran fonctionne. À partir du dossier sans noms de fichiers utiles, l’agent a identifié quel produit chaque capture montrait, quel écran, et laquelle illustrait quelle étape, suffisamment bien pour rédiger le texte environnant.
Le dessin fonctionne aussi, et c’est rapide : comme la spec est du code, une capture reprise après un changement d’interface est ré-annotée en relançant une commande, tant que rien n’a bougé de plus de 1 % environ.
La seule partie qui ne se réduit pas à une commande est l’emplacement de la légende, lequel est dicté par la capture d’écran plutôt que par l’outil.
La règle qui en découle : si l’interface n’a pas d’espace blanc, la légende sort de l’image. Un badge numéroté sur la capture et une liste numérotée dans le texte, ou un recadrage qui crée l’espace. Ce n’est pas une préférence, c’est lisible sur la capture avant même de commencer le dessin.
La loupe est la seule primitive qui s’est avérée indispensable plutôt que décorative.
La découverte qui n’était pas le sujet
L’annotation de deux captures de produits réels a révélé des éléments qui ne devraient pas sortir de l’entreprise. Une capture d’écran d’un éditeur de workflow montrait une clé API en texte clair dans une condition de branchement. Une autre montrait une barre latérale listant les titres de conversations privées.
Cela n’avait été remarqué ni l’un ni l’autre lors de la capture. Les deux sont devenus évidents dès qu’un agent a analysé l’image élément par élément pour identifier chaque chose.
Ce que j’en retire
Dessiner le cadre est mécanique. Placer la légende est le vrai travail. Chaque fois qu’une figure était ratée, c’était parce qu’une légende recouvrait l’élément désigné, et c’était toujours parce que l’interface n’avait pas d’espace pour l’accueillir. C’est un jugement de mise en page sur la capture, et c’est la seule partie qui n’est pas devenue une commande.
Un fichier de spec bat un fichier de design, pour cet usage. Les figures sont du code, donc une capture reprise le mois prochain est ré-annotée via une commande au lieu d’être rouverte et redessinée. Le coût est que la première version de toute figure est moins bonne qu’une version dessinée à la main, et nécessite un ou deux passages pour être stabilisée.
Un passage d’annotation est une revue de confidentialité accidentelle. Personne n’avait prévu d’auditer ces captures. C’est le fait d’examiner chaque région assez précisément pour la décrire qui a fait remonter la clé et les titres de conversations, ce qui justifie d’effectuer ce passage avant la publication plutôt qu’après.
Un flou n’est pas une occultation. Le moteur de rendu floute avec un filtre d’arrière-plan, et un flou de 14px sur un texte de 13px est illisible mais pas forcément irrécupérable. Pour tout ce qui est réellement secret, la solution est un bloc opaque, c’est pourquoi les deux captures contenant un tel bloc sont décrites ici plutôt que montrées.