tuanhuyptit/gwd-banner-animation

GWD 横幅动画

创建一个可编辑的 Google Web Designer 源项目，保留提供的设计并添加动画。 每个请求都是输入和动画模式的组合。

输入	适用场景
A. 分层 GWD 文件夹	用户提供一个 GWD 项目（HTML + assets/ + gwd_workspace.json）
B. Illustrator 画板	用户在 Illustrator 中打开设计（或指向一个 .ai 文件），并希望将其转为 GWD 项目

动画模式	适用场景
模板	用户提供同一系列的样本 GWD 横幅，并希望获得相同的效果（“跟样本效果一样”，该系列的其他尺寸）
自由	没有样本，或用户要求新的/自定义动画（“自己做效果”，“自由发挥效果”）

根据请求选择模式：如果提供了样本，则使用模板模式；否则使用自由模式。相似的品牌、资源、文件夹或尺寸本身绝不意味着模板模式。仅当请求确实模棱两可时才询问。

工具

• 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 舞台与时间线起点匹配。
• 除非被要求，否则不要更改点击链接 URL、广告环境、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，如果存在）并与源作品匹配。