banner-forge

banner-forge은(는) 무엇을 하나요?

하나의 브랜드 설정으로 완전한 네트워크 지원 디스플레이 캠페인을 생성합니다. 설정 우선, Figma는 선택 사항입니다. 모든 결과물은 150KB 미만, clickTag 연결, 검증기 통과를 보장합니다.

호출 시점

사용자가 다음을 요청할 때 이 스킬을 사용하세요:

• 배너 광고, 디스플레이 광고, IAB 크기, HTML5 배너 생성
• 광고 네트워크 사양에 맞춰 크리에이티브 크기 조정
• Google Ads / DV360 / TTD / Adform / Amazon DSP ZIP 생성
• Figma 프레임을 프로덕션 배너로 변환
• GSAP으로 배너 애니메이션
• 기존 HTML5 배너를 네트워크 규칙에 맞게 검증

다음 경우에는 호출하지 마세요: Meta/LinkedIn/TikTok 뉴스피드 정적 또는 동영상 크리에이티브 (Meta는 HTML5를 거부합니다. 사용 가능한 경우 V1 정적/동영상 경로로 안내하거나 정적 PNG/MP4를 직접 생성하세요).

핵심 원칙

하나의 파이프라인, 파일 기반, 재개 가능. 각 단계는 이전 단계의 JSON 사이드카 파일을 읽고 자체 작성합니다. 실패는 한 단계로 제한됩니다. 이미 완료된 작업을 다시 빌드하지 않습니다.

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

일반 경로 (설정 → 결과물)

1. 프로젝트 루트에 banner.config.json이 있는지 확인합니다. 없으면 banner.config.example.json을 복사하고 사용자에게 작성하도록 요청합니다.
2. node scripts/build.js 실행 — templates/gsap/의 템플릿이 설정으로 채워지고 크기별로 build/<크기>/에 기록됩니다.
3. node scripts/render.js 실행 — Puppeteer가 마지막 애니메이션 프레임을 backup.png(sharp 압축)로 캡처한 다음, 기본 page.screencast를 통해 전체 MP4, gifski를 통해 GIF를 생성합니다.
4. node scripts/package.js 실행 — dist/<네트워크>/<크기>.zip에 올바른 매니페스트(Adform manifest.json, Google index.html 루트에 clickTag 변수 포함)로 네트워크별 ZIP을 빌드합니다.
5. node scripts/validate.js 실행 — 파일 크기(≤150KB), clickTag 존재 여부, 필수 에셋, 매니페스트 정확성을 검사합니다. dist/validation-report.json을 작성합니다.
6. 사용자에게 요약: 빌드된 크기, 총 바이트 수, 검증 실패 항목, ZIP 파일 위치.

다섯 단계 모두 scripts/build-all.sh 또는 npm run all로 실행됩니다.

진입점

설정 파일에서 (기본, Figma 없음)

사용자가 banner.config.json을 제공하거나 편집합니다. 스킬이 4단계 파이프라인을 실행합니다. 스키마는 banner.config.example.json을 참조하세요.

Figma 프레임에서

/banner-from-figma <url>은 scripts/figma-import.js를 트리거하여 Figma MCP를 사용해 토큰, 텍스트 스타일, 에셋을 추출하여 banner.config.json으로 만든 후 기본 파이프라인으로 이어집니다.

무료 Figma 사용자를 위한 정상적인 대체: 쓰기-백에는 유료 Figma 시트가 필요합니다. 스킬이 이를 감지하고 읽기 전용 모드로 전환하여 변형을 Figma 파일에 다시 푸시하는 대신 생성된 설정을 디스크에 저장합니다. 경고 한 번을 기록하고 계속 진행합니다.

브리프에서 (Figma, 설정 없음)

/banner-from-brief <경로>는 브리프(마크다운, 텍스트, 향후 PDF 추출을 통한 PDF)를 읽고, Claude가 브랜드 토큰 + 카피 + 크기 + 네트워크를 종합하여 banner.config.json으로 만든 후 기본 파이프라인으로 이어집니다.

표준 크기 매트릭스

전체 테이블은 references/SIZES.md를 참조하세요. MVP 15개 크기:

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

규칙:

• 50KB 이하 대상 크기(300x50, 320x50, 300x600 모바일 우선 변형)는 GSAP이 아닌 CSS 전용 템플릿을 사용해야 합니다. references/ANIMATION.md 참조.
• 고정 폴라이트 로드 상한(Google 150KB 초기 / 2.2MB 전체)이 있는 크기는 scripts/validate.js에서 사전 검증됩니다.

clickTag 패턴

하나의 ZIP이 Google, DV360, TTD, Adform을 모두 통과할 수 있도록 이중 전역 패턴을 사용하세요:

<script>
  var clickTag = "https://example.com/landing";
  var clickTAG = clickTag; // TTD + Adform 레거시 대문자
</script>

Adform은 추가로 ZIP 루트에 manifest.json이 필요합니다. scripts/package.js가 네트워크별로 처리합니다.

전체 규칙: references/CLICKTAG.md.

애니메이션

• 기본: GSAP 3.13+ (2025년 4월 기준 광고 포함 상업적 이용 무료). npm을 통해 번들링되어 빌드에 인라인 처리됩니다.
• ≤50KB 크기: CSS 전용 템플릿. JS 바이트 제로.
• 절대 사용 금지: lottiefiles.com에서 로드된 Lottie (Google Ads에서 CORS 거부). Lottie가 필요하면 JSON을 인라인 처리하세요. 해당 템플릿은 V1에 포함됩니다.
• 절대 사용 금지: Rive 런타임, 원시 Canvas, 프로그래매틱 디스플레이용 WebGL (DSP에서 거부).

전체 결정 트리는 references/ANIMATION.md를 참조하세요.

지원 네트워크

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

네트워크별 차이점(매니페스트, 폴라이트 로드, 레티나, clickTag 대소문자)은 references/NETWORK_SPECS.md를 기반으로 scripts/package.js에서 처리됩니다.

폰트

Fontsource 패밀리(OFL, Apache, Ubuntu Font License)만 번들링합니다. 자체 호스팅만 — 런타임에 절대 fonts.googleapis.com을 호출하지 마세요 (GDPR).

거부: Helvetica, Futura, 모든 Adobe Fonts 패밀리, 모든 파운드리 폰트(Monotype, H&Co, Commercial Type). Inter / Figtree / Manrope로 대체하고 경고를 기록합니다.

전체 폰트 규칙은 references/LEGAL.md를 참조하세요.

이미지

MVP: 사용자 제공 히어로 이미지만.

V1: Nano Banana (Gemini 2.5 Flash Image) 또는 FLUX.1 schnell (Apache 2.0)을 통한 선택적 AI 생성. 절대 FLUX.1 dev — 비상업적. references/IMAGE_MODELS.md 참조. AI 출력은 C2PA 메타데이터 보존을 트리거합니다. 이를 제거하면 플랫폼 정책을 위반합니다.

주의해야 할 실패 모드

1. Puppeteer 첫 실행 다운로드 — ~170MB Chromium. 첫 번째 npm install 전에 사용자에게 경고합니다.
2. gifski 미설치 — package.json의 optionalDependencies에 있음. render.js는 누락된 경우 ffmpeg만 사용하고 품질 경고를 기록합니다.
3. 설정에 clickUrl 누락 — 빌드 거부. URL 없는 clickTag는 무용지물입니다.
4. 설정이 assets/fonts/에 없는 폰트 참조 — 경고 후 대체.
5. 히어로 이미지 누락 — 중립적인 플레이스홀더로 빌드 진행, 검증기가 플래그 표시.
6. Figma MCP 쓰기-백 실패 (무료 시트) — 경고 기록, 설정을 디스크에 저장하고 계속.
7. 네트워크 이름 오타 — package.js가 유효한 네트워크 목록을 표시하고 종료.

단계적 공개

위 내용은 컨텍스트 내 참조입니다. 더 깊은 내용은 references/에 있으며 필요할 때만 로드됩니다:

• references/SIZES.md — 표준 크기 테이블, 네트워크별 가용성, 파일 크기 상한.
• references/NETWORK_SPECS.md — 네트워크별 매니페스트 형태, 폴라이트 로드, 레티나, clickTag 대소문자.
• references/CLICKTAG.md — 정확한 이중 전역 스니펫 및 네트워크별 변형.
• references/ANIMATION.md — GSAP vs CSS vs Lottie 결정 트리, 타이밍 규칙.
• references/IMAGE_MODELS.md — Nano Banana, FLUX, Imagen, 라이선스, 워터마크 위험.
• references/LEGAL.md — AI 공개, 폰트 라이선스, 상표, FTC/DSA/EU AI Act.

성공 기준

성공적인 실행은 각 크기에 대해 다음을 생성합니다:

• 독립적인 index.html (clickTag 브리지를 제외한 외부 CDN 없음)
• 40KB 미만의 backup.png
• GIF 미리보기 (선택 사항) 및 MP4 미리보기 (선택 사항)
• 매니페스트 + 폴라이트 로드 + 이중 clickTag가 포함된 150KB 미만의 네트워크별 ZIP
• pass 또는 pass-with-warnings의 검증 보고서 항목

실패 시 명확히 알리세요. 검증기가 플래그를 표시한 배너를 사용자에게 알리지 않고 절대 출시하지 마세요.