tuanhuyptit/gwd-banner-animation

GWD Banner Animation

Create an editable Google Web Designer source project that preserves the supplied design and adds motion. Every request is a combination of one input and one motion mode.

Input	When
A. Layered GWD folder	User supplies a GWD project (HTML + assets/ + gwd_workspace.json)
B. Illustrator artboard	User has the design open in Illustrator (or points to an .ai) and wants a GWD project

Motion mode	When
Template	User supplies a sample GWD banner of the same set and wants the same effect ("giống hiệu ứng mẫu", another size of the set)
Free	No sample, or the user asks for new/custom motion ("tự làm hiệu ứng", "hiệu ứng tùy ý")

Pick the mode from the request: a supplied sample means template mode; otherwise free mode. Similar branding, assets, folder or size alone never imply template mode. Ask only if the request is truly ambiguous.

Tools

• scripts/inspect_gwd_banner.py <project>: inventory canvas, layers, sources, classes.
• scripts/prepare_layers.py, scripts/derive_light_layers.py: Illustrator exports → trimmed 2x assets + layout.json (references/illustrator-export.md).
• scripts/extract_gwd_motion.py <project> -o spec.json: GWD project → spec.
• scripts/adapt_template_motion.py: template spec + new layout → spec for the new size (references/template-mode.md).
• scripts/build_gwd_project.py spec.json <out>/<Name>: spec → editable GWD project (runtime from assets/gwd-runtime, Advanced mode workspace). Spec format: references/spec-format.md.
• scripts/apply_half_scale.py <project>: 2x images → natural-size elements at scale 0.5 (see GWD rules).
• scripts/validate_gwd_banner.py <project>, scripts/package_gwd_banner.py <project> [zip].

Python scripts need Pillow and numpy (python3 -m pip install --user pillow numpy).

Workflow

1. Protect sources. Treat supplied GWD folders and samples as read-only; work in a writable output folder. In Illustrator, never modify the user's artwork: duplicate into temporary GWD_* layers and delete them afterwards.
2. Get layers.
   • Input A: copy the project, run inspect_gwd_banner.py, map layers by meaning (background, label, headline, supporting copy, offer, CTA, illustration, product, glow, accent lines…), verify visually.
   • Input B: follow references/illustrator-export.md: export every layer as a full artboard at 2x with a transparent background, then prepare_layers.py, and derive_light_layers.py for glows that depend on blend modes. Export _ref2x.png of the finished artwork.
3. Motion.
   • Template mode: references/template-mode.md: extract the sample, adapt it to the new layout, review the spec. Keep the sample's sequence, timing, easing and loop unchanged.
   • Free mode: read references/motion-design-guide.md. Before writing keyframes define a one-sentence concept, hierarchy, one signature motion, entrance sequence, emphasis and readable hold, chosen from this composition. Compare with recent work in context and redesign if it repeats a previous signature motion or sequence. Write the spec (Input B) or edit the copied HTML (Input A) following the GWD rules below.
4. Build. Input B (or any spec): build_gwd_project.py. Input A edited in place: keep its HTML, assets and runtime files; ensure gwd_workspace.json has "timeline.animationMode":"proMode".
5. Validate. validate_gwd_banner.py; fix all errors.
6. Preview. Serve the folder over HTTP and open the HTML in a browser. Wait for document.getAnimations().length to reach the expected count (if the ad does not start, call document.getElementById('gwd-ad').initAd(); GWD's polite load can miss WebComponentsReady on a flaky local server). Pause and seek all animations to check: initial state, important reveals, signature motion, CTA, late hold, loop boundary, final state. For Input B compare the final frame with _ref2x.png; in template mode compare phases with the sample at the same times. A hidden browser pane may freeze real-time playback, so check the loop event structure rather than waiting for it.
7. Deliver. package_gwd_banner.py, plus HUONG-DAN.txt in the project (concept or "same as sample", timeline, layer mapping with blend modes, manual editing notes) and a short validation summary.

GWD rules (all modes)

• Each animated element has a unique gwd-gen-...gwdanimation class, a matching unique @keyframes ..._gwd-keyframes (or _gwd-mask-keyframes) rule, applied via #page1.gwd-play-animation .CLASS { animation: ...; }.
• One percentage selector per keyframe rule. Never group selectors such as 0%, 8%: GWD may treat the timing as non-finite and refuse to open the document.
• No duplicate keyframe names, no non-finite durations or delays.
• The final keyframe preserves the element's complete base transform; required content never ends hidden.
• Base styles equal the 0% keyframe so GWD's stage matches the timeline start.
• Do not change click-through URLs, ad environment, Enabler integration, copy, layer order or campaign assets unless asked. Do not edit minified GWD runtime libraries.
• Light layers produced by derive_light_layers.py must use mix-blend-mode: screen.
• 2x images: the element keeps the PNG's natural size and is scaled 0.5 (GWD panel: Scale 0.5, 0.5, 0.5), never a half-size box with the 2x PNG stretched into it; that renders correctly locally but too large in the Google Ads / DV360 preview. build_gwd_project.py does this automatically; for an existing project (Input A) run scripts/apply_half_scale.py <project> (safe to re-run) and keep spec values in 1x CSS px.
• Every keyframe of an animated image carries the full transform (the script adds it). A layer whose keyframes hold only opacity takes its scale from the base style, so a later Scale change on the GWD stage sticks to the end and misaligns light layers. When checking a user-edited project, compare each layer's final transform with its intended 0.5 scale before anything else.

Output expectations

• Sources remain unchanged; temporary Illustrator layers are removed.
• The output opens as an editable GWD project (Advanced mode) with its assets/ folder; assets are 2x.
• Template mode: the motion is recognisably the sample's, with distances adapted to the new composition.
• Free mode: the project has its own concept and signature effect.
• The final frame shows the complete message (and CTA if present) and matches the source artwork.