Banner Forge

Happy path (config → deliverables)

1. Verify a banner.config.json exists at the project root. If not, copy banner.config.example.json and ask the user to fill it in.
2. Run node scripts/build.js — templates in templates/gsap/ are filled from config and written per-size to build/<size>/.
3. Run node scripts/render.js — Puppeteer captures the last animation frame as backup.png (sharp-compressed), then a full MP4 via native page.screencast, and a GIF via gifski.
4. Run node scripts/package.js — builds per-network zips in dist/<network>/<size>.zip with the correct manifest (Adform manifest.json, Google index.html at root with clickTag var).
5. Run node scripts/validate.js — checks file size (≤150KB), clickTag presence, required assets, manifest correctness. Writes dist/validation-report.json.
6. Summarize for the user: sizes built, total bytes, any validation failures, and where the zips landed.

All five stages are wrapped by scripts/build-all.sh or npm run all.

Entry points

From a config file (default, no Figma)

User provides or edits banner.config.json. The skill runs the four-stage pipeline. See banner.config.example.json for schema.

From a Figma frame

/banner-from-figma <url> triggers scripts/figma-import.js, which uses the Figma MCP to extract tokens, text styles, and assets into a banner.config.json, then falls through to the default pipeline.

Graceful fallback for free-seat Figma users: write-back requires a paid Figma seat. The skill detects this and degrades to read-only mode, writing the generated config to disk instead of pushing variants back into the Figma file. Log a single warning and continue.

From a brief (no Figma, no config)

/banner-from-brief <path> reads a brief (markdown, text, PDF via future pdf-extract), asks Claude to synthesize brand tokens + copy + sizes + networks into banner.config.json, then falls through to the default pipeline.

Canonical size matrix

See references/SIZES.md for the full table. The 15 MVP sizes:

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

Rules:

• Sizes ≤ 50KB target (300x50, 320x50, 300x600 mobile-first variants) must use the CSS-only template, not GSAP. See references/ANIMATION.md.
• Sizes with a fixed polite-load ceiling (Google 150KB initial / 2.2MB total) are pre-validated in scripts/validate.js.

clickTag pattern

Use the dual global pattern so one zip passes Google, DV360, TTD, and Adform:

<script>
  var clickTag = "https://example.com/landing";
  var clickTAG = clickTag; // TTD + Adform legacy uppercase
</script>

Adform additionally requires a manifest.json at zip root. scripts/package.js handles this per-network.

Full rules: references/CLICKTAG.md.

Animation

• Default: GSAP 3.13+ (free for commercial use including ads as of April 2025). Bundled via npm, inlined into the build.
• ≤50KB sizes: CSS-only template. Zero JS bytes.
• Never: Lottie loaded from lottiefiles.com (CORS rejected by Google Ads). If Lottie is needed, inline the JSON — that template lands in V1.
• Never: Rive runtime, raw Canvas, or WebGL on programmatic display (DSPs reject).

See references/ANIMATION.md for the full decision tree.

Networks supported

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

Per-network differences (manifest, polite-load, retina, clickTag case) are handled in scripts/package.js driven by references/NETWORK_SPECS.md.

Fonts

Bundle only Fontsource families (OFL, Apache, Ubuntu Font License). Self-hosted only — never hit fonts.googleapis.com at runtime (GDPR).

Refuse: Helvetica, Futura, any Adobe Fonts family, any foundry font (Monotype, H&Co, Commercial Type). Substitute Inter / Figtree / Manrope and log a warning.

See references/LEGAL.md for the full font rule.

Images

MVP: user-supplied hero image only.

V1: optional AI generation via Nano Banana (Gemini 2.5 Flash Image) or FLUX.1 schnell (Apache 2.0). Never FLUX.1 dev — non-commercial. See references/IMAGE_MODELS.md. AI output triggers C2PA metadata preservation; stripping it violates platform policy.

Failure modes to watch

1. Puppeteer first-run download — ~170MB Chromium. Warn the user before first npm install.
2. gifski not installed — optionalDependencies in package.json; render.js falls back to ffmpeg-only if missing and logs a quality warning.
3. Config missing clickUrl — refuse to build. clickTag without a URL is useless.
4. Config references a font not in assets/fonts/ — warn and substitute.
5. Hero image missing — build proceeds with a neutral placeholder, validator flags it.
6. Figma MCP write-back fails (free seat) — log warning, write config to disk, continue.
7. Network name typo — package.js lists valid networks and exits.

Progressive disclosure

Everything above is the in-context reference. Deeper material lives in references/ and is loaded only when needed:

• references/SIZES.md — canonical size table, per-network availability, file-size ceilings.
• references/NETWORK_SPECS.md — manifest shapes, polite-load, retina, clickTag case per network.
• references/CLICKTAG.md — the exact dual-global snippet and per-network variations.
• references/ANIMATION.md — GSAP vs CSS vs Lottie decision tree, timing conventions.
• references/IMAGE_MODELS.md — Nano Banana, FLUX, Imagen, licensing, watermark risk.
• references/LEGAL.md — AI disclosure, font licensing, trademark, FTC/DSA/EU AI Act.

Success criteria

A successful run produces, for each size:

• An index.html that stands alone (no external CDN except the clickTag bridge)
• A backup.png under 40KB
• A GIF preview (optional) and MP4 preview (optional)
• A per-network zip under 150KB with manifest + polite-load + dual clickTag
• A validation report entry of pass or pass-with-warnings

Fail loudly. Never ship a banner that the validator flags without telling the user.