joshfinnie/og-image

Eine Share-Karte hat eine Aufgabe: Jemand, der durch einen Feed scrollt, sollte in etwa einer Sekunde verstehen, was das Produkt tut. Die Karten, die funktionieren, zeigen das Produkt in Aktion, wie einen unterschriebenen Vorschlag, eine Erinnerung, die ein Kunde bestätigen kann, oder einen Angebotspreis – statt eines Logos, das auf einem Farbverlauf schwebt. Erstelle die Karte aus Code, damit sie mit der Marke synchron bleibt und später ohne ein Design-Tool geändert werden kann.

1. Die Marke vor dem Schreiben von Code erfassen

Lies in dieser Reihenfolge, was vorhanden ist: Designdokumente (DESIGN.md, PRODUCT.md, ein Styleguide), CSS-Tokens (globals.css, ein Tailwind @theme, CSS-Custom-Properties), die Überschrift und Unterzeile der Landingpage sowie das Logo (eine SVG-Komponente oder -Datei). Verwende die tatsächlichen Hex-Werte und die tatsächlichen Anzeige- und Textschriftarten. Eine Karte in einer anderen Schriftart als die Website wirkt nicht markenkonform.

Suche nach einer vorhandenen Einrichtung (opengraph-image.*, og.png.*, og:image in einem Layout) und erweitere sie, anstatt eine zweite hinzuzufügen.

Entscheide dann, was der Mock auf der Karte zeigt. Frage, was ein Kunde nach der Nutzung des Produkts in der Hand hält (eine Rechnung, eine Bestätigungs-E-Mail, eine Dashboard-Kachel, eine Quittung) und zeichne das. Wenn es nicht offensichtlich ist, schlage einen Satz vor und fahre fort, es sei denn, der Benutzer widerspricht.

2. Die Karte zusammenstellen

Beginne mit diesem Layout, es sei denn, der Benutzer oder eine vorhandene Karte sagt etwas anderes. Es liest sich gut in den kleinen Größen, in denen Feeds es anzeigen.

Bereich	Inhalt
Leinwand	1200×630. Markenhintergrund, flach oder mit einem sanften radialen Farbverlauf zum Mock hin.
Linke Spalte, etwa 620 bis 660 px breit, mit etwa 60px 0 60px 72px Abstand und justify-content: space-between	Oben: Logo-Marke plus Wortmarke in 34 bis 38 px. Mitte: die Überschrift in 64 bis 76 px mit enger Zeilenhöhe (0,98 bis 1,08) und leicht negativem Buchstabenabstand. Unten: eine dezente Unterzeile in 26 bis 28 px.
Rechte Seite	Der Produkt-Mock in Markenfarben mit realistischen Daten. Neige ihn um 2 bis 4 Grad, platziere eine farbig akzentuierte Rückseite dahinter, die in die andere Richtung geneigt ist, und gib ihm einen weichen Schatten wie 0 24px 48px -20px rgba(0,0,0,0.35).

Kleine Details, die helfen: ein Stempel oder Abzeichen auf dem Mock („Bezahlt“, „Bestätigt“), ein überlappender Zettel an einer Ecke des Mocks mit einer wichtigen Zahl, schwache Hintergrundlinien bei geringer Deckkraft.

Text:

• Die Überschrift ist das Versprechen des Produkts, idealerweise der gleiche Satz, mit dem die Landingpage beginnt. Konkret ist besser als ausgeklügelt.
• Mock-Daten sind konkret und glaubwürdig ($1.510,00, 38 Karten, ein plausibler Kundenname). Platzhaltertexte wie Lorem Ipsum oder $XX lassen das Produkt unfertig wirken.
• Die Hervorhebung einer Phrase der Überschrift in der Akzentfarbe kann helfen. Mehr als eine verwässert den Effekt.
• Halte Texte groß. Feeds zeigen die Karte oft auf einem Drittel ihrer Größe, also verschwindet alles unter etwa 18 px.

3. Rendern

Verwende Satori, das einen JSX-ähnlichen Baum in SVG umwandelt, und rastere dann zu PNG. Next.js liefert dies als next/og. Anderswo kombiniere satori mit @resvg/resvg-js. Für die frameworkspezifische Einrichtung (Next.js App Router, Astro und ein einfaches Build-Script für jede andere statische Website) lies references/frameworks.md.

Satori unterstützt nur eine Teilmenge von CSS, und diese Einschränkungen verursachen die meisten Fehler:

• Schriftarten müssen echte TTF-, OTF- oder WOFF-Dateien sein, die zur Renderzeit übergeben werden. WOFF2 funktioniert nicht, und es gibt keinen Systemschriftarten-Fallback. Lade nur die zwei oder drei Gewichte, die du verwendest. references/frameworks.md erklärt, wo die Dateien zu bekommen sind.
• Jedes Element mit mehr als einem Kind benötigt display: "flex". Andernfalls wirft Satori einen Fehler, also setze standardmäßig jede Box auf flex.
• Kein CSS-Grid, keine CSS-Variablen, kein calc(). Setze Literalfarben in eine kleine Map am Anfang der Datei (const C = { ink: "#1c2128", ... }).
• Text bricht von selbst um. Achte auf einzelne Wörter in der letzten Zeile und auf Text, der in den Mock hineinragt. Behebe dies, indem du Zeilen explizit trennst (eine Spalte von Spans) oder die Breite und Größe anpasst. whiteSpace: "nowrap" plus flexShrink: 0 hält Preise und Positionspositionen in einer Zeile.
• position: "absolute" funktioniert innerhalb eines relativen Flex-Containers. Verwende es für die Rückseite, Stempel und Zettel.
• Inline-SVG-Pfade rendern gut, also verwende den SVG-Pfad des Logos wieder, anstatt ein Bild davon einzubetten. Lokale Rasterbilder werden als Base64-Daten-URIs eingefügt.

4. Alt-Text und Tags

Schreibe og:image:alt, um zu beschreiben, was das Bild tatsächlich zeigt, in der Form „Marke: was der Mock zeigt, und die Überschrift.“ Zum Beispiel: „Acme Invoices: eine Rechnung über 1.510,00 $ mit dem Stempel Bezahlt, neben dem Satz: Hol dir dein Geld, bevor du die Baustelle verlässt.“

Die Seite benötigt mit absoluten URLs: og:title, og:description, og:image, og:image:width (1200), og:image:height (630), og:image:alt, twitter:card gesetzt auf summary_large_image und twitter:image. Ein relativer og:image-Pfad ist der häufigste Grund, warum eine Karte nicht angezeigt wird, da die meisten Unfurl-Tools ihn nicht auflösen.

5. Durch Ansehen überprüfen

Betrachte die Karte erst dann als fertig, wenn du das PNG angesehen hast.

1. Starte den Dev-Server, rufe das Bild ab und öffne es in einem Bildbetrachter oder mit deinem dateilesenden Tool, falls es Bilder anzeigt.

2. Achte besonders auf: vereinzelte Wörter, Text, der den Mock berührt, Schatten, die am Leinwandrand abgeschnitten sind, ungleichmäßige Abstände, eine Fallback-Schriftart (sie sieht offensichtlich falsch aus) und kontrastarme Unterzeilen. Korrigiere sie und rendere erneut, bis es sauber ist.

3. Überprüfe die Tags und das Bild gemeinsam:

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

   Es listet jedes OG- und Twitter-Tag auf, ruft das Bild ab, bestätigt, dass es 1200×630 und unter 5 MB ist, markiert relative URLs und den falschen Kartentyp und beendet sich mit Exit-Code 1 bei jedem Problem. Öffne das gespeicherte PNG, um zu bestätigen, dass es das erwartete Bild ist.

4. Führe den Produktions-Build aus, um sicherzustellen, dass das Bild dort immer noch generiert wird.

5. Führe nach dem Deployment den Checker gegen die Live-URL aus. Teile dem Benutzer mit, dass Slack, LinkedIn und andere Unfurls zwischenspeichern, sodass vor der Änderung geteilte Links möglicherweise die alte Karte behalten. Der LinkedIn Post Inspector erzwingt eine Aktualisierung.

Wenn du fertig bist, gib dem Benutzer den Pfad zum PNG und einen kurzen Absatz, der das Layout und das, was der Mock zeigt, beschreibt.