# motion-ref

Adopt this skill: https://proskills.md/skills/other/joepui-motion-ref-skill

Page: https://proskills.md/skills/other/joepui-motion-ref-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 4525
upstream: https://github.com/joepui/motion-ref-skill/blob/HEAD/SKILL.md

```text
---
name: motion-ref
description: "UI 动效参考库，帮你给产品加上合适的动画。不需要懂动效 — 描述你的产品场景（页面加载慢、用户点了没反应、想让页面高级一点），直接推荐方案 + 代码。触发词：页面没动画、交互没反馈、怎么加动效、让页面动起来、加载太慢怎么办、想让产品高级一点、motion ref。"
---

# Motion Ref

把用户的产品场景翻译成合适的 UI 动效方案。默认用户不懂动画术语；先理解问题，再读取最小必要参考，最后给出可直接落地的方案。

## 核心原则

1. **有目的**：每个动画都要解决问题，例如确认操作、缓解等待、表达层级、引导注意。
2. **快且轻**：常规交互控制在 200-500ms；超过 500ms 容易显得卡，低于 100ms 用户难感知。
3. **一致性**：同类交互使用同一套时长、缓动和反馈强度。
4. **无障碍**：代码方案必须包含 `prefers-reduced-motion: reduce` 适配。

## 工作流程

1. 判断用户是在要 **代码方案** 还是 **视频 motion prompt**；不明确时默认代码方案。
2. 判断场景是否清晰：
   - 清晰：读取最相关的场景路由或分类参考，直接推荐 1-3 个动效。
   - 模糊：先给 2-3 个方向让用户选，不要一次读取全部参考。
   - 组合需求：按涉及的 UI 部件分别读取对应分类参考。
3. 只读取当前任务需要的文件。禁止为了保险读取全部 `ref/` 或全部 `references/`。
4. 输出时使用产品语言说明“解决什么问题”，再给实现代码或视频提示词。

## 按需读取导航

### 先读哪个 reference

| 用户需求 | 读取文件 | 读取条件 |
| --- | --- | --- |
| 用户用产品问题描述需求，例如“加载白屏”“点了没反应”“想高级一点” | `references/scene-routing.md` | 需要从场景匹配动效，或需要把模糊描述转成候选方向 |
| 用户要求最终方案、代码、可调参数、视频 prompt | `references/output-format.md` | 已经选定动效，或准备输出最终答案 |

### 再读哪个分类 ref

读取 `references/scene-routing.md` 后，根据匹配结果只打开相关分类文件。若用户已经明确说出分类或动效，也可直接读取对应分类文件。

| 分类 | 读取文件 | 读取条件 |
| --- | --- | --- |
| 加载、等待、白屏、进度、聊天输入中、语音识别 | `ref/01-loading.md` | 等待状态或加载反馈 |
| 按钮点击、提交中、成功、失败、长按确认、复制成功 | `ref/02-button-feedback.md` | 操作反馈发生在按钮或点击动作上 |
| 数字、文字、倒计时、标题、滚动字幕、光泽文字 | `ref/03-text-data.md` | 文本或数据本身需要动态变化 |
| 弹窗、Toast、Tooltip、Popover、抽屉、命令面板 | `ref/04-overlay.md` | 独立浮层或提示层进入/离开 |
| 页面跳转、Tab、侧栏、共享元素、底部导航 | `ref/05-navigation.md` | 页面、视图或导航状态切换 |
| 输入框、表单校验、开关、单选、验证码、滑块、步骤 | `ref/06-form-input.md` | 表单控件或输入流程 |
| 滚动出现、阅读进度、吸顶缩小、图片揭示 | `ref/07-scroll.md` | 动效由滚动触发或跟随滚动 |
| 图标、Logo、角标、点赞、铃铛、复制图标 | `ref/08-icon.md` | 小图标或标识发生状态变化 |
| 轮播、列表增删、拖拽排序、手风琴、头像堆叠、滑动操作 | `ref/09-carousel-list.md` | 列表或集合项交互 |
| 主题、空状态、在线状态、收藏、已读未读、成功失败状态 | `ref/10-state.md` | 全局或组件状态变化 |
| 背景、高级感、发光、粒子、磁性光标、扫描线、3D 悬浮 | `ref/11-ambient.md` | 氛围、品牌感或背景质感 |
| 图表、仪表盘、统计卡片、折线、环形图、排名、时间线、散点、分布、占比、雷达图 | `ref/12-data-viz.md` | 数据可视化入场、趋势对比、分布展示或数值强调 |
| 淡入、上滑、缩放、弹性、序列、模糊、折叠展开 | `ref/13-enter-exit.md` | 通用元素出现、消失或列表入场 |

## 输出要求

输出最终方案前，必须读取：

1. 至少一个相关 `ref/*.md` 分类文件。
2. `references/output-format.md`。

从 `ref/*.md` 中提取视觉描述、适用场景、时长/参数、实现要点。不要凭记忆补动画参数。若多个动效组合跨分类，只读取涉及到的分类文件。
```

## File: README.md
upstream: https://github.com/joepui/motion-ref-skill/blob/HEAD/README.md

````text
<h1 align="center">motion-ref-skill</h1>

<p align="center">
  <strong>Add motion to your product — no design background needed.</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Agent-Skill-111111?style=flat-square" alt="Agent Skill">
  <img src="https://img.shields.io/badge/Claude%20Code-Supported-f59e0b?style=flat-square" alt="Claude Code">
  <img src="https://img.shields.io/badge/Codex-Supported-10a37f?style=flat-square" alt="Codex">
  <img src="https://img.shields.io/badge/OpenClaw-Supported-3b82f6?style=flat-square" alt="OpenClaw">
</p>

<p align="center">
  <a href="#install">Install</a> •
  <a href="#usage">Usage</a> •
  <a href="#categories">Categories</a> •
  <a href="https://joepui.github.io/motion-ref-skill/">Live Preview</a> •
  <a href="README_zh.md">中文文档</a>
</p>

---

AI agent skill for UI motion design. 119 production-ready effects across 13 categories — describe your product scenario, get implementation guidance you can ship. No motion design knowledge required.

Works with Claude Code, Codex, OpenClaw, and any SKILL.md-compatible agent.

## Install

```bash
npx skills add https://github.com/joepUI/motion-ref-skill
```

Or install manually:

```bash
git clone https://github.com/joepUI/motion-ref-skill.git ~/.claude/skills/motion-ref-skill
```

Restart your agent after installing.

## Usage

Describe your product scenario. The skill recommends the right animation and gives you production-ready code.

### Enrich your whole site

```
/motion-ref My website feels static and lifeless.
            Help me add animations to make it feel polished.
```

The skill will analyze your pages and suggest a combination of effects: scroll reveals for content sections, stagger animations for card grids, hover feedback for buttons, smooth page transitions, etc.

### Fix a specific problem

```
/motion-ref Users click the submit button and nothing happens for 3 seconds.
            They keep clicking because there's no feedback.
```

```
/motion-ref The page loads with a white flash before content appears.
            It looks broken.
```

### Add polish to a feature

```
/motion-ref I have a pricing toggle between Monthly and Annual.
            The prices should animate when switching, not just swap.
```

```
/motion-ref My landing page needs to feel premium.
            Something subtle on the hero section.
```

### Get recommendations

```
/motion-ref What animations would work well for a SaaS dashboard?
```

```
/motion-ref I'm building a mobile chat app.
            What motion effects should I consider?
```

## Categories

| # | Category | Count | Highlights |
|---|----------|-------|------------|
| 1 | Loading & Waiting | 14 | Spinner, Skeleton Shimmer, Wave Bars, Typing Indicator, Rose Curve, Lemniscate |
| 2 | Button & Click Feedback | 9 | Press Scale, Ripple, Success Check, Error Shake, Confetti |
| 3 | Text & Data | 10 | Typewriter, Number Counter, Flip Counter, Shimmer Text, Gradient Text |
| 4 | Overlay & Popup | 10 | Modal, Bottom Sheet, Toast, Tooltip, Drawer, Command Palette |
| 5 | Navigation & Transition | 7 | Page Slide, Shared Element, Tab Slide, Dock Nav |
| 6 | Form & Input | 10 | Focus Ring, Label Float, Toggle Switch, OTP Input, Range Slider, Step Indicator |
| 7 | Scroll-driven | 5 | Scroll Reveal, Progress Indicator, Scroll Text Reveal |
| 8 | Icon & Badge | 10 | Hamburger/Close, SVG Draw, Badge Bounce, Heart Like, Bell Shake, Copy Check |
| 9 | Carousel & List | 8 | Carousel, Card Stack, Drag Reorder, Accordion, Avatar Stack, Swipe Action |
| 10 | State Change | 7 | Theme Toggle, Error Recovery, Online Status, Favorite Star, Read/Unread |
| 11 | Atmosphere & Background | 8 | Gradient Flow, Particles, Magnetic Cursor, 3D Card Hover, Light Sweep, Scan Line |
| 12 | Data Visualization | 12 | Bar Chart Rise, Radial Bars, Scatter Pop, Density Curve, Pie Slice Reveal, Radar Sweep |
| 13 | Enter & Exit | 8 | Fade In, Slide Up, Spring In, Stagger, Blur In, Collapse |

## Live Preview

Browse all 119 effects with live demos: **https://joepui.github.io/motion-ref-skill/**

## License

MIT
````
