joshfinnie/og-image

Um card de compartilhamento tem um trabalho: alguém rolando um feed deve entender o que o produto faz em cerca de um segundo. Os cards que funcionam mostram o produto em ação, como uma proposta assinada, um lembrete que um cliente pode confirmar ou um preço de oferta, em vez de um logotipo flutuando sobre um gradiente. Gere o card a partir do código para que ele se mantenha sincronizado com a marca e possa ser alterado posteriormente sem uma ferramenta de design.

1. Reúna a marca antes de escrever código

Leia, nesta ordem, o que existir: documentos de design (DESIGN.md, PRODUCT.md, um guia de estilo), tokens CSS (globals.css, um @theme do Tailwind, propriedades personalizadas CSS), o título e subtítulo da página inicial e o logotipo (um componente SVG ou arquivo). Use os valores hexadecimais reais e as fontes reais de exibição e corpo. Um card com um tipo de letra diferente do site parece fora da marca.

Procure por uma configuração existente (opengraph-image.*, og.png.*, og:image em um layout) e estenda-a em vez de adicionar uma segunda.

Depois decida o que a maquete no card mostra. Pergunte o que um cliente tem em mãos após usar o produto (uma fatura, um e-mail de confirmação, um bloco de painel, um recibo) e desenhe isso. Se não for óbvio, proponha um em uma frase e prossiga, a menos que o usuário se oponha.

2. Componha o card

Comece a partir deste layout, a menos que o usuário ou um card existente diga o contrário. Ele é lido bem nos tamanhos pequenos em que os feeds o exibem.

Região	Conteúdo
Canvas	1200x630. Fundo da marca, liso ou com um gradiente radial suave em direção à maquete.
Coluna esquerda, com cerca de 620 a 660px de largura, com padding de aproximadamente 60px 0 60px 72px, espaçada com justify-content: space-between	Topo: marca registrada mais logotipo com 34 a 38px. Meio: o título com 64 a 76px, altura de linha apertada (0,98 a 1,08) e espaçamento entre letras ligeiramente negativo. Parte inferior: um subtítulo suave com 26 a 28px.
Lado direito	A maquete do produto nas cores da marca com dados realistas. Incline-a de 2 a 4 graus, coloque um cartão de fundo com cor de destaque inclinado para o outro lado e dê a ele uma sombra suave como 0 24px 48px -20px rgba(0,0,0,0,35).

Pequenos toques que ajudam: um carimbo ou selo na maquete ("Pago", "Confirmado"), um papel sobrepondo o canto da maquete com um número-chave, linhas de fundo tênues com baixa opacidade.

Cópia:

• O título é a promessa do produto, idealmente a mesma linha que a página inicial usa. Específico vence inteligente.
• Os dados da maquete são concretos e verossímeis ($1.510,00, 38 cartas, um nome de cliente plausível). Texto placeholder como lorem ipsum ou $XX faz o produto parecer inacabado.
• Destacar uma frase do título na cor de destaque pode ajudar. Mais de uma a dilui.
• Mantenha o texto grande. Os feeds geralmente mostram o card com um terço do seu tamanho, então qualquer coisa abaixo de cerca de 18px desaparece.

3. Renderize-o

Use Satori, que transforma uma árvore semelhante a JSX em SVG, e depois rasterize para PNG. O Next.js já inclui isso como next/og. Em outros lugares, combine satori com @resvg/resvg-js. Para configuração por framework (Next.js App Router, Astro e um script de build simples para qualquer outro site estático), leia references/frameworks.md.

O Satori suporta apenas um subconjunto de CSS, e esses limites causam a maioria das falhas:

• As fontes devem ser arquivos TTF, OTF ou WOFF reais passados no momento da renderização. WOFF2 não funciona e não há fallback de fonte do sistema. Carregue apenas os dois ou três pesos que você usa. references/frameworks.md aborda onde obter os arquivos.
• Qualquer elemento com mais de um filho precisa de display: "flex". O Satori lança uma exceção caso contrário, então defina toda caixa como flex por padrão.
• Sem CSS grid, sem variáveis CSS, sem calc(). Coloque cores literais em um pequeno mapa no topo do arquivo (const C = { ink: "#1c2128", ... }).
• O texto quebra sozinho. Fique atento a uma única palavra sozinha na última linha e a texto que invade a maquete. Corrija dividindo as linhas explicitamente (uma coluna de spans) ou ajustando a largura e o tamanho. whiteSpace: "nowrap" mais flexShrink: 0 mantém preços e itens de linha em uma linha.
• position: "absolute" funciona dentro de um pai flex relativo. Use-o para o cartão de fundo, carimbos e papéis.
• Caminhos SVG inline são renderizados bem, então reutilize o caminho SVG do logotipo em vez de incorporar uma imagem dele. Imagens raster locais vão como URIs de dados base64.

4. Texto alternativo e tags

Escreva og:image:alt para descrever o que a imagem realmente mostra, no formato "Marca: o que a maquete mostra e o título." Por exemplo: "Acme Invoices: uma fatura de $1.510,00 com carimbo de Pago, ao lado da linha: Receba o pagamento antes de sair do local de trabalho."

A página precisa, com URLs absolutos: og:title, og:description, og:image, og:image:width (1200), og:image:height (630), og:image:alt, twitter:card definido como summary_large_image e twitter:image. Um og:image relativo é o motivo mais comum para um card não aparecer, porque a maioria dos unfurlers não o resolve.

5. Verifique olhando para ele

Não considere o card pronto até ter olhado para o PNG.

1. Inicie o servidor de desenvolvimento, busque a imagem e abra-a em um visualizador de imagens, ou com sua ferramenta de leitura de arquivos se ela exibir imagens.

2. Observe atentamente: palavras órfãs, texto tocando a maquete, sombras cortadas na borda do canvas, padding irregular, uma fonte de fallback (parece obviamente errada) e subtítulos de baixo contraste. Corrija e renderize novamente até que esteja limpo.

3. Verifique as tags e a imagem juntas:

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

   Ele lista todas as tags OG e Twitter, busca a imagem, confirma que é 1200x630 e tem menos de 5MB, sinaliza URLs relativas e o tipo de card errado, e sai com código 1 em qualquer problema. Abra o PNG salvo para confirmar que é a imagem esperada.

4. Execute o build de produção para garantir que a imagem ainda seja gerada lá.

5. Após o deploy, execute o verificador contra a URL ativa. Informe ao usuário que Slack, LinkedIn e outros armazenam em cache unfurls, então links compartilhados antes da alteração podem manter o card antigo por um tempo. O Post Inspector do LinkedIn força uma atualização.

Quando terminar, forneça ao usuário o caminho do PNG e um parágrafo curto descrevendo o layout e o que a maquete mostra.