joshfinnie/og-image

Una tarjeta para compartir tiene un solo trabajo: alguien que se desplaza por un feed debe entender qué hace el producto en aproximadamente un segundo. Las tarjetas que funcionan muestran el producto en acción, como una propuesta firmada, un recordatorio que un cliente puede confirmar o un precio de oferta, en lugar de un logotipo flotando sobre un degradado. Genera la tarjeta desde código para que se mantenga sincronizada con la marca y pueda modificarse más tarde sin una herramienta de diseño.

1. Reúne la marca antes de escribir código

Lee, en este orden, lo que exista: documentos de diseño (DESIGN.md, PRODUCT.md, una guía de estilo), tokens CSS (globals.css, un @theme de Tailwind, propiedades personalizadas CSS), el titular y subtitular de la página de inicio, y el logotipo (un componente SVG o archivo). Utiliza los valores hexadecimales reales y las tipografías reales de visualización y cuerpo. Una tarjeta con una tipografía diferente a la del sitio se percibe como fuera de marca.

Busca una configuración existente (opengraph-image.*, og.png.*, og:image en un layout) y extiéndela en lugar de agregar una segunda.

Luego decide qué mostrará el mock en la tarjeta. Pregunta qué tiene un cliente en sus manos después de usar el producto (una factura, un correo de confirmación, un mosaico del panel, un recibo) y dibuja eso. Si no es obvio, propón uno en una oración y continúa a menos que el usuario se oponga.

2. Compón la tarjeta

Comienza desde este diseño a menos que el usuario o una tarjeta existente indiquen lo contrario. Se ve bien en los tamaños pequeños en los que los feeds la muestran.

Región	Contenido
Lienzo	1200x630. Fondo de la marca, plano o con un suave degradado radial hacia el mock.
Columna izquierda, aproximadamente 620 a 660px de ancho, con relleno de unos 60px 0 60px 72px, espaciada con justify-content: space-between	Arriba: marca más logotipo de texto de 34 a 38px. Medio: el titular de 64 a 76px con altura de línea ajustada (0.98 a 1.08) y un interletraje ligeramente negativo. Abajo: un subtitular atenuado de 26 a 28px.
Lado derecho	El mock del producto en colores de la marca con datos realistas. Inclínalo de 2 a 4 grados, coloca una tarjeta de respaldo de color de acento detrás inclinada en la dirección opuesta, y dale una sombra suave como 0 24px 48px -20px rgba(0,0,0,0.35).

Pequeños detalles que ayudan: un sello o insignia en el mock ("Pagado", "Confirmado"), un resbalón que se superpone a la esquina del mock con un número clave, líneas de fondo tenues con baja opacidad.

Texto:

• El titular es la promesa del producto, idealmente la misma línea que usa la página de inicio. Lo específico vence a lo ingenioso.
• Los datos del mock son concretos y creíbles ($1,510.00, 38 tarjetas, un nombre de cliente plausible). El texto de relleno como lorem ipsum o $XX hace que el producto parezca inacabado.
• Resaltar una frase del titular en el color de acento puede ayudar. Más de una lo diluye.
• Mantén el texto grande. Los feeds a menudo muestran la tarjeta a un tercio de su tamaño, por lo que cualquier cosa por debajo de unos 18px desaparece.

3. Renderízalo

Usa Satori, que convierte un árbol similar a JSX en SVG, y luego rasteriza a PNG. Next.js incluye esto como next/og. En otros casos, combina satori con @resvg/resvg-js. Para la configuración por framework (Next.js App Router, Astro y un script de compilación simple para cualquier otro sitio estático), lee references/frameworks.md.

Satori solo admite un subconjunto de CSS, y estos límites causan la mayoría de los fallos:

• Las fuentes deben ser archivos TTF, OTF o WOFF reales pasados en el momento del renderizado. WOFF2 no funciona y no hay fuente del sistema de respaldo. Carga solo los dos o tres pesos que uses. references/frameworks.md cubre dónde obtener los archivos.
• Cualquier elemento con más de un hijo necesita display: "flex". Satori falla de lo contrario, así que establece cada caja como flex por defecto.
• No hay CSS grid, no hay variables CSS, no hay calc(). Coloca los colores literales en un mapa pequeño al principio del archivo (const C = { ink: "#1c2128", ... }).
• El texto se ajusta solo. Presta atención a una sola palabra al final de la última línea y al texto que se superpone con el mock. Soluciónalo dividiendo las líneas explícitamente (una columna de spans) o ajustando el ancho y el tamaño. whiteSpace: "nowrap" más flexShrink: 0 mantiene los precios y los elementos de línea en una sola línea.
• position: "absolute" funciona dentro de un padre flex relativo. Úsalo para la tarjeta de respaldo, sellos y resbalones.
• Las rutas SVG en línea se renderizan bien, así que reutiliza la ruta SVG del logotipo en lugar de incrustar una imagen del mismo. Las imágenes rasterizadas locales se incluyen como URI de datos base64.

4. Texto alternativo y etiquetas

Escribe og:image:alt para describir lo que la imagen realmente muestra, en la forma "Marca: lo que muestra el mock, y el titular." Por ejemplo: "Facturas Acme: una factura por $1,510.00 sellada como Pagada, junto a la línea: Cobra antes de irte del sitio de trabajo."

La página necesita, con URLs absolutas: og:title, og:description, og:image, og:image:width (1200), og:image:height (630), og:image:alt, twitter:card configurado como summary_large_image, y twitter:image. Una og:image relativa es la razón más común por la que una tarjeta no aparece, ya que la mayoría de los 'unfurlers' no la resolverán.

5. Verifica mirándola

No des la tarjeta por terminada hasta que hayas mirado el PNG.

1. Inicia el servidor de desarrollo, obtén la imagen y ábrela en un visor de imágenes, o con tu herramienta de lectura de archivos si muestra imágenes.

2. Examina detenidamente: palabras huérfanas, texto que toca el mock, sombras recortadas en el borde del lienzo, relleno desigual, una fuente de respaldo (se ve claramente mal) y subtitulares de bajo contraste. Corrígelos y renderiza de nuevo hasta que esté limpio.

3. Verifica las etiquetas y la imagen juntas:

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

   Enumera cada etiqueta OG y de Twitter, obtiene la imagen, confirma que sea de 1200x630 y de menos de 5MB, señala URLs relativas y el tipo de tarjeta incorrecto, y sale con 1 si hay algún problema. Abre el PNG guardado para confirmar que es la imagen que esperas.

4. Ejecuta la compilación de producción para asegurarte de que la imagen aún se genera allí.

5. Después del despliegue, ejecuta el verificador contra la URL en vivo. Informa al usuario que Slack, LinkedIn y otros almacenan en caché los 'unfurls', por lo que los enlaces compartidos antes del cambio pueden mantener la tarjeta anterior por un tiempo. El Post Inspector de LinkedIn fuerza una actualización.

Cuando termines, entrega al usuario la ruta del PNG y un párrafo corto que describa el diseño y lo que muestra el mock.