Communitygithub.com

Abduovv/Arcadia-frontend

修复页面内容同时涌入的卡顿问题。提供经过生产验证的 framer-motion 配方,用于编排页面入场动画、列表交错、模态框过渡、滤镜交叉淡入淡出、实时数据动画和微交互。

Arcadia-frontend 是什么?

该技能提供了一套经过生产验证的 framer-motion 模式,专门解决页面加载动画中最常见的问题——所有内容同时出现、缺乏编排和物理感。它支持多种主流 AI 代理平台(Claude Code、Cursor、Codex 等),适用于构建或审查任何需要加载内容的页面、修复卡顿动画、以及将 framer-motion 代码提升到生产级别。核心工作流程分为三种模式:构建新动画(通过 ASCII 故事板、时序对象和参考文件实现)、审查现有动画代码(使用 CLI 扫描反模式并给出精确补丁)、快速查询(直接回答弹簧配置或动画实现问题)。技能内建了九条不可妥协的规则,包括强制性故事板注释、命名时序常量、弹簧优先、阶段驱动序列、以及尊重 prefers-reduced-motion 等。提供详细的参考文件(页面编排、列表交错、弹出模态框、滤镜过渡、实时数据、悬停微交互、弹簧预设),并通过遥测机制收集使用情况以持续改进。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Abduovv/Arcadia-frontend/tree/HEAD/.agents/skills/page-load-animations

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

前言(前置执行)

_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 代码中的反模式
  • 用户说“页面感觉卡顿”或“所有内容同时出现”

如果你正在构建页面级组件且此技能尚未触发,请自行触发它。

工作流程

在编写动画代码之前,识别相关的参考文件并阅读:

只加载所需内容。不要预先读取所有参考文件。

模式 1:构建新动画

  1. 阅读你所需模式的相关参考文件。
  2. 从 ASCII 故事板注释开始——在编写任何代码之前规划完整序列。
  3. 定义一个 TIMING 对象,为每个延迟使用命名常量。
  4. 使用参考文件中的模式实现。默认使用弹簧物理。
  5. 在报告完成之前,对照下面的不可妥协规则进行验证。

模式 2:审查现有动画代码

  1. 扫描常见的反模式:
    # 在父元素和子元素上都使用 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
    
  2. 针对每个发现的问题,引用相关参考文件中的特定反模式规则。
  3. 提供精确的代码补丁。

模式 3:快速查询

如果用户问“X 的弹簧配置是什么?”或“如何对 Y 进行动画处理?”,直接从参考文件和弹簧预设中回答,无需运行完整工作流。

不可妥协规则

  1. ASCII 故事板注释。 每个动画页面都以一个时间线注释开头,一目了然地展示完整序列。时间从挂载开始计算,右对齐。
  2. 命名时序常量。 每个延迟都放在文件顶部的 TIMING 对象中。setTimeout 或 delay 属性中不允许出现魔法数字。
  3. 弹簧优先。 对于自然、可中断的运动,优先使用弹簧物理而非基于持续时间的缓动。仅淡入淡出和工具提示使用持续时间。
  4. 阶段驱动排序。 单个整数状态驱动多部分序列。不允许分散的布尔标志。
  5. stage >= N 模式。 各部分一旦出现就保持可见。绝不要使用 stage === N。
  6. 绝不在父元素和子元素上都使用 layout。 这是筛选动画抖动问题的第一大原因。改用带有 ResizeObserver 的 AnimatedHeight。
  7. 绝不对 AnimatePresence 使用 staggerChildren。 它不可靠。改用 delay: i * stagger 手动实现。
  8. 尊重 prefers-reduced-motion。 继承自 animation.md。每个动画必须优雅降级。
  9. 挂载与更新的区分。 挂载动画应具戏剧性(600ms,富有表现力的缓动)。更新动画应细腻(150ms,平滑缓动)。不同阶段,不同配置。

设计原则

  1. 故事板优先——在编写代码之前规划序列
  2. 弹簧优先——弹簧物理优于基于持续时间的缓动
  3. 命名常量——每个时序值都声明,而非内联
  4. 阶段驱动——单个整数状态编排复杂序列
  5. 数据驱动——重复元素使用 .map() 配合基于索引的延迟,而非复制粘贴的代码块
  6. 测量而非猜测——对于动态高度使用 ResizeObserver,绝不使用硬编码的像素高度

与其他技能的集成

  • frontend-design-guidelines——通用 UI 技能。它将 framer-motion 的工作委托给此技能。当两者都触发时,animation.md 的基线规则在约束方面具有权威性;此技能在实现配方方面具有权威性。
  • number-formatting——对于实时更新的数字显示,使用 number-formatting 进行格式化规范,使用此技能进行滚动数字动画模式。
  • brand-design——品牌颜色可能影响动画颜色选择(正/负指示符、强调高亮)。

资源

references/

跨技能参考

  • 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。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能