joshfinnie/og-image

Une carte de partage n'a qu'un seul rôle : quelqu'un qui parcourt un fil d'actualité doit comprendre en une seconde environ ce que fait le produit. Les cartes qui fonctionnent montrent le produit en action (une proposition signée, un rappel qu'un client peut confirmer, un prix proposé) plutôt qu'un logo flottant sur un dégradé. Générez la carte à partir du code pour qu'elle reste synchronisée avec la marque et puisse être modifiée ultérieurement sans outil de design.

1. Rassembler la marque avant d'écrire le code

Lisez, dans cet ordre, tout ce qui existe : fichiers de design (DESIGN.md, PRODUCT.md, un guide de style), tokens CSS (globals.css, un @theme Tailwind, des propriétés personnalisées CSS), le titre et sous-titre de la page d'accueil, et le logo (un composant SVG ou un fichier). Utilisez les valeurs hexadécimales réelles et les polices d'affichage et de texte réelles. Une carte avec une police différente de celle du site donne l'impression d'être hors marque.

Cherchez une configuration existante (opengraph-image.*, og.png.*, og:image dans une mise en page) et étendez-la plutôt que d'en ajouter une seconde.

Décidez ensuite ce que la maquette sur la carte doit montrer. Demandez ce qu'un client tient en main après avoir utilisé le produit (une facture, un email de confirmation, une tuile de tableau de bord, un reçu) et dessinez-le. Si ce n'est pas évident, proposez-en une en une phrase et continuez sauf si l'utilisateur s'y oppose.

2. Composer la carte

Partez de cette disposition sauf indication contraire de l'utilisateur ou d'une carte existante. Elle se lit bien aux petites tailles d'affichage des fils.

Zone	Contenu
Toile	1200 × 630. Fond de marque, uni ou avec un léger dégradé radial vers la maquette.
Colonne gauche, environ 620 à 660 px de large, marges intérieures environ 60px 0 60px 72px, espacée avec justify-content: space-between	Haut : logo + marque en 34 à 38 px. Milieu : le titre en 64 à 76 px avec un interlignage serré (0,98 à 1,08) et un espacement négatif léger. Bas : un sous-titre atténué en 26 à 28 px.
Côté droit	La maquette du produit dans les couleurs de la marque avec des données réalistes. Inclinez-la de 2 à 4 degrés, placez une carte de fond de couleur d'accent inclinée dans l'autre sens, et ajoutez une ombre douce comme 0 24px 48px -20px rgba(0,0,0,0.35).

Petites touches utiles : un tampon ou un badge sur la maquette (« Payé », « Confirmé »), une glissière chevauchant le coin de la maquette avec un chiffre clé, des traits de fond discrets à faible opacité.

Texte :

• Le titre est la promesse du produit, idéalement la même phrase que celle de la page d'accueil. La spécificité est plus efficace que l'esprit.
• Les données de la maquette sont concrètes et crédibles (1 510,00 €, 38 cartes, un nom de client plausible). Le texte factice comme lorem ipsum ou $XX donne l'impression que le produit n'est pas terminé.
• Mettre en évidence une phrase du titre dans la couleur d'accent peut aider. Plus d'une la dilue.
• Gardez le texte grand. Les fils d'actualité affichent souvent la carte au tiers de sa taille, donc tout ce qui est en dessous d'environ 18 px disparaît.

3. Rendre l'image

Utilisez Satori qui transforme un arbre de style JSX en SVG, puis pixellisez en PNG. Next.js embarque cela sous next/og. Ailleurs, associez satori à @resvg/resvg-js. Pour le câblage par framework (Next.js App Router, Astro et un script de build simple pour tout autre site statique), lisez references/frameworks.md.

Satori ne supporte qu'un sous-ensemble de CSS, et ces limites causent la plupart des échecs :

• Les polices doivent être de véritables fichiers TTF, OTF ou WOFF passés au moment du rendu. WOFF2 ne fonctionne pas et il n'y a pas de police de secours système. Chargez seulement les deux ou trois graisses que vous utilisez. references/frameworks.md explique où obtenir les fichiers.
• Tout élément avec plus d'un enfant nécessite display: "flex". Satori lève une erreur sinon, donc définissez par défaut chaque boîte en flex.
• Pas de grille CSS, pas de variables CSS, pas de calc(). Mettez les couleurs littérales dans une petite table en haut du fichier (const C = { ink: "#1c2128", ... }).
• Le texte se coupe automatiquement. Surveillez un mot seul sur la dernière ligne et un texte qui empiète sur la maquette. Corrigez en scindant les lignes explicitement (une colonne de span) ou en ajustant la largeur et la taille. whiteSpace: "nowrap" associé à flexShrink: 0 garde les prix et les lignes d'articles sur une seule ligne.
• position: "absolute" fonctionne à l'intérieur d'un parent flex en relatif. Utilisez-le pour la carte de fond, les tampons et les glissières.
• Les chemins SVG en ligne s'affichent bien, donc réutilisez le chemin SVG du logo plutôt que d'incorporer une image. Les images matricielles locales sont converties en données URI base64.

4. Texte alternatif et balises

Écrivez og:image:alt pour décrire ce que l'image montre réellement, sous la forme « Marque : ce que montre la maquette, et le titre. » Par exemple : « Acme Factures : une facture de 1 510,00 € tamponnée Payée, à côté de la ligne : Soyez payé avant de quitter le chantier. »

La page a besoin, avec des URL absolues : og:title, og:description, og:image, og:image:width (1200), og:image:height (630), og:image:alt, twitter:card défini à summary_large_image, et twitter:image. Une og:image relative est la raison la plus courante pour laquelle une carte ne s'affiche pas, car la plupart des déplieurs ne la résoudront pas.

5. Vérifier en regardant

Ne considérez pas la carte comme terminée tant que vous n'avez pas regardé le PNG.

1. Démarrez le serveur de développement, récupérez l'image et ouvrez-la dans un visualiseur d'images, ou avec votre outil de lecture de fichiers s'il affiche les images.

2. Regardez attentivement : mots orphelins, texte touchant la maquette, ombres coupées au bord de la toile, marges inégales, police de secours (elle a l'air clairement incorrecte) et sous-titres à faible contraste. Corrigez et rendez à nouveau jusqu'à ce que ce soit propre.

3. Vérifiez les balises et l'image ensemble :

   python3 scripts/check_og.py http://localhost:3000/ --out /tmp/og-check.png
   

   Il liste chaque balise OG et Twitter, récupère l'image, confirme qu'elle fait 1200×630 et moins de 5 Mo, signale les URL relatives et le mauvais type de carte, et se termine avec le code 1 en cas de problème. Ouvrez le PNG sauvegardé pour confirmer que c'est l'image attendue.

4. Lancez la build de production pour vous assurer que l'image s'y génère toujours.

5. Après le déploiement, exécutez le vérificateur sur l'URL en ligne. Dites à l'utilisateur que Slack, LinkedIn et d'autres mettent en cache les dépliements, donc les liens partagés avant la modification peuvent conserver l'ancienne carte pendant un certain temps. L'inspecteur de posts de LinkedIn force une actualisation.

Lorsque c'est terminé, donnez à l'utilisateur le chemin du PNG et un court paragraphe décrivant la disposition et ce que montre la maquette.