og-image

OG image

Todo arquivo que este skill usa está em sua própria pasta, ao lado deste SKILL.md, e os caminhos aqui são relativos a essa pasta. Ele não precisa de nada de outros skills ou pastas, então não vá procurar. A menos que o usuário nomeie outro local, salve tudo que ele produzir em out/og-image/ dentro do projeto atual.

Um cartão de compartilhamento vende o produto no meio segundo em que alguém rola a tela e vê um link. A fórmula: marca, um título curto e o produto real embaixo, cortado pela borda inferior. Nada mais.

Estilo de referência (veja references/):

• control-panel.png — marca centrada no topo, um título muito grande de uma linha, e a janela do app (sidebar, cabeçalho, lista) começando a cerca de um terço da altura, sangrando para fora do fundo, com um painel de detalhes flutuante à direita.
• pulse.png — mesma composição construída com o layout real do Pulse: sidebar com ícones de projeto, cabeçalho de busca, página de projeto com abas, linhas de feed e a barra de atividade.

Regras

1. Produto real, nunca inventado. Mostre o app como ele é hoje. Use apenas telas, abas, labels, status e funcionalidades que existem no código. Nenhuma métrica, gráfico ou funcionalidade inventada, mesmo que o texto da landing page fale sobre eles. Se uma demo de marketing no site mostrar algo que o app não tem, não copie essa demo.
2. Mensagem vem do site atual. Use o pitch e o conteúdo de exemplo da homepage ao vivo (seu hero, seus dados de demo) a menos que o usuário forneça um título. Se o usuário der um título, use-o literalmente (um ponto final no final é aceitável para uma headline declarativa; pergunte se não tiver certeza).
3. Pareça vivo, não gerado. Os dados de demo devem parecer com a semana de uma equipe real:
   • Pessoas com aparência real, usando as fotos de avatar do projeto se ele tiver (ex.: public/landing/people); use os nomes que o usuário pedir.
   • Entidades recebem ícones ou imagens, não letras simples (ex.: avatares de projeto como tiles de ícones coloridos com os tons de destaque do tema do produto).
   • Grades de atividade, gráficos e contagens seguem ritmos reais: dias úteis movimentados com variação, fins de semana quase vazios com algum dia leve, a semana atual cortada em hoje, labels de meses onde os meses realmente começam. Nunca um padrão uniforme ou obviamente repetitivo.
   • Horários relativos, IDs, branches e status nos formatos que o app usa.
4. Texto lidera. O título é a maior e mais escura coisa no cartão e legível em tamanho de miniatura (~60–72px em um cartão de 1200px, uma linha, tracking apertado, a fonte de display do produto). O produto fica abaixo dele e nunca se sobrepõe.
5. Apenas o estilo do produto. Fundo, fontes, cores, raios, sombras dos tokens do projeto. Um brilho muito suave com o tom de destaque atrás do título é aceitável; sem novas paletas, gradientes ou imagens de stock.

Passos

1. Descubra

• Leia o componente de homepage/landing e o README para obter o pitch, nome do produto e conteúdo de exemplo.
• Encontre o shell real do app (layout, sidebar, cabeçalho) e a tela principal (rotas + componentes). Anote nomes exatos de classes, tamanhos de texto, labels de abas, tons de chips de status, estados vazios/carregando que você deve evitar.
• Encontre tokens (CSS global / tema), fontes, biblioteca de ícones, componente de marca, assets de avatar.
• Verifique o que já existe: uma rota/imagem OG existente, meta og:image no head da raiz ou página, config WEB_URL/URL do site.

2. Construa uma rota de renderização

Construa o cartão como uma página real na stack do projeto para que use as fontes, tokens e componentes reais (não um SVG desenhado à mão, não um screenshot de produção com dados privados):

• Uma rota, ex.: /og/<page> (TanStack routes/og.<page>.tsx, Next app/og/<page>/page.tsx, etc.), noindex, sem chrome do app.
• Um componente (ex.: og-image.tsx ao lado da landing à qual pertence) renderizando um frame fixo 1200×630 com data-og-frame na raiz e overflow-hidden.
• Layout:
  • Marca centrada, ~48px do topo.
  • Título centralizado abaixo dela.
  • Janela do app começando ~200–240px do topo, ~60px da esquerda, mais larga que o espaço restante para sangrar para fora da borda direita ou inferior. Cantos superiores arredondados, borda fina, sombra do produto.
• Dentro da janela, reconstrua a tela real como uma réplica estática: shell (sidebar + cabeçalho) mais a tela principal. Copie a marcação e as classes dos componentes reais; cite os arquivos fonte em um comentário de cabeçalho. Apenas props estáticas, sem consultas, sem timers.
• Para encaixar um layout de tamanho completo no cartão, disponha a janela em sua largura natural (ex.: 1200px) e reduza-a com zoom (0.85–0.95). zoom também escala top/left no mesmo elemento, então divida os deslocamentos pretendidos pelo fator de zoom.
• Reutilize primitivos de demo existentes da landing (avatars, badges de origem, cores de calor) quando eles corresponderem ao app real.

3. Capture

Inicie o servidor de desenvolvimento (ou reutilize um), então:

node <pasta deste skill>/scripts/capture.mjs \
  --url http://localhost:<porta>/og/<page> \
  --out out/og-image/og-<page>.png

Isso abre um viewport de 1200×630 em 2x (→ 2400×1260), prefere movimento reduzido, esconde overlays de desenvolvimento (devtools do TanStack/Next/Vite/Astro, toasters), aguarda as fontes e tira um screenshot de [data-og-frame]. Use --hide para qualquer outro overlay e --wait se imagens carregarem lentamente.

Problemas comuns:

• Colisão de portas: verifique se a porta realmente está servindo este app (lsof -iTCP:<porta> -sTCP:LISTEN, e veja o título da página). Outro app local em [::1]:<porta> pode responder silenciosamente ao localhost. Escolha uma porta livre se necessário.
• Um servidor de desenvolvimento em segundo plano iniciado a partir de uma sessão de agente morre com a sessão. Desanexe-o (nohup … & disown) se o usuário precisar continuar visualizando.
• Não esconda overlays com regras amplas de :has() / body > div; elas podem esconder a raiz do app e fazer o capture falhar por timeout.

4. Olhe para ele

Abra o PNG e verifique como um designer, em tamanho real e imaginando a 500px de largura:

• Título em uma linha, nada sobrepondo ele, espaço generoso acima da janela.
• Sem badges de devtools, cursores, toasts, skeletons de carregamento ou animações parcialmente reproduzidas.
• Nada cortado estranhamente (um label cortado no meio de uma palavra na borda lateral, um chip meio escondido). Sangramento inferior/direito é intencional; bordas esquerda e superior da janela estão totalmente visíveis.
• Dados parecem reais (regra 3). Itere até que fique assim, então copie o PNG final para public/.

5. Conecte as meta tags

Na página à qual a imagem pertence (ou na raiz para um cartão de todo o site):

• og:type, og:title, og:description
• og:image — URL absoluta, construída a partir da configuração da URL do site (ex.: ${WEB_URL}/og-<page>.png)
• og:image:width 2400, og:image:height 1260, og:image:alt descrevendo título + o que a captura do produto mostra
• twitter:card = summary_large_image, twitter:title, twitter:description, twitter:image

Verifique se as tags aparecem no HTML servido (curl -s <page> | grep og:image) e a URL do PNG retorna 200 image/png.

Saída

Informe ao usuário:

• onde estão o PNG e a rota/componente de renderização
• como regenerar: o comando de captura acima
• o que a imagem mostra e quais telas/componentes reais ela replica
• qualquer coisa que não seja de dados reais (nomes de exemplo, projetos), e que a env de URL do site deve apontar para o domínio de produção para que os crawlers resolvam a imagem