tuanhuyptit/gwd-banner-animation

GWD 橫幅動畫

建立可編輯的 Google Web Designer 原始專案，保留提供的設計並加入動畫效果。 每次請求是一個輸入與一種動畫模式的組合。

輸入	使用時機
A. 分層 GWD 資料夾	使用者提供 GWD 專案（HTML + assets/ + gwd_workspace.json）
B. Illustrator 工作區域	使用者在 Illustrator 中開啟設計（或指定 .ai 檔案）並想要轉為 GWD 專案

動畫模式	使用時機
範本	使用者提供同一組的 GWD 橫幅範本，希望重現相同的效果（「giống hiệu ứng mẫu」，同一系列的其他尺寸）
自由	沒有範本，或使用者要求全新/自訂動畫（「tự làm hiệu ứng」、「hiệu ứng tùy ý」）

請根據請求選擇模式：若提供範本則為範本模式；否則為自由模式。相似的品牌、素材、資料夾或單獨尺寸不應視為範本模式。僅在請求確實不明確時提問。

工具

• scripts/inspect_gwd_banner.py <project>：檢查畫布、圖層、來源、類別。
• scripts/prepare_layers.py、scripts/derive_light_layers.py：處理 Illustrator 匯出檔 → 修剪後的 2x 素材 + layout.json（references/illustrator-export.md）。
• scripts/extract_gwd_motion.py <project> -o spec.json：GWD 專案 → 規格檔。
• scripts/adapt_template_motion.py：範本規格 + 新版面 → 新尺寸的規格檔（references/template-mode.md）。
• scripts/build_gwd_project.py spec.json <out>/<Name>：規格檔 → 可編輯的 GWD 專案（執行時期來自 assets/gwd-runtime，進階模式工作區）。規格格式：請參考 references/spec-format.md。
• scripts/apply_half_scale.py <project>：2x 圖片 → 原始尺寸元素，縮放比例設為 0.5（請參閱 GWD 規則）。
• scripts/validate_gwd_banner.py <project>、scripts/package_gwd_banner.py <project> [zip]。

Python 腳本需安裝 Pillow 與 numpy（python3 -m pip install --user pillow numpy）。

工作流程

1. 保護來源。 將提供的 GWD 資料夾與範本視為唯讀；在可寫入的輸出資料夾中進行工作。在 Illustrator 中，切勿修改使用者的作品：複製到暫時的 GWD_* 圖層，並在完成後刪除。
2. 取得圖層。
   • 輸入 A：複製專案，執行 inspect_gwd_banner.py，根據意義對應圖層（背景、標籤、標題、輔助文案、優惠、CTA、插圖、產品、光暈、強調線條……），並進行視覺確認。
   • 輸入 B：依照 references/illustrator-export.md 操作：將每個圖層以2x解析度、透明背景匯出為完整工作區域，然後執行 prepare_layers.py 與 derive_light_layers.py（處理依賴混合模式的光暈圖層）。匯出完工作品的 _ref2x.png。
3. 動畫。
   • 範本模式：參考 references/template-mode.md：擷取範本動畫，調整至新版面，審閱規格。保持範本的序列、時間、淡入曲線與循環不變。
   • 自由模式：閱讀 references/motion-design-guide.md。在撰寫關鍵影格前，先定義一句話的概念、層級結構、一個招牌動作、入場順序、強調效果與可讀停頓，從此組合中選擇。與上下文中的近期作品比較，若重複先前的招牌動作或序列則重新設計。撰寫規格檔（輸入 B）或直接編輯複製的 HTML（輸入 A），並遵守下列 GWD 規則。
4. 建置。 輸入 B（或任何規格檔）：執行 build_gwd_project.py。輸入 A（原地編輯）：保留其 HTML、素材與執行時期檔案；確保 gwd_workspace.json 包含 "timeline.animationMode":"proMode"。
5. 驗證。 執行 validate_gwd_banner.py；修正所有錯誤。
6. 預覽。 透過 HTTP 提供資料夾服務，並在瀏覽器中開啟 HTML。等待 document.getAnimations().length 達到預期數量（若廣告未啟動，請呼叫 document.getElementById('gwd-ad').initAd()；GWD 的禮貌載入在不穩定的本地伺服器上可能錯過 WebComponentsReady）。暫停並搜尋所有動畫以檢查：初始狀態、重要揭露、招牌動作、CTA、後期停頓、循環邊界、最終狀態。對於輸入 B，比對最終影格與 _ref2x.png；在範本模式中，比對相同時間點的階段與範本。隱藏的瀏覽器視窗可能會凍結即時播放，因此應檢查循環事件結構而非等待循環。
7. 交付。 執行 package_gwd_banner.py，並在專案中附上 HUONG-DAN.txt（概念說明或「與範本相同」、時間軸、圖層對應（含混合模式）、手動編輯筆記）以及簡短的驗證摘要。

GWD 規則（所有模式）

• 每個動畫元素需擁有唯一的 gwd-gen-...gwdanimation 類別、對應的唯一 @keyframes ..._gwd-keyframes（或 _gwd-mask-keyframes）規則，並透過 #page1.gwd-play-animation .CLASS { animation: ...; } 套用。
• 每個關鍵影格規則僅使用一個百分比選擇器。切勿將多個選擇器群組，如 0%, 8%：GWD 可能將時間視為非有限值因而拒絕開啟文件。
• 無重複的關鍵影格名稱，無非有限的持續時間或延遲。
• 最後一個關鍵影格需保留元素的完整基礎變形；必要內容不能以隱藏狀態結束。
• 基礎樣式需等於 0% 關鍵影格，使 GWD 舞台與時間軸起點一致。
• 除非被要求，否則請勿更改點擊連結網址、廣告環境、Enabler 整合、文案、圖層順序或廣告活動素材。請勿編輯壓縮後的 GWD 執行時期函式庫。
• 由 derive_light_layers.py 產生的光暈圖層必須使用 mix-blend-mode: screen。
• 2x 圖片：元素保留 PNG 的原始尺寸並縮放為 0.5（GWD 面板：Scale 0.5, 0.5, 0.5），絕不能使用半尺寸盒子再拉伸 2x PNG；後者在本地看起來正確，但在 Google Ads / DV360 預覽中會過大。build_gwd_project.py 會自動處理；對於既有專案（輸入 A），請執行 scripts/apply_half_scale.py <project>（可安全重複執行），並保持規格值為 1x CSS 像素。
• 動畫圖片的每個關鍵影格都必須包含完整的變形（腳本會自動加入）。如果某圖層的關鍵影格僅控制透明度，其縮放比例來自基礎樣式；因此後續在 GWD 舞台上修改 Scale 會導致該值持續到結尾，造成光暈圖層錯位。檢查使用者編輯的專案時，請優先比對每個圖層的最終變形與其預期的 0.5 縮放比例。

輸出預期

• 來源檔案保持不變；暫時的 Illustrator 圖層已移除。
• 輸出為可編輯的 GWD 專案（進階模式），包含 assets/ 資料夾；素材為 2x 解析度。
• 範本模式：動畫效果應可辨識源自範本，距離已根據新版面調整。
• 自由模式：專案擁有自己的概念與招牌效果。
• 最終影格應顯示完整的訊息（若有 CTA 則需呈現）並與素材作品一致。