UI clone : mesurer la référence, la reconstruire, prouver qu'elle correspond
Chaque travail suit une boucle : capturer la référence → la mesurer (lire les valeurs exactes quand c'est possible, mesurer les pixels sinon) → rédiger le cahier des charges → construire dans la stack de l'utilisateur → capturer notre version de la même manière → comparer → corriger, jusqu'à ce que le cahier des charges soit respecté. Le livrable est du code dans le projet de l'utilisateur accompagné de preuves (chiffres, images de différences, feuilles côte à côte), jamais « ça a l'air à peu près correct ». Méthodes adaptées de NiazMorshed2007/reanimate et rossark0/rossark-motion-skill (tous deux sous licence MIT) ; chaque script ici est le nôtre.
<skill> = dossier de ce skill. Le travail se fait dans ./ui-clone/<nom>/ du projet : ref/, ours/, figma/, compare-N/, diff-N/, spec.md. Ajoutez ui-clone/ au .gitignore sauf si l'utilisateur souhaite que les preuves soient versionnées.
Configuration (une fois par machine)
- Python (numpy + Pillow) :
~/.ui-clone/venv/bin/python(créez avecpython3 -m venv ~/.ui-clone/venv && ~/.ui-clone/venv/bin/pip install numpy pillowsi manquant). Exécutez les scripts avec-I. - Capture navigateur (Playwright + Chromium, ~250 Mo, uniquement pour les entrées URL / serveur de dev) : exécuteur dans
~/.ui-clone/runner(npm i [email protected] && npx [email protected] install chromiumà cet endroit). Exécutez les scripts.mjsavecnode <skill>/scripts/<script>.mjs(ils chargent Playwright depuis~/.ui-clone/runner, ouUICLONE_RUNNER; si le Chromium propre à Playwright n'est pas installé, ils utilisent n'importe quel Chromium dans le cache de Playwright, ouUICLONE_CHROMIUM). - ffmpeg/ffprobe dans le PATH. Figma seulement :
FIGMA_TOKEN=...dans l'environnement, lekeys.envdu projet, ou~/.ui-clone/keys.env(jeton d'accès personnel en lecture seule). Ne jamais afficher ni committer les jetons. Demandez avant d'installer quoi que ce soit qui n'est pas présent.
0. Périmètre (en haut de spec.md, avant toute capture)
- Cible : exactement ce qu'il faut cloner (URL + sélecteur, fichier + plage temporelle + recadrage, nœud Figma) et rien de plus.
- Fidélité (à indiquer dans la première réponse ; elle détermine ce qui sera vérifié) :
niveau quand doit correspondre peut différer motion-fidèle (par défaut pour le travail d'autrui) « faire en sorte que le nôtre ressemble/bouge comme le leur » structure et proportions, ordre, timing ±0,08 s, famille d'easing, dépassement, course relative à la taille, décalage copie, couleurs, polices, images, marque pixel-fidèle le propre design de l'utilisateur (Figma → code), son propre site, un travail client pour lequel il a les droits, ou une pratique privée tout ce qui précède + polices, tailles, espacement, couleurs, rayons, ombres, ressources ; différence de capture d'écran ≤ 2 % (≤ 0,5 % au repos), aucun décalage mesuré rien de ce qu'il n'a pas demandé à changer mixte « cloner X et ajouter Y » la partie clonée selon l'un des niveaux ci-dessus les ajouts (gardés séparés, montrés, vérifiés pour ne pas casser le clone) - Droits : les copies pixel-fidèles des UI, logos, illustrations, polices et textes d'autres entreprises leur appartiennent ; utilisez-les uniquement pour apprendre ou avec autorisation, et ne les publiez jamais comme le travail de l'utilisateur. Lorsque la référence est le produit d'un tiers et que l'utilisateur souhaite le publier, optez par défaut pour le niveau motion-fidèle avec son propre design et expliquez pourquoi.
- Destination : où va le code et dans quelle stack. Lisez
package.json, les composants existants, le système de style (configuration Tailwind, variables CSS, tokens de design) et la bibliothèque d'animation déjà utilisée ; alignez-vous sur eux plutôt que d'ajouter une nouvelle bibliothèque.
1. Choisir la méthode d'entrée (la plus précise disponible ; indiquez celle que vous utilisez)
| Entrée | Capture | Ce que vous obtenez |
|---|---|---|
| URL en direct | inspect_web.mjs + capture_web.mjs | valeurs CSS exactes, polices, durées/délais/easings déclarés, keyframes ; enregistrement image par image avec une horloge virtuelle |
| Serveur de dev local (le nôtre) | mêmes scripts sur http://localhost:… | le côté « nôtre » de chaque comparaison, capturé exactement comme la référence |
| Vidéo / GIF / enregistrement d'écran (web ou appli) | ref_frames.py | chaque image au fps source + feuilles de timing/pose ; valeurs mesurées à partir des pixels |
| Figma | figma_fetch.py (jeton) ou images PNG exportées | tailles exactes, espacement, auto-layout, typographie, couleurs, effets, transitions de prototype + une PNG de référence |
| Application mobile | enregistrement d'écran (référence) ; pour la nôtre : xcrun simctl io booted recordVideo ours.mp4 (simulateur iOS) ou adb shell screenrecord (Android) | comme vidéo ; la nôtre capturée de la même manière |
| Combinez-les : valeurs d'URL + un enregistrement pour les interactions difficiles à déclencher (flux connectés, glissés) ; valeurs Figma + le serveur de dev pour vérifier « mon build correspond-il au design ? » ; référence vidéo + capture du serveur de dev pour le nôtre. | ||
| Pages derrière un mur de connexion : demandez un enregistrement d'écran ou que l'utilisateur se connecte ; ne manipulez jamais ses mots de passe. |
2. Capturer et mesurer la référence
URL :
inspect_web.mjs --url URL --selector "<section>" --out ui-clone/<nom>/ref [--state hover --target "<btn>"]→inspect.md: par élément, boîte + styles calculés, transitions déclarées, animations en cours avec keyframes, @keyframes, polices, bibliothèques détectées (GSAP, Framer Motion, Lottie, three.js, Lenis...), canevas (2d/WebGL), différences hover/focus. Les valeurs déclarées priment sur les valeurs mesurées : copiez-les.capture_web.mjs --url URL --selector "<section>" --trigger load|hover|click|scroll|none --duration 2 --fps 30 --out ui-clone/<nom>/ref→ frames/, video.mp4, frames.json, animations.json. Par défaut--mode seek(horloge virtuelle : les timers JS et requestAnimationFrame sur l'horloge de Playwright, les animations CSS/Web Animations mises en pause et avancées image par image : captures identiques). Utilisez--mode realtimepour les pages que l'horloge virtuelle casse (éléments vidéo, certaines bibliothèques WebGL/canvas) et mentionnez-le.--stilldonne une seule capture d'écran stabilisée pour le travail pixel ;--dpr 2pour des comparaisons nettes en rétina (--dpr 3pour les petits éléments : une croissance de 12 px au survol est trop peu de pixels pour ajuster un easing en 1x) ;--pad 12ajoute une marge autour de--selectorpour que les effets de survol/échelle qui dépassent la boîte au repos restent dans le cadre ;--viewport 390x844pour les téléphones. Le mode seek est vérifié comme étant identique d'une exécution à l'autre.--mode realtimeprend de vraies captures d'écran aussi vite que la machine le permet (~19/s sur un portable typique) et rééchantillonne ; il affiche le taux atteint : le timing n'est précis qu'à cette fréquence. Vidéo / GIF / enregistrement :ref_frames.py REF.mp4 --out ui-clone/<nom>/ref [--start --end --crop x:y:w:h]. Figma :figma_fetch.py --url "<lien figma avec node-id>" --out ui-clone/<nom>/figma --scale 2→ design.md/json + frame.png. Ensuite, mesurer le mouvement (pour toute entrée avec images) :- Coupures et sections :
motion_compare.py <ref> <ref> --out <ref>/self --no-align. - Couleurs :
track_motion.py <ref>/frames --sample X,Y --at T. - Chaque élément en mouvement :
track_motion.py <ref>/frames --name el --colors HEX,HEX --tol 35 --region x,y,w,h(toujours une région sur les références chargées). - Chaque déplacement :
fit_easing.py <ref>/track_el.json --prop cx|cy|w|h|aspect|presence --from A --to B→ timing, easing, dépassement, et lignes prêtes à copier en CSS / WAAPI / Framer Motion / GSAP / Remotion. Erreur ≤ 0,03 = ajustement proche ; « aucun easing unique ne correspond » = diviser la fenêtre ou c'est une chaîne de keyframes. Lorsque l'erreur du second est à moins de ~0,003 du meilleur, traitez-le comme une égalité (par exemple easeOutQuad 0,58 s contre easeOutCubic 0,80 s correspondent aux mêmes images) : dites-le, et préférez les valeurs déclarées deinspect.md, du code source ou des feuilles pour départager. Le suivi ne voit un élément que par sa couleur, donc un élément qui apparaît en fondu pendant qu'il bouge semble commencer tard : pour les entrées web, utilisez les valeurs déclarées à la place. Lisez chaque feuille (sheets/poses.png,sheets/timing_NN.png) vous-même : les chiffres disent quoi, les feuilles disent quoi visuellement.
3. Rédiger le cahier des charges (ui-clone/<nom>/spec.md ; chaque ligne devient une vérification)
- Structure & style statique (pixel-fidèle) : élément → boîte, police (famille/taille/poids/hauteur de ligne/espacement des lettres),
couleurs, rayon, ombre, espacement ; source (
inspect.json/design.json/ mesuré). - Chronologie (mouvement) :
| # | élément | propriété | de → à | début ms | durée ms | easing | décalage / répétition | déclencheur | source |. - Notez ce qui ne bouge pas. Un « ? » signifie que la référence n'a pas encore été lue. Montrez le cahier des charges avant une construction importante.
4. Construire
Dans la stack et le système de design de l'utilisateur. Copiez exactement les valeurs déclarées (pixel-fidèle) ou les proportions relatives
(motion-fidèle). Easings depuis inspect.json ou depuis la ligne de fit_easing.py pour leur bibliothèque ; ressorts là où la référence
dépasse et se stabilise ; décalages comme base + index × step. Respectez prefers-reduced-motion (affichez l'état final).
Gardez les ajouts dans des composants séparés. Donnez à notre version une route/page qui rend le composant à la fenêtre de la référence
avec le même déclencheur, afin qu'il puisse être capturé à l'identique. Effets WebGL : reconstruisez le shader à partir de ce que la référence
montre (ou de son source lisible lorsque l'utilisateur peut l'utiliser) ; pas de temps fixe à partir du temps, aléatoire ensemencé.
5. Vérifier, corriger, répéter (2-5 tours ; conservez le dossier de chaque tour)
- Capturez notre version avec la même commande que la référence (seuls
--url/input et--outchangent), ouref_frames.py OURS.mp4 --out ui-clone/<nom>/ours --like <ref>/frames.jsonpour les entrées vidéo. - Pixels :
screenshot_diff.py <ref>/still.png <ours>/still.png --out ui-clone/<nom>/diff-N [--strict] [--max 0.02] [--mask x,y,w,h](pixel-fidèle : toujours--strict: seuil par pixel 0,03, max 0,5 %, et toute région dont la couleur dérive de plus de 3 niveaux RGB échoue ; la valeur par défaut est indulgente et laisse passer les petites variations de padding et de couleur) → % de différence, pires régions, décalages de l'image entière ou par élément (« quelque chose dans la région … a bougé de +0 px x, +6 px y »), dérive de couleur,side_by_side.png. Corrigez d'abord les décalages (ils font tout paraître faux), puis les tailles, puis les couleurs. Pixel-fidèle ÉCHEC sur tout décalage mesuré ; motion-fidèle utilise--allow-shiftet un--maxplus souple. - Mouvement :
motion_compare.py <ref> <ours> --out ui-clone/<nom>/compare-N(coupures, déplacements, décalage ; RÉUSSI ±0,08 s ;activity.png,sheets/compare_NN.png) et, par ligne du cahier des charges,fit_easing.py REF_TRACK --prop P --from A --to B --vs OUR_TRACK. - Lisez les feuilles à chaque tour. Modifiez la plus petite chose que la preuve indique ; recapturez ; recompar ez.
- Après 5 tours, signalez chaque ligne encore en échec avec son chiffre et sa raison (licence de police, effet WebGL approximé, ressort réglé à l'œil). Ne relâchez jamais un seuil en silence.
| Symptôme | Cause habituelle | Correctif |
|---|---|---|
| image entière décalée de N px | défilement/décalage/recadrage différent ou marge manquante d'un wrapper | faites correspondre la fenêtre, le dpr, le recadrage ; corrigez l'espacement extérieur |
| un élément a bougé | marge/padding/hauteur de ligne/espacement entre lettres différent | comparez sa boîte avec inspect.json / design.json |
| texte partout légèrement décalé | police de remplacement, poids ou espacement des lettres différent | chargez la même police (ou l'équivalent sous licence de l'utilisateur), faites correspondre taille/poids/crénage |
| couleurs légèrement décalées partout | espace colorimétrique, empilement d'opacité, arrêts de dégradé | copiez les couleurs/dégradés calculés ; vérifiez l'opacité sur les parents |
| mouvement décalé d'un offset | latence du déclencheur ou délai manquant | corrigez le premier délai |
| notre version antichargée / trop rapide | easing plus fort (expo contre cubic) | utilisez le bezier ajusté ou l'easing déclaré |
| la référence dépasse, pas la nôtre | ressort/back contre bezier | ressort/back réglé sur le dépassement et la stabilisation mesurés |
| l'animation de défilement commence tôt/tard | seuil/décalage du déclencheur | faites correspondre la position de défilement où le mouvement commence |
| un mouvement supplémentaire dans la nôtre | une transition parasite (ex. transition: all) | limitez les transitions aux propriétés qui doivent animer |
6. Rapport (doit se suffire à lui-même)
Niveau de fidélité et ce qui a été cloné / ajouté ; fichiers modifiés et comment déclencher le mouvement ; les tableaux du dernier tour
(différence de pixels et décalages ; timing des coupures/déplacements ; easing par élément), chemins vers side_by_side.png, activity.png et
les feuilles de comparaison ; chaque différence restante avec son chiffre et sa raison ; quelles vérifications ont été mesurées (un script
les a produites) contre estimées à l'œil (regard d'une feuille).
Limites
- La capture par horloge virtuelle ne peut pas contrôler la lecture
<video>ni certaines bibliothèques GPU/physique : utilisez--mode realtimeet attendez-vous à ±1-2 images de gigue ; mentionnez-le. - Les feuilles de style et polices cross-origin peuvent cacher les règles @keyframes/@font-face à l'inspection ; les styles calculés et les animations en cours sont tout de même lus.
- Depuis les vidéos, la 3D est appariée comme mouvement de caméra/objet, pas comme modèles ou matériaux ; une action en direct chargée donne un rythme, pas des valeurs d'élément exactes.
- Mobile : les valeurs proviennent d'enregistrements (pas de source) ; les captures depuis le simulateur de notre version sont comparées de la même manière.