graphic-gif

Generates an animated looping GIF from CSS animations or an AI image-to-video API. Output: animation.gif.

Unlike every other graphic- skill that outputs a static PNG or PDF, this skill outputs an animated .gif. Uses CSS @keyframes animations captured frame-by-frame via Playwright and the Web Animations API (Option A, default), or an AI image-to-video pipeline via Kling (Option B).

Critical Rules (read before every generation)

1. Default is css-animated. Never use ai-generated unless explicitly requested.
2. Canvas is 800×800px square. All clamp() values computed at 800px (1vw = 8px).
3. Single self-contained HTML. All CSS inline in <style>. Font CDN <link> only external dependency.
4. Never dump HTML in chat. Save to file, show summary only.
5. Frame capture uses Web Animations API seeking. NOT setTimeout loops, NOT animation-delay tricks.
6. Exact frame count: Math.floor(duration_seconds * fps) frames. The frame at t=duration_ms MUST NOT be captured — it duplicates t=0 and causes a visible stutter at the loop point.
7. No placeholder boxes. CSS-generated visuals only. No "image goes here" elements.
8. Simpler palettes = smaller files. Use: clean-slate, terminal, electric-burst, brutalist.
9. No animation-delay for stagger. Bake stagger into @keyframes percentages — frame seeking handles timing.
10. Commit to design direction before writing CSS. Tone, signature element, motion style, unforgettable detail — all decided before first line of code.

Step 1: Intake

Required: prompt (content description AND motion brief)

Optional with defaults:

| Parameter | Default | Options | |---|---|---| | animation_type | css-animated | css-animated / ai-generated | | duration | 3.0 | seconds | | fps | 12 | frames per second | | loop | true | true / false | | style | clean-slate | clean-slate / terminal / electric-burst / brutalist | | dimensions | 800x800 | WxH in pixels | | optimization | balanced | quality / balanced / filesize |

If prompt is missing or lacks motion description, ask exactly:

> "What should the GIF show? Describe the content AND the motion (e.g., 'Stats count up: 73% of buyers read 3+ pieces of content before purchase. Typewriter effect, one character at a time. Style: terminal. 3 seconds, 12fps.') > > Key settings (all optional, defaults shown): > - animation_type: css-animated (default) or ai-generated > - duration: 3.0 seconds > - fps: 12 > - loop: true > - style: clean-slate (options: clean-slate / terminal / electric-burst / brutalist) > - dimensions: 800x800 > - optimization: balanced (options: quality / balanced / filesize)"

If all required info is present → skip directly to Step 2.

Step 2: Internal Architecture (never shown to user)

For css-animated:

1. Choose animation type from: fade-in, slide-in, typewriter, counter, pulse, loop-scroll
2. Read references/animation-library.md — find the chosen type's full HTML/CSS spec
3. Read references/style-presets.md — load the chosen style's CSS token block
4. Calculate frame count: Math.floor(duration_seconds * fps) — write this number down
5. Commit to design direction:

| Decision | Derive from | |---|---| | Tone | Emotional register for audience (mechanical / warm / electric / professional) | | Signature element | ONE visual device used consistently (cursor blink, ghost number, scan-line overlay, accent border) | | Motion style | Ease curve philosophy for this type (spring / linear / step / ease-in-out) | | Unforgettable detail | The ONE thing a viewer will remember about this GIF |

For ai-generated:

1. Generate base still frame HTML (poster-style layout for the canvas)
2. Export as PNG using screenshot
3. Call Kling API: POST https://api.klingai.com/v1/videos/image2video with image_url and prompt describing the motion
4. Poll for job completion
5. Download video → convert to GIF with ffmpeg:

bash # Two-pass palette for best color quality ffmpeg -i input.mp4 -vf "fps=12,scale=800:800:flags=lanczos,palettegen=stats_mode=diff" palette.png ffmpeg -i input.mp4 -i palette.png -vf "fps=12,scale=800:800:flags=lanczos,paletteuse=dither=bayer:bayer_scale=5" output.gif

Step 3: HTML Generation (css-animated path)

Read references/animation-library.md and references/style-presets.md before generating.

Canvas base — required on every GIF:

css
*, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }

body {
  width: 800px;
  height: 800px;
  overflow: hidden;
  background: var(--bg);
  font-family: var(--font-body);
}

.canvas {
  width: 800px;
  height: 800px;
  position: relative;
  overflow: hidden;
  display: flex;
  align-items: center;
  justify-content: center;
}

Animation rules:

• animation-fill-mode: forwards (or both) on ALL animated elements
• Timing functions per type:
• typewriter → steps(N, end) where N = exact character count
• counter → linear
• fade-in → cubic-bezier(0.22, 1, 0.36, 1) (ease-out)
• slide-in → cubic-bezier(0.34, 1.56, 0.64, 1) (spring overshoot)
• pulse → ease-in-out with animation-iteration-count: infinite
• loop-scroll → linear with animation-iteration-count: infinite
• For one-shot animations (fade-in, slide-in, typewriter, counter): animation-iteration-count: 1 — looping happens at GIF level
• No animation-delay — stagger is baked into @keyframes percentages

Typewriter N calculation: Count every character including spaces, punctuation, numbers:

• "73% of buyers" = 14 characters → steps(14, end)
• "Hello, World!" = 13 characters → steps(13, end)

Counter CSS @property (required for counter type):

css
@property --num {
  syntax: '<integer>';
  inherits: false;
  initial-value: 0;
}
.counter {
  animation: countUp var(--duration) linear forwards;
  counter-reset: num var(--num);
}
.counter::after { content: counter(num); }
@keyframes countUp {
  from { --num: 0; }
  to   { --num: var(--target); }
}

Loop-scroll: content MUST be duplicated:

html
<!-- 4 original items + 4 duplicate items -->
<div class="ticker-track" style="--item-count: 4;">
  [item1][item2][item3][item4][item1][item2][item3][item4]
</div>

translateX(0 → -50%) with linear infinite.

Design quality rules (from commit in Step 2):

• Named signature element MUST be present in CSS/HTML (not just described)
• Typography: weight contrast minimum 2:1 (e.g., 700 vs 400) between display and supporting text
• Background: no pure white #fff for dark styles — use the preset's exact --bg value
• For terminal style: add scan-line overlay ::after with repeating-linear-gradient at opacity: 0.03
• For brutalist: thick border 4px solid #000 or 4px solid var(--accent) on key element
• Unforgettable detail: if it requires an extra element — add it now

Step 4: Self-QA (fix every failure before Step 5)

Canvas:

• ] body and .canvas exactly 800×800px (or specified dimensions)
• ] overflow: hidden on both body and .canvas
• ] No elements overflowing the canvas boundary

Animations:

• ] NO animation-delay anywhere — stagger is in @keyframes percentages
• ] All animations start at t=0 (Web Animations API will seek from there)
• ] animation-fill-mode: forwards or both on all animated elements
• ] One-shot animations: animation-iteration-count: 1
• ] Infinite animations (pulse, loop-scroll): animation-iteration-count: infinite

Type-specific checks:

• ] Typewriter: N in steps(N, end) = exact character count of text string
• ] Counter: @property --num declared with syntax: '<integer>' and initial-value: 0
• ] Counter: counter-reset: num var(--num) and ::after { content: counter(num) }
• ] Loop-scroll: content duplicated exactly once in HTML

Design:

• ] No placeholder boxes
• ] Style preset tokens applied from references/style-presets.md — no free-floating hex colors
• ] Signature element named in Step 2 is actually present in the HTML/CSS
• ] Unforgettable detail from Step 2 is actually implemented
• ] Font CDN <link> present for chosen style's font

Step 5: Export

Determine slug from prompt (kebab-case, ≤30 chars). Create output directory:

bash
mkdir -p [slug]

Save HTML:

[slug]/animation.html

Open in browser for quick visual check:

bash
open [slug]/animation.html

Run export script (replace [skill-root] with the actual path to this skill):

bash
bash [skill-root]/scripts/export-gif.sh \
  [slug]/animation.html \
  [slug]/animation.gif \
  --duration [duration] \
  --fps [fps] \
  [--no-loop if loop=false] \
  --optimization [optimization] \
  --width [W] \
  --height [H]

The script:

1. Installs gifenc, sharp (or jimp), and playwright in a temp directory
2. Downloads Chromium if not cached
3. Runs capture-and-encode.mjs — pauses animations, seeks each frame, screenshots, assembles GIF
4. Runs gifsicle optimization pass if available
5. Reports file size and opens result

If export script not found at [skill-root]/scripts/export-gif.sh, check that the skill was installed with its scripts/ folder intact.

Step 6: Output Summary

Show after successful export:

## GIF: [1-line description]
Date: [YYYY-MM-DD] | Style: [style] | Animation: [type] | [duration]s @ [fps]fps
Dimensions: [WxH] | Frames: [N] | Loop: [true/false]

Files
  Source:   [slug]/animation.html
  Output:   [slug]/animation.gif
  Size:     [X] KB

Checklist
- [ ] Preview loops cleanly at start/end point (no stutter)
- [ ] Text legible at intended display size
- [ ] File size appropriate: email <500KB / social <3MB

AI-Generated Path (Option B)

Only use when animation_type: ai-generated is explicitly specified.

Requirements:

• Kling API key in environment: KLING_API_KEY (66 free credits/day, no credit card for free tier)
• ffmpeg installed locally for video→GIF conversion

Workflow:

1. Generate a base still frame HTML matching the prompt (poster/graphic style at specified dimensions)
2. Export still frame as PNG:

bash # Quick screenshot via Playwright node -e " const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch(); const page = await browser.newPage({ viewport: { width: W, height: H } }); await page.goto('file://[slug]/animation.html'); await page.screenshot({ path: '[slug]/base-frame.png' }); await browser.close(); })(); "

1. Upload to Kling image-to-video endpoint
2. Convert result to GIF with ffmpeg two-pass palette
3. Apply gifsicle optimization

When Kling is unavailable: Fall back to css-animated with a note to the user: "AI generation requires a Kling API key (KLING_API_KEY). Falling back to css-animated. Set the key to enable AI generation."

Prompt Tips (show when user asks for guidance)

> "Describe motion, not just content. 'Stats count up one by one' beats 'show stats'." > > "Keep it simple for file size. 1–3 animated elements and a solid background." > > "Think in loops. The animation should flow invisibly from end back to start." > > "Specify the animation type explicitly. typewriter and counter are the most effective for social." > > ✅ Good: "Create an animated GIF, css-animated, typewriter effect. Text: '73% of B2B buyers read 3+ pieces of content before contacting sales.' Each character types out one at a time. Style: terminal. 3 seconds, 12fps, loop=true." > > ❌ Bad: "make an animated gif of marketing tips"