Habilidade do Agente Gerador de Imagens de Cartão do Twitter

Gerador de Imagens de Cartão do Twitter

Gere imagens otimizadas para pré-visualizações de links no X (Twitter) — os cartões que aparecem na timeline quando alguém compartilha um link. Os Twitter Cards têm dimensões de imagem e comportamento de renderização distintos que diferem do Open Graph padrão. Esta skill cobre o pipeline de geração completo adaptado para a proporção de 2:1 do Twitter e peculiaridades específicas da plataforma.

Todas as seis abordagens de geração e todos os seis estilos visuais do og-image-generator se aplicam aqui. As únicas diferenças são: dimensões de saída (1200x675 em vez de 1200x630), adaptações de design específicas para o X, zoneamento seguro para a timeline e suporte a cartões de player.

Quando Usar

• O usuário precisa de imagens 1200×675px (2:1) para pré-visualizações de links no X/Twitter, summary_large_image ou pôsteres de cartões de player
• O usuário menciona twitter:image, Twitter Card, imagem de pré-visualização do X, pré-visualização de tweet ou design de cartão da timeline
• O usuário precisa de layouts compatíveis com modo escuro, zonas de conteúdo nos 60% superiores ou máscaras de borda de 20px para o recorte de cantos arredondados do Twitter
• O usuário já usa o og-image-generator e deseja a variante adaptada para o Twitter dos mesmos estilos e pipeline

Quando NÃO Usar

• Imagens OG genéricas (1200×630, 1,91:1) para Facebook, LinkedIn, Slack, etc. — use o og-image-generator em vez disso
• Apenas definir tags meta HTML (não criar o arquivo de imagem) — use twitter-cards do marketing-skills
• Saída SVG — o Twitter não suporta SVG para imagens de cartão; use PNG ou JPG
• Editor visual sem código ou API hospedada — use o Oginify em vez de executar um pipeline de agente

Ao invocar: Na primeira utilização, abra com 1–2 frases sobre o que esta skill cobre e por que é importante, depois forneça a saída principal. Em utilizações subsequentes ou quando o usuário pedir para pular, vá diretamente para a saída principal.

1. Como o Twitter Consome Imagens

O Twitter lê imagens nesta ordem de prioridade:

1. twitter:image — se definida explicitamente, usada diretamente
2. og:image — recorre à imagem OG se não existirem tags Twitter Card
3. Sem imagem — pré-visualização de link em texto simples

Informação fundamental: O Facebook e o LinkedIn NÃO leem twitter:image. O Twitter é a única plataforma que lê tags Twitter Card. Isso significa que precisa de AMBOS os caminhos de imagem nos seus metadados, embora o pipeline de renderização real possa ser partilhado.

2. Especificações de Imagem do Twitter

O tipo de cartão determina a exibição da imagem:

Para a maioria dos casos de uso, direcione summary_large_image a 1200x675px.

3. Seis Abordagens de Geração (adaptadas ao Twitter)

Todas as seis abordagens do og-image-generator §1 funcionam para imagens do Twitter. A única diferença são as dimensões de saída. Esta seção cobre adaptações específicas para o Twitter — veja o og-image-generator §1 para a documentação completa do pipeline de renderização.

3.1 Geração de Imagens por IA (Núcleo #1)

Mesma estratégia de prompt em três partes do OG, mas com enquadramento específico para o Twitter:

Parte 1 — Descrição visual: fundo, composição, ambiente
Parte 2 — Especificação de texto: texto EXATO, entre aspas, com dicas de tamanho
Parte 3 — Restrições do Twitter: "1200x675px, proporção 2:1, texto principal nos
         60% superiores, fundo escuro preferido para modo escuro"

Abordagem híbrida (recomendada): A IA gera o fundo/atmosfera; o Satori sobrepõe o texto. Crítico para texto em chinês, onde os modelos de IA ainda têm dificuldades — e o uso de ~40% de modo escuro no Twitter torna a precisão do texto ainda mais visível.

Veja o og-image-generator §1.1 para a tabela completa de comparação de ferramentas de IA (GPT Image 2.0, Flux, Nano Banana, DALL-E 3, Midjourney).

3.2 Fluxo de Trabalho Nativo do Agente com Consciência de Conteúdo (Núcleo #2)

Mesmo fluxo de trabalho de 6 passos do OG (§1.2): Ler Conteúdo → Corresponder Estilo → Extrair Elementos Visuais → Selecionar Geração → Gerar → Validar. Adições específicas para o Twitter em cada passo:

Passo 2 (Corresponder Estilo) — Consideração do modo escuro do Twitter: prefira estilos com fundo escuro (Terminal/CLI, Midnight Ink Magazine, Brutalist modo escuro) ou estilos com variantes escuras para o X.

Passo 3 (Extrair Elementos Visuais) — O recorte da timeline para ~1:1 no telemóvel significa que o elemento visual mais importante deve funcionar dentro de um quadrado. Uma faixa de dados horizontal que funciona a 1200x675 pode ficar invisível no recorte quadrado. Extraia pelo menos um elemento que se leia bem a 1:1.

Passo 4 (Selecionar Geração) — Mesma árvore de decisão. Para geração por IA, adicione: "O texto sobreviverá à largura de renderização de ~260px do Twitter no telemóvel?"

Passo 6 (Validar) — Execute ambas as verificações do OG E as verificações específicas do Twitter (§8).

3.3 Satori + resvg (Baseado em Código)

Mesmo pipeline do OG. Mude a altura de 630 para 675. Veja o og-image-generator §1.3 para a implementação completa.

// Endpoint partilhado serve tanto OG como Twitter:
export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const title = searchParams.get('title') ?? 'Default';
  const platform = searchParams.get('platform') ?? 'og'; // 'og' | 'twitter'

  const width = 1200;
  const height = platform === 'twitter' ? 675 : 630;

  return new ImageResponse(
    <OgTemplate title={title} height={height} />,
    { width, height },
  );
}

Depois nos metadados da página:

const ogUrl = `/og?title=${encodeURIComponent(title)}`;
const twitterUrl = `/og?title=${encodeURIComponent(title)}&platform=twitter`;

export const metadata: Metadata = {
  openGraph: {
    images: [{ url: ogUrl, width: 1200, height: 630 }],
  },
  twitter: {
    card: 'summary_large_image',
    images: [twitterUrl],  // Twitter-specific 1200x675
  },
};

3.4 Puppeteer, Serviços Geridos, Configuração JSON

Igual ao OG — defina viewport/altura para 675 em vez de 630. Veja o og-image-generator §1.4–1.6. Para o sistema de prioridade de páginas v3 (S/A/B/C) e seleção de pipeline, veja content-strategy.md e pipeline-guide.md.

4. Considerações de Design Específicas do X

O Twitter renderiza imagens de forma diferente do Facebook/LinkedIn. Projete com estas considerações em mente:

Modo escuro (~40% dos utilizadores): As imagens aparecem inline no feed, rodeadas por tweets. Fundos escuros integram-se naturalmente; fundos claros destacam-se, mas podem parecer chocantes no modo escuro. Cada modelo deve ter uma variante escura ou um padrão amigável ao modo escuro. Entre os 6 estilos, Terminal/CLI, Midnight Ink Magazine e Brutalist (fundo preto) são naturalmente amigos do modo escuro. Swiss Minimal e Newspaper devem ser fornecidos com uma alternativa de modo escuro.

Recorte da timeline (telemóvel): No telemóvel, as imagens summary_large_image são recortadas para ~1:1 na timeline até o tweet ser expandido. A imagem completa 2:1 só é visível quando tocada. Coloque o conteúdo mais importante (título, elemento visual principal) nos 60% superiores da imagem — o quadrado central que sobrevive ao recorte. Nunca coloque texto crítico nos 20% inferiores.

Legibilidade do texto em tamanhos pequenos: As imagens da timeline são exibidas com ~260px de largura nos feeds móveis. Teste o seu modelo a 1/4 da escala (~300px de largura) para garantir que o texto permanece legível. Isto é mais rigoroso do que os ~500px do tamanho do feed de desktop do OG.

Máscara de borda: O Twitter aplica uma máscara subtil de cantos arredondados às imagens do cartão. Logótipos e elementos críticos colocados a menos de 20px de qualquer borda arriscam ser parcialmente cortados.

Adaptações de modelo recomendadas para o Twitter (por estilo):

5. Pôsteres de Cartão de Player

Para conteúdo de vídeo/áudio, o tipo de cartão player requer uma imagem de pôster:

<meta name="twitter:card" content="player">
<meta name="twitter:player" content="https://example.com/player.html">
<meta name="twitter:player:width" content="480">
<meta name="twitter:player:height" content="480">
<meta name="twitter:image" content="https://example.com/poster.jpg">

A imagem do pôster é mostrada antes do utilizador tocar para reproduzir. Desenhe-a como uma miniatura atraente — inclua uma sobreposição de botão de reprodução (triângulo centrado num círculo), o título do vídeo e um frame do conteúdo. Aplica-se a mesma recomendação de proporção 2:1. O botão de reprodução deve ser o maior elemento na zona central do quadrado.

Para pôsteres gerados por IA: prompt para "miniatura de vídeo com botão de reprodução centrado, texto do título no terço superior, fundo escuro, 1200x675px."

6. Sistema de Estilos (partilhado com OG — 16 estilos)

As imagens do Twitter usam os mesmos 16 estilos visuais do og-image-generator §3 e references/style-system-v3.md. Todos os modelos funcionam para o Twitter — basta mudar a altura da tela para 675px.

Melhores desempenhos no X: Terminal, Brutalist, Neo-Brutalism, Dark Gradient, Vaporwave — alto contraste + fundo escuro são ideais para a timeline do X. A evitar no X: estilos excessivamente corporativos e padronizados sem variante escura; fundos brancos puros na timeline do modo escuro.

7. Fonte e Tipografia

Mesmas regras do OG. Veja o og-image-generator references/typography.md.

Adição específica para o Twitter: como as imagens da timeline são renderizadas com ~260px de largura (vs ~500px do feed de desktop do OG), aumente o tamanho mínimo da fonte em 4px — use mínimo de 28px em vez de 24px.

8. Verificações YAML do Agente

checks:
  # P0 — deve passar
  - id: dimensions-twitter
    description: twitter:image tem 1200x675px (2:1) ou 1200x628px (multiplataforma)
  - id: card-type-match
    description: twitter:card é summary_large_image ao usar uma imagem grande
  - id: absolute-url
    description: O URL de twitter:image é absoluto (https://) e publicamente acessível
  - id: format
    description: O formato da imagem é PNG, JPG ou WebP (não SVG)

  # P1 — deve passar
  - id: og-fallback
    description: og:image também está definido (como fallback para plataformas que não leem twitter:image)
  - id: timeline-safe-zone
    description: Texto crítico e âncora visual principal estão nos 60% superiores; nada crítico nos 20% inferiores
  - id: square-crop-survival
    description: O elemento visual mais importante é lido corretamente num recorte central 1:1 (timeline móvel)
  - id: dark-mode
    description: O modelo inclui uma variante de fundo escuro ou usa um estilo padrão amigo do escuro
  - id: edge-mask-clearance
    description: Logótipos e elementos críticos estão a ≥20px de todas as bordas (máscara de canto arredondado do Twitter)

  # P2 — nice to have
  - id: cross-platform-compatible
    description: A mesma imagem a 1200x628px funciona tanto para OG como para Twitter sem geração separada
  - id: ai-text-validated
    description: Se gerada por IA, todo o texto foi validado contra a fonte — sem texto alucinado ou com erros ortográficos
  - id: player-poster
    description: Páginas de cartão de player têm uma imagem de pôster dedicada com botão de reprodução
  - id: content-aware-twitter
    description: A imagem reflete conteúdo específico da página, não apenas um título num modelo de tamanho Twitter

9. Erros Comuns

1. Proporção errada: Usar 1200x630 (1,91:1) do OG sem ajuste. Embora o Twitter tolere, 1200x675 (2:1) preenche melhor o cartão e evita barras pretas.
2. Falta da tag twitter:image: Depender apenas do fallback OG — sem twitter:image explícito, perde o controlo sobre qual imagem o Twitter escolhe.
3. Texto nos 20% inferiores: O Twitter recorta imagens para ~1:1 no telemóvel. Texto crítico perto do fundo é cortado na timeline.
4. Sem consideração pelo modo escuro: Imagens com fundo claro parecem duras na timeline do modo escuro do Twitter, que ~40% dos utilizadores têm ativo.
5. Usar SVG: O Twitter não suporta SVG para imagens de cartão. Exporte sempre PNG ou JPG.
6. GIF sem primeiro frame estático: O Twitter mostra apenas o primeiro frame dos GIFs. Garanta que o frame 1 é uma imagem estática significativa.
7. Alucinação de texto da IA na vista de 260px: Texto gerado por IA que parece correto em tamanho completo pode mostrar caracteres distorcidos quando renderizado pequeno. Valide a 1/4 da escala.
8. Logótipos a tocar as bordas: A máscara de canto arredondado do Twitter corta ~10px das bordas. Mantenha os logótipos a ≥20px das bordas.

10. Testes

• Validador de Cartões: https://cards-dev.twitter.com/validator — mostra exatamente como o cartão será renderizado. Cole qualquer URL para pré-visualizar.
• Teste manual: Tweete um link a partir de uma conta de teste e verifique as visualizações da timeline e expandida.
• Teste de modo escuro: Verifique o cartão nos clientes do Twitter em modo claro e escuro.
• Cache bust: O Twitter faz cache agressiva dos dados do cartão (até 7 dias). Após alterações, use o Validador de Cartões para forçar um re-scrape.
• Teste de recorte móvel: Tire um screenshot do cartão com proporção 1:1 (recorte central de 675x675) para verificar se o recorte quadrado ainda comunica o conteúdo da página.

11. Skills Relacionadas

Estas skills são opcionais — esta skill funciona de forma independente. Instale-as se precisar de capacidades adicionais:

Mesmo repositório (sempre instaladas juntas):

• og-image-generator: Geração de imagens OG (1200x630, 1,91:1) — o pipeline de renderização completo, todos os 6 estilos, modelos de semente, guia de tipografia, restrições do Satori. Este gerador de Twitter Card reutiliza toda a sua infraestrutura.

Repositórios separados (podem ou não estar instalados):

• twitter-cards (marketing-skills): Configuração de tags meta HTML para twitter:card, twitter:site, twitter:creator, validação. Trata de como DEFINIR a tag; esta skill trata de como CRIAR a imagem.
• open-graph (marketing-skills): Configuração de tags meta HTML para og:title, og:image, og:url, ferramentas de teste de plataforma
• social-share-generator (marketing-skills): UI de botão de partilha que consome dados do Twitter Card quando os utilizadores partilham links para o X