Was macht banner-forge?

Eine Markenkonfiguration – eine komplette, netzwerkbereite Display-Kampagne. Konfigurationsgesteuert, Figma optional. Jedes Ausgabeformat unter 150 KB, mit clickTag-Brücke und validatorgeprüft.

Wann sollte diese Fähigkeit verwendet werden?

Diese Fähigkeit wird verwendet, wenn der Nutzer bittet:

Banneranzeigen, Display-Anzeigen, IAB-Größen oder HTML5-Banner zu generieren
Ein Creative auf verschiedene Ad-Network-Formate zu skalieren
Google Ads / DV360 / TTD / Adform / Amazon DSP ZIPs zu erstellen
Einen Figma-Frame in produktionsreife Banner umzuwandeln
Ein Banner mit GSAP zu animieren
Ein bestehendes HTML5-Banner auf Netzwerkregeln zu prüfen

Nicht verwenden für: Meta/LinkedIn/TikTok-Newsfeed-statische oder Video-Creatives (Meta lehnt HTML5 ab – leite den Nutzer bei Verfügbarkeit an den V1-statischen/Video-Pfad weiter oder erstelle direkt statische PNG/MP4).

Kernprinzip

Eine Pipeline, dateibasiert, fortsetzbar. Jede Stufe liest JSON-Seitenwagen der vorherigen Stufe und schreibt eigene. Fehler sind auf eine Stufe begrenzt. Nie etwas neu aufbauen, was nicht nötig ist.

banner.config.json
    → scripts/build.js    → build/<groesse>/{index.html, assets/, meta.json}
    → scripts/render.js   → build/<groesse>/{backup.png, preview.gif, preview.mp4}
    → scripts/package.js  → dist/<netzwerk>/<groesse>.zip
    → scripts/validate.js → dist/validation-report.json

Standard-Pfad (Konfiguration → Ergebnisse)

Überprüfe, ob eine banner.config.json im Projektstamm vorhanden ist. Falls nicht, kopiere banner.config.example.json und bitte den Nutzer, sie auszufüllen.
Führe node scripts/build.js aus – Vorlagen in templates/gsap/ werden aus der Konfiguration befüllt und größenabhängig nach build/<groesse>/ geschrieben.
Führe node scripts/render.js aus – Puppeteer erfasst den letzten Animationsframe als backup.png (sharp-komprimiert), ein volles MP4 über natives page.screencast und ein GIF über gifski.
Führe node scripts/package.js aus – erstellt netzwerkbezogene ZIPs in dist/<netzwerk>/<groesse>.zip mit korrektem Manifest (Adform manifest.json, Google index.html im Stammverzeichnis mit clickTag-Variable).
Führe node scripts/validate.js aus – prüft Dateigröße (≤150 KB), clickTag-Präsenz, erforderliche Assets, Manifest-Korrektheit. Schreibt dist/validation-report.json.
Fasse für den Nutzer zusammen: erstellte Größen, Gesamtbytes, etwaige Validierungsfehler und wo die ZIPs abgelegt wurden.

Alle fünf Stufen sind durch scripts/build-all.sh oder npm run all zusammengefasst.

Einstiegspunkte

Aus einer Konfigurationsdatei (Standard, kein Figma)

Der Nutzer stellt banner.config.json bereit oder bearbeitet sie. Die Fähigkeit führt die vierstufige Pipeline aus. Siehe banner.config.example.json für das Schema.

Aus einem Figma-Frame

/banner-from-figma <url> startet scripts/figma-import.js, das über das Figma MCP Tokens, Textstile und Assets in eine banner.config.json extrahiert und dann in die Standard-Pipeline übergeht.

Sanfter Fallback für Nutzer mit kostenlosem Figma-Account: Das Zurückschreiben erfordert einen kostenpflichtigen Figma-Account. Die Fähigkeit erkennt dies und schaltet in den Nur-Lese-Modus, wobei die generierte Konfiguration auf die Festplatte geschrieben wird, anstatt Varianten zurück in die Figma-Datei zu pushen. Eine Warnung wird ausgegeben und fortgesetzt.

Aus einem Briefing (kein Figma, keine Konfiguration)

/banner-from-brief <pfad> liest ein Briefing (Markdown, Text, PDF über zukünftigen pdf-extract), bittet Claude, Markentokens + Text + Größen + Netzwerke in banner.config.json zu synthetisieren und geht dann in die Standard-Pipeline über.

Kanonische Größentabelle

Siehe references/SIZES.md für die vollständige Tabelle. Die 15 MVP-Größen:

300x250, 336x280, 300x600, 728x90, 970x90, 970x250, 160x600, 120x600, 320x50, 320x100, 300x50, 300x1050, 468x60, 250x250, 200x200.

Regeln:

Größen ≤ 50 KB Ziel (300x50, 320x50, 300x600 Mobile-First-Varianten) müssen das reine CSS-Template verwenden, nicht GSAP. Siehe references/ANIMATION.md.
Größen mit einer festen Polite-Load-Obergrenze (Google 150 KB initial / 2,2 MB gesamt) werden in scripts/validate.js vorvalidiert.

clickTag-Muster

Verwende das duale globale Muster, damit ein ZIP bei Google, DV360, TTD und Adform funktioniert:

<script>
  var clickTag = "https://example.com/landing";
  var clickTAG = clickTag; // TTD + Adform Legacy-Großschreibung
</script>

Adform erfordert zusätzlich eine manifest.json im ZIP-Stammverzeichnis. scripts/package.js behandelt dies pro Netzwerk.

Vollständige Regeln: references/CLICKTAG.md.

Animation

Standard: GSAP 3.13+ (frei für kommerzielle Nutzung einschließlich Werbung ab April 2025). Über npm gebündelt, in den Build inlined.
≤50 KB Größen: Nur-CSS-Template. Null JS-Bytes.
Nie: Lottie geladen von lottiefiles.com (CORS von Google Ads abgelehnt). Wenn Lottie benötigt wird, das JSON inlinen – dieses Template landet in V1.
Nie: Rive-Runtime, reines Canvas oder WebGL bei programmatischer Display-Werbung (DSPs lehnen ab).

Siehe references/ANIMATION.md für den vollständigen Entscheidungsbaum.

Unterstützte Netzwerke

MVP: Google Ads, DV360, The Trade Desk, Adform. V1: Amazon DSP (2x Retina).

Netzwerkspezifische Unterschiede (Manifest, Polite-Load, Retina, clickTag-Schreibweise) werden in scripts/package.js behandelt, gesteuert durch references/NETWORK_SPECS.md.

Schriftarten

Nur Fontsource-Familien bündeln (OFL, Apache, Ubuntu Font License). Nur selbst gehostet – niemals zur Laufzeit fonts.googleapis.com aufrufen (DSGVO).

Ablehnen: Helvetica, Futura, alle Adobe-Fonts-Familien, alle Foundry-Schriftarten (Monotype, H&Co, Commercial Type). Ersetze durch Inter / Figtree / Manrope und gib eine Warnung aus.

Siehe references/LEGAL.md für die vollständige Schriftartenregel.

Bilder

MVP: Nur vom Benutzer bereitgestelltes Hero-Bild.

V1: Optionale KI-Generierung über Nano Banana (Gemini 2.5 Flash Image) oder FLUX.1 schnell (Apache 2.0). Niemals FLUX.1 dev – nicht kommerziell. Siehe references/IMAGE_MODELS.md. KI-Ausgabe löst die Beibehaltung der C2PA-Metadaten aus; deren Entfernung verstößt gegen die Plattformrichtlinie.

Fehlermodi, die beachtet werden sollten

Puppeteer-Erstausführung-Download – ~170 MB Chromium. Den Nutzer vor dem ersten npm install warnen.
gifski nicht installiert – optionalDependencies in package.json; render.js fällt auf nur ffmpeg zurück, wenn fehlend, und gibt eine Qualitätswarnung aus.
Konfiguration fehlt clickUrl – Bau verweigert. clickTag ohne URL ist nutzlos.
Konfiguration verweist auf eine Schriftart, die nicht in assets/fonts/ ist – warnen und ersetzen.
Hero-Bild fehlt – Bau wird mit einem neutralen Platzhalter fortgesetzt, der Validierer markiert es.
Figma MPC-Rückschreiben fehlschlägt (kostenloser Account) – Warnung ausgeben, Konfiguration auf Festplatte schreiben, fortfahren.
Netzwerkname Tippfehler – package.js listet gültige Netzwerke auf und beendet sich.

Progressive Offenlegung

Alles oben Genannte ist der In-Kontext-Referenz. Tiefergehendes Material befindet sich in references/ und wird nur bei Bedarf geladen:

references/SIZES.md – kanonische Größentabelle, Verfügbarkeit pro Netzwerk, Dateigrößenobergrenzen.
references/NETWORK_SPECS.md – Manifest-Formen, Polite-Load, Retina, clickTag-Schreibweise pro Netzwerk.
references/CLICKTAG.md – das genaue duale globale Snippet und Variationen pro Netzwerk.
references/ANIMATION.md – Entscheidungsbaum GSAP vs. CSS vs. Lottie, Zeitkonventionen.
references/IMAGE_MODELS.md – Nano Banana, FLUX, Imagen, Lizenzierung, Wasserzeichenrisiko.
references/LEGAL.md – KI-Offenlegung, Schriftartenlizenzierung, Marken, FTC/DSA/EU AI Act.

Erfolgskriterien

Ein erfolgreicher Durchlauf erzeugt für jede Größe:

Eine index.html, die eigenständig ist (kein externes CDN außer der clickTag-Brücke)
Ein backup.png unter 40 KB
Eine GIF-Vorschau (optional) und MP4-Vorschau (optional)
Ein netzwerkspezifisches ZIP unter 150 KB mit Manifest + Polite-Load + dualem clickTag
Einen Validierungsberichtseintrag pass oder pass-with-warnings

Laut scheitern. Nie ein Banner ausliefern, das der Validierer beanstandet, ohne den Nutzer zu informieren.

Joeldkelly/banner-forge

Was ist banner-forge?

In Ihrer bevorzugten KI fragen

Dokumentation