前言(前置执行)
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
_TEL_TIER="${_TEL_TIER:-anonymous}"
_TEL_PROMPTED=$([ -f ~/.superstack/.telemetry-prompted ] && echo "yes" || echo "no")
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
mkdir -p ~/.superstack
echo "TELEMETRY: $_TEL_TIER"
echo "TEL_PROMPTED: $_TEL_PROMPTED"
if [ "$_TEL_TIER" != "off" ]; then
_TEL_EVENT='{"skill":"page-load-animations","phase":"build","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'
echo "$_TEL_EVENT" >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
_CONVEX_URL=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"convexUrl":"[^"]*"' | head -1 | cut -d'"' -f4 || echo "")
[ -n "$_CONVEX_URL" ] && curl -s -X POST "$_CONVEX_URL/api/mutation" -H "Content-Type: application/json" -d '{"path":"telemetry:track","args":{"skill":"page-load-animations","phase":"build","status":"success","version":"0.2.0","platform":"'$(uname -s)-$(uname -m)'","timestamp":'$(date +%s)000'}}' >/dev/null 2>&1 &
true
fi
如果 TEL_PROMPTED 为 no:在开始技能工作流前,询问用户关于遥测的事宜。
使用 AskUserQuestion:
帮助 superstack 变得更好!我们会追踪哪些技能被使用以及耗时—— 不追踪代码、文件路径或任何个人信息。随时可以在
~/.superstack/config.json中更改。
选项:
- A) 当然,帮助 superstack 改进(匿名)
- B) 不了,谢谢
如果选择 A:执行以下 bash 命令:
echo '{"telemetryTier":"anonymous"}' > ~/.superstack/config.json
_TEL_TIER="anonymous"
touch ~/.superstack/.telemetry-prompted
如果选择 B:执行以下 bash 命令:
echo '{"telemetryTier":"off"}' > ~/.superstack/config.json
_TEL_TIER="off"
touch ~/.superstack/.telemetry-prompted
这只发生一次。如果 TEL_PROMPTED 为 yes,则完全跳过此步骤,直接进入技能工作流。
技能选错? 请参阅 SKILL_ROUTER.md 查看所有可用技能。
页面加载动画
模式源自经过实战检验的 framer-motion 配方。原始灵感:suzi-ux-motions。
经过生产验证的 framer-motion 配方,让页面加载感觉有意为之而非杂乱无章。此技能的存在是因为加密 UI 中最常见的动画问题不是缺少动画——而是所有内容同时出现,没有编排、交错或弹簧物理效果。结果即使代码正确,也给用户一种卡顿的感觉。
此技能提供实现配方。有关动画理论(何时使用动画、持续时间层级、缓动曲线、减少运动),请参阅 frontend-design-guidelines/references/animation.md。此技能继承所有这些基线约束。
权威模型
animation.md= 基线约束(持续时间层级、缓动、减少运动、GPU 属性)- 此技能 = 在这些约束内实现的生产级配方
frontend-design-guidelines将 framer-motion 模式委托给此技能,而非相反
安装
npm install framer-motion
CSS 过渡是简单状态变化的默认方案(依据 animation.md)。在以下情况使用 framer-motion:需要弹簧物理、编排序列、AnimatePresence 退出动画、手势/拖拽或共享布局过渡。
何时触发此技能
在任何以下场景中应用这些配方:
- 构建一个加载多个部分的页面(仪表盘、详情页、落地页)
- 在挂载时交错显示列表、卡片网格或表格
- 对模态框、下拉菜单或弹出框进行动画处理
- 切换标签页或筛选器,内容变化且高度变化
- 显示实时更新的数字、图表或环形图
- 添加悬停反馈、V 形旋转或工具提示入场效果
- 审查现有 framer-motion 代码中的反模式
- 用户说“页面感觉卡顿”或“所有内容同时出现”
如果你正在构建页面级组件且此技能尚未触发,请自行触发它。
工作流程
在编写动画代码之前,识别相关的参考文件并阅读:
- 编排页面加载入场 → references/page-choreography.md
- 交错显示列表或卡片网格 → references/list-stagger.md
- 对模态框、下拉菜单或弹出框进行动画处理 → references/popups-modals.md
- 切换标签页/筛选器并处理高度变化 → references/filter-transitions.md
- 滚动数字、图表变形、环形图揭示 → references/live-data.md
- 按钮反馈、V 形旋转、工具提示 → references/hover-micro.md
- 查找弹簧预设或缓动曲线 → references/spring-presets.md
只加载所需内容。不要预先读取所有参考文件。
模式 1:构建新动画
- 阅读你所需模式的相关参考文件。
- 从 ASCII 故事板注释开始——在编写任何代码之前规划完整序列。
- 定义一个 TIMING 对象,为每个延迟使用命名常量。
- 使用参考文件中的模式实现。默认使用弹簧物理。
- 在报告完成之前,对照下面的不可妥协规则进行验证。
模式 2:审查现有动画代码
- 扫描常见的反模式:
# 在父元素和子元素上都使用 layout 属性(抖动来源) grep -rn "layout" --include="*.tsx" --include="*.jsx" | head -20 # 将 staggerChildren 与 AnimatePresence 一起使用(不可靠) grep -rn "staggerChildren" --include="*.tsx" --include="*.jsx" | head -10 # transition-all(动画化非预期属性) grep -rn "transition-all\|transition: all" --include="*.tsx" --include="*.css" | head -10 # 缺少减少运动处理 grep -rn "motion\.\|animate=" --include="*.tsx" -l | while read f; do grep -L "reduced-motion\|useReducedMotion\|motion-safe" "$f"; done | head -10 - 针对每个发现的问题,引用相关参考文件中的特定反模式规则。
- 提供精确的代码补丁。
模式 3:快速查询
如果用户问“X 的弹簧配置是什么?”或“如何对 Y 进行动画处理?”,直接从参考文件和弹簧预设中回答,无需运行完整工作流。
不可妥协规则
- ASCII 故事板注释。 每个动画页面都以一个时间线注释开头,一目了然地展示完整序列。时间从挂载开始计算,右对齐。
- 命名时序常量。 每个延迟都放在文件顶部的 TIMING 对象中。
setTimeout或delay属性中不允许出现魔法数字。 - 弹簧优先。 对于自然、可中断的运动,优先使用弹簧物理而非基于持续时间的缓动。仅淡入淡出和工具提示使用持续时间。
- 阶段驱动排序。 单个整数状态驱动多部分序列。不允许分散的布尔标志。
stage >= N模式。 各部分一旦出现就保持可见。绝不要使用stage === N。- 绝不在父元素和子元素上都使用
layout。 这是筛选动画抖动问题的第一大原因。改用带有ResizeObserver的AnimatedHeight。 - 绝不对
AnimatePresence使用staggerChildren。 它不可靠。改用delay: i * stagger手动实现。 - 尊重
prefers-reduced-motion。 继承自animation.md。每个动画必须优雅降级。 - 挂载与更新的区分。 挂载动画应具戏剧性(600ms,富有表现力的缓动)。更新动画应细腻(150ms,平滑缓动)。不同阶段,不同配置。
设计原则
- 故事板优先——在编写代码之前规划序列
- 弹簧优先——弹簧物理优于基于持续时间的缓动
- 命名常量——每个时序值都声明,而非内联
- 阶段驱动——单个整数状态编排复杂序列
- 数据驱动——重复元素使用
.map()配合基于索引的延迟,而非复制粘贴的代码块 - 测量而非猜测——对于动态高度使用
ResizeObserver,绝不使用硬编码的像素高度
与其他技能的集成
frontend-design-guidelines——通用 UI 技能。它将 framer-motion 的工作委托给此技能。当两者都触发时,animation.md的基线规则在约束方面具有权威性;此技能在实现配方方面具有权威性。number-formatting——对于实时更新的数字显示,使用number-formatting进行格式化规范,使用此技能进行滚动数字动画模式。brand-design——品牌颜色可能影响动画颜色选择(正/负指示符、强调高亮)。
资源
references/
- references/page-choreography.md — 阶段驱动的页面入场,含 ASCII 故事板、TIMING 对象、章节配置、弹簧预设和
stage >= N模式 - references/list-stagger.md — 基于索引的交错延迟、StaggerItem 包装器、时序/偏移指南和反模式
- references/popups-modals.md — 三层模态动画(背景、面板、内容交错)、下拉菜单模式、关闭行为
- references/filter-transitions.md — 带 ResizeObserver 的 AnimatedHeight、带键包装器的交叉淡入淡出、关键
layout反模式 - references/live-data.md — 滚动数字(老虎机样式)、SVG 环形图揭示、图表变形、挂载与更新阶段管理
- references/hover-micro.md — CSS 与 framer-motion 决策矩阵、按钮反馈、V 形旋转、工具提示入场、复制反馈
- references/spring-presets.md — 所有预设以表格 + JSON 形式呈现:弹簧配置、缓动曲线、交错值、持续时间预设
跨技能参考
frontend-design-guidelines/references/animation.md— 此技能继承的基线约束(持续时间层级、缓动、减少运动、GPU 属性)number-formatting— 数字显示规则(格式化,非动画)
快速开始
# 触发方式:
# "修复我的页面加载——所有内容同时出现"
# "为这个仪表盘添加入场动画"
# "模态框动画感觉很卡顿"
# "如何交错显示这些卡片?"
# "下拉菜单应该用什么弹簧配置?"
# "为余额显示添加滚动数字动画"
# 构建页面级组件时自动触发
遥测(最后执行)
技能工作流完成(成功、错误或中止)后,记录遥测事件。
根据工作流结果确定结果:success(正常完成)、error(失败)、abort(用户中断)。
执行以下 bash 命令:
_TEL_END=$(date +%s)
_TEL_DUR=$(( _TEL_END - ${_TEL_START:-$_TEL_END} ))
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
if [ "$_TEL_TIER" != "off" ]; then
echo '{"skill":"page-load-animations","phase":"build","event":"completed","outcome":"OUTCOME","duration_s":"'"$_TEL_DUR"'","session":"'"$_SESSION_ID"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","platform":"'$(uname -s)-$(uname -m)'"}' >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
true
fi
根据工作流结果将 OUTCOME 替换为 success/error/abort。