imshaikot/app-preview-craft-skill

app-preview-craft — captures d'écran pour store, cartes sociales et vidéos d'appareils 3D

Tout ce que cette compétence produit est une page (stage/stage.html) mise en scène par un thème et capturée par Chrome headless : les images fixes sont des captures d'écran et finalisées par sharp, les vidéos sont rendues image par image et acheminées vers ffmpeg. La même page alimente le studio d'aperçu, donc ce que l'utilisateur voit est exactement ce que la CLI exporte.

0. Trouver la compétence, la configurer une fois

Les chemins ci-dessous sont relatifs au répertoire contenant ce SKILL.md. Résolvez-le une fois et préfixez les commandes avec — $SKILL désigne ce répertoire partout :

SKILL=/chemin/absolu/vers/app-preview-craft        # le dossier avec SKILL.md, scripts/, stage/
# pas sûr de l'endroit où il a été installé ? (dossiers de compétences, puis cache du plugin Claude Code)
find ./.claude/skills ./.agents/skills ./.goose/skills ~/.claude/skills ~/.agents/skills \
     ~/.gemini/skills ~/.config/goose/skills ~/.claude/plugins \
     -path '*app-preview-craft*/scripts/cli.mjs' 2>/dev/null | head -1

Ensuite, vérifiez la machine. --fix exécute npm install dans la compétence lorsque les paquets manquent :

node "$SKILL/scripts/doctor.mjs" --fix

Le docteur doit se terminer par Ready. Un ffmpeg manquant n'est qu'un avertissement (les images fixes fonctionnent toujours). S'il signale l'absence de WebGL, les thèmes 3D ne peuvent pas être rendus — dites-le plutôt que de passer silencieusement à des thèmes plats.

Les sorties vont dans le répertoire où l'utilisateur travaille (le cwd du shell) sauf s'il nomme un autre dossier avec --out. N'écrivez jamais de rendus dans $SKILL. L'état temporaire réside dans $TMPDIR/app-preview-craft/ et est supprimé après chaque exécution.

1. Flux de travail

1. Choisissez la catégorie (le premier argument de la CLI) parmi ce que l'utilisateur a demandé :

   Catégorie	Produit	Taille par défaut
   app-store	Un ensemble : une capture par diapositive, par taille, plus overview.png	iphone-6.9 1320×2868
   social-card	Une carte (ou --all diapositives) pour og/X/LinkedIn/Instagram/story	og 1200×630
   screen-video	Animation 2D à partir des seules captures ; accepte les enregistrements d'écran	reel 1080×1920
   device-video	Vidéo de présentation d'appareil three.js	reel 1080×1920
   device-mockup	Image fixe héroïque 3D, éventuellement transparente	mockup-landscape 2400×1600

2. Rassemblez le contenu. Captures d'écran (PNG/JPG/WebP) et/ou enregistrements (MP4/MOV/WebM) du projet de l'utilisateur, une par diapositive, dans l'ordre. Rédigez le texte vous-même sauf si l'utilisateur l'a fourni (voir §4). Sans captures, l'application exemple fournie "Tempo" est utilisée — acceptable pour montrer les thèmes, jamais pour un livrable.

3. Choisissez un thème. Un thème nommé par l'utilisateur gagne. Pour les ensembles App Store, faites correspondre la catégorie store de l'application avec le tableau du §3 et dites quel thème vous avez choisi et pourquoi. Lorsque l'utilisateur hésite, montrez-lui d'abord les options :

   node "$SKILL/scripts/cli.mjs" gallery app-store        # → ./gallery-app-store.png
   

   Lisez la feuille (pour qu'elle s'affiche pour l'utilisateur) et laissez-le choisir. Le studio (§8) est la meilleure réponse lorsqu'il veut parcourir et ajuster visuellement.

4. Rendu.

   node "$SKILL/scripts/cli.mjs" app-store captures/01.png captures/02.png captures/03.png \
     --theme ledger \
     --title "Chaque euro, *comptabilisé*" --title "Des budgets qui *s'adaptent*" --title "Privé *par conception*" \
     --subtitle "Avantage en une ligne…" --subtitle "…" --subtitle "…" \
     --size iphone-6.9,ipad-13 --set palette.accent=auto
   

5. Inspectez avant de signaler. Lisez overview.png (ensembles), l'image fixe, ou extrayez des images d'une vidéo (--frames 1,4,mid,end rend des images PNG au lieu d'une vidéo — économique pour vérifier le mouvement). Recherchez des titres tronqués, du texte sur l'appareil, un appareil couvrant la décoration, des écrans vides. Corrigez avec --set/remplacements par diapositive et re-rendez.

6. Signalez les chemins de sortie, le thème et la taille, et — chaque fois qu'un appareil 3D apparaît — que CREDITS.txt a été écrit et que le crédit CC-BY doit accompagner les images (§7).

2. Tailles

node "$SKILL/scripts/cli.mjs" list sizes --category app-store affiche le tableau. N'importe quel LxH fonctionne aussi. Plusieurs à la fois : --size iphone-6.9,iphone-6.5,ipad-13.

• App Store Connect nécessite l'ensemble 6,9" (iphone-6.9) pour les applications iPhone et ipad-13 pour les applications iPad ; les autres tailles sont facultatives. La sortie PNG est aplatie (Apple rejette la transparence).
• Les tailles tablette remplacent automatiquement le téléphone par un cadre tablette plat sauf si le thème est sans cadre. Donnez des captures d'écran iPad pour ces diapositives lorsque l'application en a.
• Vidéos d'aperçu d'application : --size app-preview (886×1920) ou app-preview-ipad, 15–30 s, 30 fps. Une piste AAC stéréo silencieuse est ajoutée automatiquement (Connect attend de l'audio).
• Google Play : play-phone, play-tablet, et play-feature (1024×500, carte sociale).

3. Thèmes

list themes --category <c> affiche ceux-ci avec leurs mises en page. Chaque catégorie en a ≥ 5.

app-store — chacun modelé sur une catégorie d'application populaire

Thème	Catégorie d'application	Inspiré par	Aspect
stride	Santé & Fitness	Strava, Nike Run Club	orange vif, pilules condensées en capitales, bandes de vitesse, téléphone incliné
ledger	Finance	Revolut, Monzo, Robinhood	maillage minuit, dégradé menthe→cyan, orbes chromés
serene	Santé & Pleine conscience	Calm, Headspace	aurore pastel, accents italiques serif, écran sans cadre sur une boule douce
canvas	Productivité	Notion, Things, Linear	papier chaud, grille de cahier, grand serif, téléphone à encre plate
sizzle	Nourriture & Boisson	DoorDash, Uber Eats, Deliveroo	jaune ensoleillé, pois, surlignages marqueur rouge, téléphone incliné
wander	Voyage	Airbnb, Hopper, Booking	dégradé crépuscule avec un soleil rétro qui traverse tout l'ensemble (panorama)
mixtape	Musique & Audio	Spotify, Apple Music	votre écran flouté en fond lumineux, mot géant contouré
arcade	Jeux	Apple Arcade, art de lancement de jeux mobiles	grille synthwave, jantes néon, jouets 3D brillants
snapshot	Photo & Social	Instagram, BeReal, VSCO	trois captures sans cadre en éventail comme des tirages, maillage film chaud
pulse	Données de santé & Wearables	Oura, WHOOP, Apple Health	noir clinique, lueur cramoisie, titre sous un Pro Max de face

Les thèmes empruntent une ambiance, jamais une marque : aucun logo, nom ou œuvre de ces applications n'apparaît.

social-card

launch (aurore + téléphone incliné), spotlight (faisceau + sol miroir), pastel-fan (trois écrans en éventail), bento (grille de fragments d'écran), neon-grid (synthwave), editorial (papier, serif, écran duotone), duo (MacBook + téléphone — passez un écran desktop pour le portable).

screen-video (2D)

carousel, stack (les cartes s'envolent), scroll (les captures longues défilent dans le téléphone), zoom-tour (Ken Burns pleine page vers le focus de chaque diapositive), wall (mur incliné d'écrans), store-preview (style d'aperçu App Store — utilisez --size app-preview), grid-reveal.

device-video (3D)

turntable, orbit (la caméra décrit un arc), float (bouclable), rise (la caméra avance), flip (dos → face révélée), trio (trois modèles en éventail), desk (le couvercle du MacBook s'ouvre, le téléphone glisse à côté ; les deux reposent sur scene.floor), spotlight (360° sur un miroir), synthwave, keyframes (votre propre mouvement d'appareil et de caméra, à partir de motion.keys — voir §5).

device-mockup (images fixes 3D)

studio, noir, pedestal, levitate, lineup (chaque modèle de téléphone), flatlay, desk-duo. Ajoutez --transparent pour un PNG détouré.

4. Texte

• Titre par diapositive : ≤ 6 mots, un avantage pas une fonctionnalité. Encadrez 1 à 2 mots avec *astérisques* pour les mettre en valeur dans le style du thème ; " | " force un saut de ligne.
• Sous-titre : une courte phrase. Accroche (facultative) : une étiquette d'un mot au-dessus.
• Les deux premières diapositives portent le message — la plupart des acheteurs ne défilent jamais plus loin.
• N'inventez jamais d'évaluations, de téléchargements, de récompenses ou de citations de presse. Les décorations telles que rating et laurels sont réservées aux chiffres réels que l'utilisateur vous donne ; demandez en cas de doute.
• Ne nommez pas de concurrents et n'utilisez pas de marques Apple/Google dans le texte au-delà de ce que les directives du store autorisent.

5. Configuration de tout

Ordre de résolution, le dernier gagne : base intégrée → valeurs par défaut de la mise en page → thème (et sa chaîne extends) → fichier de thème personnalisé → config projet themeOverrides → raccourcis CLI → --set → thème par diapositive theme.

• Raccourcis : --layout --device --finish --pose --font --body-font --bg --bg2 --bg3 --ink --sub --accent --accent2 --background --pattern --background-image --clean-status-bar --no-decor --duration --fps --speed --intro --outro.
• --set chemin=valeur atteint n'importe quelle clé du thème (répétable). list options affiche les chemins documentés avec types et plages. Les valeurs sont converties ; JSON fonctionne pour les listes/objets : --set device.pose=5,-15,4 --set 'decor=[{"kind":"sparkles","count":8}]'.
• device.pose est x,y,z degrés. Les thèmes restent dans environ ±20° de lacet et ±6° de roulis pour que l'écran reste lisible à la taille de vignette du store ; des poses plus prononcées fonctionnent mais au détriment de la lisibilité.
• Les couleurs acceptent auto = la couleur la plus vive de la première capture d'écran : --accent auto.
• --device iphone-17-pro | iphone-17-pro-max | iphone-12-pro | galaxy-s21-ultra | macbook-pro-16 | flat[:phone|phone-android|tablet|browser] | frameless | none, ou l'identifiant du propre modèle de l'utilisateur (§7).
• Les mises en page sont interchangeables au sein d'un type (list layouts) : images fixes — hero-top, hero-bottom, tilt, duo, fan, split, big-type, callout, bento, laptop-phone, showcase, pedestal, lineup, flatlay ; vidéos — carousel, stack, scroll, zoom-tour, wall, phone-swap, grid-reveal, turntable, orbit, float, rise, flip, trio, desk, spotlight, keyframes.
• Votre propre mouvement : la mise en page keyframes déplace un appareil 3D et la caméra à travers motion.keys, une liste de { "at": 0..1, "x", "y", "size", "pose": [rx, ry, rz], "cam": { "yaw", "pitch", "dist" }, "ease" }. at est une fraction de la vidéo entière ; une valeur qu'une clé omet reprend celle de la clé précédente ; la première clé commence à partir de la pose propre du thème. Eases : linear inOutCubic inOutSine outCubic outQuart outBack inOutQuart outExpo. --theme keyframes --set 'motion.keys=[{"at":0,"y":1.4,"pose":[0,70,0]},{"at":0.3,"y":0.62,"pose":[4,-20,3],"ease":"outQuart"},{"at":1,"pose":[0,15,0],"cam":{"dist":0.9}}]'. Aucune bibliothèque d'animation n'est impliquée : chaque trame est une fonction pure de son temps, ce qui permet de rendre les trames dans le désordre. Vérifiez un mouvement avec --frames 0,2,mid,end.

Thèmes personnalisés sont des fichiers JSON (ou .mjs) avec n'importe quel sous-ensemble de clés de thème plus extends :

{ "extends": "app-store/ledger", "name": "Acme", "palette": { "accent": "#ff5a1f" },
  "type": { "display": "bricolage", "weight": 800 }, "device": { "finish": "#1c1f24" } }

Passez --theme chemin/vers/acme.json, ou déposez-le dans ./.app-preview-craft/themes/ (ou ~/.app-preview-craft/themes/) et utilisez --theme acme. list themes montre les thèmes personnalisés.

Configuration projet. node "$SKILL/scripts/cli.mjs" init app-store écrit app-preview-craft.json ; ensuite node "$SKILL/scripts/cli.mjs" (sans arguments) le rend, et les indicateurs le remplacent toujours. $SKILL/examples/app-preview-craft.json est un exemple complet et fonctionnel : texte par diapositive, décoration et remplacements de thème, un fichier de thème personnalisé, un écran desktop, et une liste jobs qui rend un ensemble App Store, une carte sociale, une maquette et une vidéo en une seule commande. Les chemins dans une config se résolvent relativement au fichier de config.

Clés par diapositive : screen, desktop (affichage portable), title, subtitle, kicker, theme (remplacements pour cette diapositive uniquement), decor (remplace la décoration du thème pour cette diapositive), focus: [x, y, zoom] (cible zoom-tour), hold (secondes dans une vidéo), trim: [start, end] et at (quelle seconde d'un enregistrement une image fixe utilise), bigWord (mise en page big-type).

Objets de décoration sont {kind, x, y, scale, rotate, style, layer, delay, …} avec x/y comme fractions de page et style l'un de glass | solid | light | dark | outline :

kind	clés supplémentaires
badge	text, icon (star bolt heart check sparkle trophy leaf lock music pin flame bell chart shield globe play)
rating	score, label, starColor
laurels	top, text, bottom
chips	items[], icons[], width, lead
notification	app, title, body, time, icon (chemin d'image) ou glyph, width
stat	label, value, trend, trendColor
callout	rect: [x, y, w, h] de la capture à agrandir, w, border, radius
arrow	w, h, text (note manuscrite), flip, stroke
logo	name, src (chemin de l'icône d'application)
store-badge	top, text, ou src pour l'œuvre officielle du badge
sparkles confetti	count, colors[], area: [x0, y0, x1, y1], seed
blob	size, color, opacity (se place derrière l'appareil)
orbs rings shapes	Primitives 3D : count, shapes[], finish (glossy chrome matte glass iridescent), area, items[]
credit	text (par défaut la ligne de crédit du modèle)

6. Écrans et traitements

• sharp prépare chaque capture d'écran avant le démarrage de Chrome : screen.cleanStatusBar (redessine une barre d'état iOS 9:41 / batterie pleine — uniquement pour les captures en forme de téléphone), tint + tintAmount, duotone: "#dark,#light", saturate, brightness, sharpen, et un arrière-plan pré-flouté pour les arrière-plans blur-shot.
• Sur les modèles iPhone, la Dynamic Island est dessinée comme une pilule noire fusionnée sur les découpes pilule-et-caméra du modèle, correspondant à ce qu'iOS affiche. Fournissez des captures d'écran avec la zone de l'île claire (toute capture iOS normale l'est) ; cleanStatusBar conserve l'heure et les icônes de chaque côté.
• Une capture plus haute que l'écran défile dans les vidéos (thème scroll) et montre son sommet dans les images fixes (screen.fit=top).
• Les enregistrements sont divisés en trames par ffmpeg au taux d'images de sortie ; dans les vidéos, chaque diapositive d'enregistrement dure aussi longtemps que le clip (remplacez avec hold, coupez avec trim). Les images fixes utilisent une trame (at, par défaut : le milieu).
• Les écrans portables letterboxent une capture d'écran de téléphone sur une copie floutée sauf si la diapositive a un écran desktop. desktop accepte également un enregistrement. Dans la vidéo desk, la zone du portable affiche l'écran desktop ; sans cela, elle reste vide.

7. Sortie et licence

Chaque exécution écrit un CREDITS.txt dans le dossier de sortie listant les modèles 3D utilisés. Tous les modèles d'appareils dans stage/ sont sous licence Creative Commons Attribution (CC BY 4.0). Les images exportées doivent être accompagnées du crédit — un fichier texte séparé, une ligne dans la description du store, ou un pied de page sur une carte sociale. Le crédit par défaut est :

Maquettes d'appareils par l'équipe app-preview-craft (CC BY 4.0)

Le thème peut remplacer le texte via decor avec kind: "credit". Les modèles d'utilisateur personnalisés (voir --device au §5) n'ont pas besoin de crédit ; les modèles intégrés, oui.

8. Studio d'aperçu

Au lieu de deviner la mise en page :

node "$SKILL/scripts/cli.mjs" studio app-store

ouvre un serveur local, affiche la page de preview studio dans le navigateur, et affiche l'URL. L'utilisateur peut basculer les thèmes, les mises en page, les appareils et les tailles, modifier le texte et la décoration, puis exporter. Le studio lit le même stage/stage.html que la CLI, donc ce qu'il voit est garanti identique à la sortie. studio est le meilleur point de départ lorsque l'utilisateur n'est pas sûr de ce qu'il veut.

9. Exemples

# Ensemble App Store pour une application Fitness
node "$SKILL/scripts/cli.mjs" app-store captures/*.png --theme stride \
  --title "*Pulser* plus fort" --title "Repos *optimisé*" --title "*Tous* les sports" \
  --size iphone-6.9,ipad-13 --set palette.accent=auto

# Carte sociale pour une application Finance
node "$SKILL/scripts/cli.mjs" social-card captures/01.png --theme ledger \
  --title "Votre argent *en pleine conscience*" --size og \
  --set device=iphone-17-pro

# Vidéo de présentation 3D avec mouvement personnalisé
node "$SKILL/scripts/cli.mjs" device-video captures/*.png --theme keyframes \
  --set 'motion.keys=[{"at":0,"y":1.4},{"at":0.3,"y":0.62,"ease":"outQuart"},{"at":1,"pose":[0,15,0]}]'

# Maquette d'appareil transparente
node "$SKILL/scripts/cli.mjs" device-mockup captures/01.png --theme studio --transparent

10. Dépannage

• Le docteur signale WebGL manquant : les thèmes 3D ne fonctionneront pas. Dites-le à l'utilisateur et proposez de basculer sur un thème plat (par exemple, canvas pour app-store).
• Le rendu prend du temps : les vidéos sont lentes car chaque trame est rendue individuellement. Utilisez --frames pour vérifier d'abord le mouvement avec quelques images.
• Les titres sont tronqués : réduisez le texte ou changez de mise en page. Utilisez " | " pour des sauts de ligne.
• L'appareil couvre la décoration : ajustez device.pose ou device.scale. La mise en page showcase donne plus d'espace.
• Les couleurs semblent fades : --accent auto extrait la couleur la plus vive de la première capture.
• Erreur 'Module not found' : exécutez node "$SKILL/scripts/doctor.mjs" --fix pour installer les dépendances.

11. Contribution et extension

Les thèmes personnalisés sont des fichiers JSON ou .mjs (voir §5). Les modèles d'appareils personnalisés peuvent être ajoutés dans stage/models/ ; voir stage/README.md pour le format. Les mises en page personnalisées sont des classes JavaScript dans stage/layouts/ ; voir stage/layouts/hero-top.mjs comme exemple de départ.