Competenza agente generatore di immagini per Twitter Card

Generatore di immagini per Twitter Card

Genera immagini ottimizzate per le anteprime dei link su X (Twitter) — le card che appaiono nella timeline quando qualcuno condivide un link. Le Twitter Card hanno dimensioni e comportamenti di rendering distinti rispetto all'Open Graph standard. Questa competenza copre l'intera pipeline di generazione adattata per le proporzioni 2:1 di Twitter e le sue peculiarità specifiche di piattaforma.

Tutti i sei approcci di generazione e tutti i sei stili visivi di generatore-immagini-og si applicano qui. Le uniche differenze sono: dimensioni di output (1200x675 invece di 1200x630), adattamenti di design specifici per X, zone sicure per la timeline e supporto per player card.

Quando usarla

• L'utente necessita di immagini 1200×675px (2:1) per anteprime di link X/Twitter, summary_large_image o poster di player card
• L'utente menziona twitter:image, Twitter Card, immagine anteprima X, anteprima tweet o design card timeline
• L'utente necessita di layout adatti alla modalità scura, zone di contenuto nel 60% superiore, o maschere di 20px ai bordi per il ritaglio ad angoli arrotondati di X
• L'utente già utilizza generatore-immagini-og e desidera la variante adattata per Twitter degli stessi stili e pipeline

Quando NON usarla

• Immagini OG generiche (1200×630, 1.91:1) per Facebook, LinkedIn, Slack, ecc. — usa invece generatore-immagini-og
• Solo impostazione dei meta tag HTML (non la creazione del file immagine) — usa twitter-cards da marketing-skills
• Output SVG — Twitter non supporta SVG per le immagini delle card; usa PNG o JPG
• Editor visivo no-code o API ospitata — usa Oginify invece di eseguire una pipeline agente

All'invocazione: Al primo utilizzo, apri con 1-2 frasi su cosa copre questa competenza e perché è importante, poi fornisci l'output principale. Ad utilizzi successivi o quando l'utente chiede di saltare, vai direttamente all'output principale.

1. Come Twitter consuma le immagini

Twitter legge le immagini in questo ordine di priorità:

1. twitter:image — se impostata esplicitamente, usata direttamente
2. og:image — ricade sull'immagine OG se non esistono tag Twitter Card
3. Nessuna immagine — anteprima link in testo semplice

Intuizione chiave: Facebook e LinkedIn NON leggono twitter:image. Twitter è l'unica piattaforma che legge i tag Twitter Card. Ciò significa che hai bisogno di ENTRAMBI i percorsi immagine nei tuoi metadati, anche se la pipeline di rendering effettiva può essere condivisa.

2. Specifiche delle immagini per Twitter

Il tipo di card determina la visualizzazione dell'immagine:

Per la maggior parte dei casi d'uso, mira a summary_large_image a 1200x675px.

3. Sei approcci di generazione (adattati per Twitter)

Tutti i sei approcci dal §1 di generatore-immagini-og funzionano per le immagini Twitter. L'unica differenza sono le dimensioni di output. Questa sezione copre gli adattamenti specifici per Twitter — vedi il §1 di generatore-immagini-og per la documentazione completa della pipeline di rendering.

3.1 Generazione di immagini AI (Core #1)

Stessa strategia di prompt in tre parti come OG, ma con inquadramento specifico per Twitter:

Parte 1 — Descrizione visiva: sfondo, composizione, atmosfera
Parte 2 — Specifica del testo: testo ESATTO, tra virgolette, con indicazioni di dimensione
Parte 3 — Vincoli Twitter: "1200x675px, proporzioni 2:1, testo chiave nel
         60% superiore, sfondo scuro preferito per la modalità scura"

Approccio ibrido (consigliato): L'AI genera lo sfondo/l'atmosfera; Satori sovrappone il testo. Fondamentale per il testo in cinese dove i modelli AI ancora faticano — e l'uso della modalità scura di Twitter (~40% degli utenti) rende l'accuratezza del testo ancora più visibile.

Vedi il §1.1 di generatore-immagini-og per la tabella completa di confronto degli strumenti AI (GPT Image 2.0, Flux, Nano Banana, DALL-E 3, Midjourney).

3.2 Flusso di lavoro nativo-agente consapevole del contenuto (Core #2)

Stesso flusso di lavoro a 6 passi come OG (§1.2): Leggi contenuto → Abbina stile → Estrai elementi visivi → Seleziona generazione → Genera → Valida. Aggiunte specifiche per Twitter ad ogni passo:

Passo 2 (Abbina stile) — Considerazione modalità scura Twitter: preferisci stili con sfondo scuro (Terminal/CLI, Midnight Ink Magazine, Brutalist dark mode) o stili con varianti scure per X.

Passo 3 (Estrai elementi visivi) — Il ritaglio della timeline di Twitter a ~1:1 su mobile significa che l'elemento visivo più importante deve funzionare dentro un quadrato. Un nastro dati orizzontale che funziona a 1200x675 potrebbe essere invisibile nel ritaglio quadrato. Estrai almeno un elemento che si legga bene a 1:1.

Passo 4 (Seleziona generazione) — Stesso albero decisionale. Per la generazione AI, aggiungi: "Il testo sopravviverà alla larghezza di rendering mobile ~260px di Twitter?"

Passo 6 (Valida) — Esegui entrambi i controlli OG E i controlli specifici per Twitter (§8).

3.3 Satori + resvg (Basato su codice)

Stessa pipeline di OG. Cambia l'altezza da 630 a 675. Vedi il §1.3 di generatore-immagini-og per l'implementazione completa.

// Endpoint condiviso serve sia OG che 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 },
  );
}

Poi nei metadati della pagina:

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],  // Specifico per Twitter 1200x675
  },
};

3.4 Puppeteer, Servizi gestiti, Configurazione JSON

Come OG — imposta viewport/altezza a 675 invece di 630. Vedi i §1.4–1.6 di generatore-immagini-og. Per il sistema di priorità delle pagine v3 (S/A/B/C) e la selezione della pipeline, vedi content-strategy.md e pipeline-guide.md.

4. Considerazioni di design specifiche per X

Twitter rende le immagini in modo diverso da Facebook/LinkedIn. Progetta tenendo presente questi aspetti:

Modalità scura (~40% degli utenti): Le immagini appaiono in linea nel feed, circondate da tweet. Sfondi scuri si integrano naturalmente; sfondi chiari risaltano ma possono sembrare stridenti in modalità scura. Ogni template dovrebbe avere una variante scura o un default adatto alla modalità scura. Tra i 6 stili, Terminal/CLI, Midnight Ink Magazine, e Brutalist (sfondo nero) sono naturalmente amici della modalità scura. Swiss Minimal e Newspaper dovrebbero essere forniti con un'alternativa per la modalità scura.

Ritaglio della timeline (mobile): Su mobile, le immagini summary_large_image vengono ritagliate a ~1:1 nella timeline finché il tweet non viene espanso. L'immagine completa 2:1 è visibile solo quando toccata. Posiziona il contenuto più importante (titolo, elemento visivo primario) nel 60% superiore dell'immagine — il quadrato centrale che sopravvive al ritaglio. Non mettere mai testo critico nel 20% inferiore.

Leggibilità del testo a dimensioni ridotte: Le immagini della timeline vengono visualizzate a ~260px di larghezza nei feed mobili. Testa il tuo template a scala 1/4 (~300px di larghezza) per assicurarti che il testo rimanga leggibile. Questo è più restrittivo rispetto alla dimensione del feed desktop di OG ~500px.

Maschera ai bordi: Twitter applica una sottile maschera di angoli arrotondati alle immagini delle card. Loghi ed elementi critici posizionati entro 20px da qualsiasi bordo rischiano di essere parzialmente ritagliati.

Adattamenti dei template raccomandati per Twitter (per stile):

5. Poster delle Player Card

Per contenuti video/audio, il tipo di card player richiede un'immagine poster:

<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">

L'immagine poster viene mostrata prima che l'utente tocchi play. Progettala come una miniatura coinvolgente — includi una sovrapposizione di pulsante play (triangolo centrato in un cerchio), il titolo del video, e un fotogramma del contenuto. Si applica la stessa raccomandazione delle proporzioni 2:1. Il pulsante play dovrebbe essere l'elemento più grande nella zona quadrata centrale.

Per poster generati con AI: prompt per "miniatura video con pulsante play centrato, testo del titolo nel terzo superiore, sfondo scuro, 1200x675px."

6. Sistema di stili (condiviso con OG — 16 stili)

Le immagini per Twitter usano gli stessi 16 stili visivi dal §3 di generatore-immagini-og e riferimenti/style-system-v3.md. Tutti i template funzionano per Twitter — basta cambiare l'altezza del canvas a 675px.

Top performer su X: Terminal, Brutalist, Neo-Brutalism, Dark Gradient, Vaporwave — alto contrasto + sfondo scuro sono ottimali per la timeline di X. Da evitare su X: stili aziendali eccessivamente conformi senza variante scura; sfondi bianchi puri nella timeline in modalità scura.

7. Font e Tipografia

Stesse regole di OG. Vedi il riferimenti/typography.md di generatore-immagini-og.

Aggiunta specifica per Twitter: poiché le immagini della timeline vengono renderizzate a ~260px di larghezza (contro i ~500px del feed desktop di OG), aumenta la dimensione minima del font di 4px — usa 28px minimo invece di 24px.

8. Controlli YAML Agente

checks:
  # P0 — deve passare
  - id: dimensions-twitter
    description: twitter:image è 1200x675px (2:1) o 1200x628px (multipiattaforma)
  - id: card-type-match
    description: twitter:card è summary_large_image quando si usa un'immagine grande
  - id: absolute-url
    description: L'URL di twitter:image è assoluto (https://) e pubblicamente accessibile
  - id: format
    description: Il formato dell'immagine è PNG, JPG, o WebP (non SVG)

  # P1 — dovrebbe passare
  - id: og-fallback
    description: og:image è anche impostato (come fallback per le piattaforme che non leggono twitter:image)
  - id: timeline-safe-zone
    description: Il testo critico e l'ancora visiva primaria sono nel 60% superiore; niente di critico nel 20% inferiore
  - id: square-crop-survival
    description: L'elemento visivo più importante si legge correttamente in un ritaglio centrale 1:1 (timeline mobile)
  - id: dark-mode
    description: Il template include una variante con sfondo scuro o usa uno stile predefinito adatto alla modalità scura
  - id: edge-mask-clearance
    description: Loghi ed elementi critici sono a ≥20px da tutti i bordi (maschera di angoli arrotondati di Twitter)

  # P2 — gradito ma non essenziale
  - id: cross-platform-compatible
    description: La stessa immagine a 1200x628px funziona sia per OG che per Twitter senza generazione separata
  - id: ai-text-validated
    description: Se generata con AI, tutto il testo è stato validato rispetto alla fonte — nessun testo allucinato o con errori di ortografia
  - id: player-poster
    description: Le pagine con player card hanno un'immagine poster dedicata con pulsante play
  - id: content-aware-twitter
    description: L'immagine riflette il contenuto specifico della pagina, non solo un titolo in un template di dimensioni Twitter

9. Errori comuni

1. Proporzioni sbagliate: Usare 1200x630 di OG (1.91:1) senza aggiustamenti. Sebbene Twitter lo tolleri, 1200x675 (2:1) riempie meglio la card ed evita il letterboxing.
2. Tag twitter:image mancante: Fare affidamento solo sul fallback OG — senza un twitter:image esplicito, perdi il controllo su quale immagine Twitter sceglie.
3. Testo nel 20% inferiore: Twitter ritaglia le immagini a ~1:1 su mobile. Il testo critico vicino al fondo viene tagliato nella timeline.
4. Nessuna considerazione per la modalità scura: Immagini con sfondo chiaro appaiono dure nella timeline della modalità scura di Twitter, che ~40% degli utenti ha abilitato.
5. Usare SVG: Twitter non supporta SVG per le immagini delle card. Output sempre PNG o JPG.
6. GIF senza primo frame statico: Twitter mostra solo il primo frame delle GIF. Assicurati che il frame 1 sia un'immagine statica significativa.
7. Allucinazione del testo AI nella vista a 260px: Il testo generato dall'AI che sembra corretto a piena dimensione può mostrare caratteri confusi quando renderizzato piccolo. Valida a scala 1/4.
8. Loghi che toccano i bordi: La maschera di angoli arrotondati di Twitter ritaglia ~10px dai bordi. Mantieni i loghi a ≥20px dai bordi.

10. Test

• Card Validator: https://cards-dev.twitter.com/validator — mostra esattamente come la card verrà renderizzata. Incolla qualsiasi URL per l'anteprima.
• Test manuale: Tweetta un link da un account di test, poi controlla le viste timeline ed espanse.
• Test modalità scura: Controlla la card sia in modalità chiara che scura nei client Twitter.
• Cache bust: Twitter memorizza i dati della card in modo aggressivo (fino a 7 giorni). Dopo le modifiche, usa il Card Validator per forzare un nuovo scraping.
• Test di ritaglio mobile: Fai uno screenshot della card a proporzioni 1:1 (ritaglia al centro 675x675) per verificare che il ritaglio quadrato comunichi ancora il contenuto della pagina.

11. Competenze correlate

Queste competenze sono opzionali — questa competenza funziona autonomamente. Installale se hai bisogno di funzionalità aggiuntive:

Stesso repo (sempre installate insieme):

• generatore-immagini-og: Generazione immagini OG (1200x630, 1.91:1) — la pipeline di rendering completa, tutti i 6 stili, template di base, guida alla tipografia, vincoli Satori. Questo generatore di Twitter Card riutilizza tutta la sua infrastruttura.

Repo separati (possono essere installati o meno):

• twitter-cards (marketing-skills): Configurazione dei meta tag HTML per twitter:card, twitter:site, twitter:creator, validazione. Gestisce come IMPOSTARE il tag; questa competenza gestisce come CREARE l'immagine.
• open-graph (marketing-skills): Configurazione dei meta tag HTML per og:title, og:image, og:url, strumenti di test per piattaforme
• social-share-generator (marketing-skills): UI del pulsante di condivisione che consuma i dati della Twitter Card quando gli utenti condividono link su X