SVG Character Animator

English | 中文

Make SVG characters come alive: smooth morphs between poses and emotions, plus ambient idle motion — breathing, blinking, swaying — and one-click export to a web player or a native SwiftUI view.

This repo contains two things:

1. The skill (SKILL.md) — an Agent Skill that teaches AI coding agents (Claude Code, Cursor, Codex, and any other agent that reads SKILL.md) how to build production-quality SVG character animation. Hand your agent 2–10 SVG states of a character, get back a runnable React state machine.
2. Animator Studio (animator-studio-en.html / animator-studio-cn.html) — a standalone browser editor for previewing and tuning the results: live morph preview, easing curves, idle presets, per-path controls, and three exporters. Double-click to open, no install.

Why a skill for this

Naive SVG morphing looks bad — circles collapse into triangles, stroke caps flatten, colors pop, and the character freezes dead between transitions. Fixing that isn't about picking a better morph library; it's an architecture:

• Per-path strategy detection — most "morphs" are really parts moving or rotating. Paths whose structure matches across states get exact bezier interpolation (perfect quality); only genuinely different shapes go through a morph library.
• Path normalization — equivalent paths written differently are recognized as the same, so more paths get the exact treatment.
• Two-layer motion — transition morphs and idle animation blend instead of fighting.
• Decoration handling — elements that exist in only some states fade in and out gracefully rather than morphing into garbage.

The skill encodes all of this so your agent gets it right the first time.

Quick start

Use the skill with your coding agent

1. Install:
   • Claude Code — clone this repo into your skills directory (e.g. ~/.claude/skills/svg-character-animator/), or install it as a plugin skill.
   • Other agents (Cursor, Codex, Copilot, …) — clone anywhere, then add SKILL.md to your project rules, or just start with "read SKILL.md in <repo path> first, then …".
2. Ask something like:

   "Here are two SVGs of my mascot — happy and sleepy. Make it morph between them when clicked, and have it breathe while idle."

3. The agent builds a runnable React component and iterates with you.

Try Animator Studio

Open animator-studio-en.html (or the Chinese UI, animator-studio-cn.html) in a browser and drop in a *.states.js animation file. Two examples are included:

• examples/critters.states.js — the critters demo · source artwork on Figma Community
• examples/snowman.states.js — a 5-state snowman

Internet is needed on first open (React/Babel load from CDN). The file format is documented in templates/preview/states.example.js.

Exports

All three exporters live in the Studio side panel and capture your current tuning (duration, easing curve, per-path methods, idle preset and anchor):

Repository layout

SKILL.md                  The skill — what the agent reads
references/               Deep-dive docs (strategy detection, idle recipes, iOS porting, …)
templates/                Production React component + browser preview harness
scripts/                  SwiftUI exporter, studio build script, Figma workflow notes
assets/preset-library.json  Easing/idle presets as data
examples/                 Example characters (critters, snowman)
evals/                    Test prompts for benchmarking the skill
animator-studio-en.html   Animator Studio, English UI (build artifact)
animator-studio-cn.html   Animator Studio, Chinese UI (build artifact)
LICENSE                   MIT (code) — see License below

The studio files are build artifacts — don't edit them by hand. Edit templates/preview/* and rebuild:

node scripts/build-standalone.js            # → animator-studio-en.html
node scripts/build-standalone.js --lang cn  # → animator-studio-cn.html

License

Example artwork © molauu, CC BY-NC 4.0; code MIT.

• Code — everything except the example artwork is MIT licensed: use it freely, commercially or not.
• Example artwork — the characters in examples/ (critters and snowman, including their vector artwork) are © molauu, CC BY-NC 4.0: share and adapt with attribution, non-commercial only. They're here as learning examples — animate your own artwork for anything you ship.

中文说明

English | 中文

快速制作SVG角色动画：在不同姿势和表情之间平滑变形，加上呼吸、眨眼、摇摆等待机动画，并可一键导出为网页播放器或原生 SwiftUI 视图。

技能包含两部分：

1. 技能本体（SKILL.md）—— 一个 Agent Skill 技能包，教 AI 编程智能体（Claude Code、Cursor、Codex 等任何能读 SKILL.md 的智能体）做出高质量的 SVG 角色动画。给智能体同一角色的 2–10 个 SVG 状态，它会生成一个可直接运行的 React 状态机组件。
2. Animator Studio 动画工作台（animator-studio-cn.html / animator-studio-en.html）—— 独立的浏览器编辑器，用来预览和调整效果：实时变形预览、缓动曲线、待机动画预设、逐路径控制，以及三种导出。双击即开，无需安装。

为什么需要一个技能包

直接做 SVG 变形效果往往很差：圆形中途塌成三角形、描边端点变扁、颜色突跳、切换间角色僵死。解决这些问题靠的不是换个更好的变形库，而是一套架构：

• 逐路径策略检测 —— 大多数"变形"其实只是部件在移动或旋转。结构一致的路径直接做精确的贝塞尔插值（质量完美），只有形状真正不同的才交给变形库。
• 路径规范化 —— 写法不同但形状相同的路径会被识别为一致，让更多路径走精确插值。
• 双层动画 —— 切换的变形动画和待机动画互相融合，而不是打架。
• 装饰处理 —— 只在部分状态出现的装饰元素优雅地淡入淡出，不会变形成乱码。

技能包把这套架构写成了智能体一次就能做对的知识。

快速开始

配合编程智能体使用

1. 安装：
   • Claude Code —— 克隆本仓库到技能目录（如 ~/.claude/skills/svg-character-animator/），或作为插件技能安装。
   • 其他智能体（Cursor、Codex、Copilot 等）—— 克隆到任意位置，把 SKILL.md 加进项目规则，或直接说："先读 <仓库路径> 里的 SKILL.md，然后……"。
2. 提出请求，比如：

   "这是我的吉祥物的两个 SVG —— 开心和困倦。点击时在两者之间变形，待机时让它呼吸。"

3. 智能体会生成可运行的 React 组件，并和你一起迭代。

试试 Animator Studio

用浏览器打开 animator-studio-cn.html（或英文界面 animator-studio-en.html），拖入一个 *.states.js 动画文件即可。内置两个示例：

• examples/critters.states.js —— 小动物演示 · Figma 社区源文件
• examples/snowman.states.js —— 5 状态雪人

首次打开需要联网（React/Babel 从 CDN 加载）。文件格式见 templates/preview/states.example.js。

导出

三种导出都在工作台右侧面板，并带上你当前的全部调整（时长、缓动曲线、逐路径方式、待机预设与锚点）：

目录结构

SKILL.md                  技能本体 —— 智能体阅读的内容
references/               深入文档（策略检测、待机动画配方、iOS 移植……）
templates/                生产用 React 组件 + 浏览器预览工具
scripts/                  SwiftUI 导出器、工作台构建脚本、Figma 工作流说明
assets/preset-library.json  缓动/待机预设数据
examples/                 示例角色（小动物、雪人）
evals/                    用于评测技能效果的测试题
animator-studio-en.html   Animator Studio 英文界面（构建产物）
animator-studio-cn.html   Animator Studio 中文界面（构建产物）
LICENSE                   MIT（代码）—— 见下方"许可"

工作台文件是构建产物，请勿手改。修改 templates/preview/* 后重新构建：

node scripts/build-standalone.js            # → animator-studio-en.html
node scripts/build-standalone.js --lang cn  # → animator-studio-cn.html

许可

示例美术 © molauu，CC BY-NC 4.0；代码 MIT。

• 代码 —— 除示例美术外的所有内容采用 MIT 协议，可自由使用，包括商用。
• 示例美术 —— examples/ 中的角色（小动物和雪人，含其矢量图形）版权归 molauu 所有，采用 CC BY-NC 4.0：可署名、非商业地分享和改编。它们只是学习示例 —— 正式产品请用你自己的美术素材。