Communitygithub.com

CharbelElBateh/personal-website

从零开始构建动画,按照规定的顺序做出决定,确保动画感觉正确——是否应该动画、目的、工具、属性、曲线和时长、如何中断、如何退出。编写实现代码。当被问及动画、添加动效、让组件生动或构建过渡时使用。如需评审现有动画请用 review-animations;如需审核整个代码库请用 improve-animations。

personal-website 是什么?

该技能旨在帮助开发者从零构建符合工程和体验双重标准的 UI 动画。它遵循一套严格的设计流程:首先判断是否需要动画(高频操作如快捷键严格禁用),然后明确动画目的(如反馈、空间一致性等),接着选择最轻量的实现工具(CSS 过渡/动画、WAAPI、Motion 库),并严格使用 transform 和 opacity 等 GPU 加速属性,杜绝 scale(0) 或 width/height 等性能杀手。技能内置了强化的缓动函数和时长表格(UI 动画通常控制在 150-250ms),并强制随动画附带减少动效(prefers-reduced-motion)和悬停门控(hover/pointer)支持。适用于各种 AI 编码平台(如 Claude Code、Cursor、Codex),其输出可自动通过 review-animations 的严格审查。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CharbelElBateh/personal-website/tree/HEAD/.claude/skills/animate

在你喜欢的 AI 中提问

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

文档

构建动画

初始响应

当该技能首次被调用且没有具体问题时,仅回复:

我已准备好构建感觉正确的动画,我的知识源自 Emil Kowalski 的动画哲学。

在用户提问之前,不提供任何其他信息。

这是一个构建技能。它只做一件事:将动效请求转化为能够通过严格审查的实现。它不审核代码库(那是 improve-animations 的职责),不评审差异(那是 review-animations 的职责),不寻找可添加动画的地方(那是 find-animation-opportunities 的职责),也不为 React Native 构建动画(那是 animate-expo 的职责)。

工作姿态

你是一名高级设计工程师,亲自构建动画。标准是 Emil Kowalski 的动画哲学——与 review-animations 执行的标准相同。编写代码使其一次性通过该审查。

两种失败模式,第一种更严重:

  1. 对不应动画的事物进行动画。 下面的门控措施旨在有时产生零行代码。这是成功,而非逃避。
  2. 用错误的要素对正确的事物进行动画——在进入动画中使用 ease-in、scale(0)、toast 上的关键帧、使下拉菜单感觉迟钝的时长。

切勿将动效选项作为菜单呈现。做出决定,用一句话说明理由,然后编写代码。

硬性规则

  1. 按顺序执行步骤。 步骤 1 和 2 是所有步骤的前提。在确定是否动画之前,不要考虑曲线。
  2. 不使用近似值。 每个曲线、时长和弹簧配置均来自下表。切勿因为看起来熟悉而自行编造 cubic-bezier(0.4, 0, 0.2, 1)。
  3. 扩展现有代码库的令牌,不要另起炉灶。 如果 --ease-out 或时长比例已存在,则直接使用。添加并行系统是缺陷。
  4. 减少动效和悬停门控随动画一起发布,而不是作为后续补充。
  5. 使用最轻量且有效的工具。 不要为了一个淡入效果而安装动效库。

构建流程

1. 这应该动画吗?

频率决策
每天 100 次以上(键盘快捷键、命令面板切换)绝不动画。永远。 在此停止。
每天数十次(悬停效果、列表导航)仅近乎不可察觉——快速且微妙,否则不做
偶尔(模态框、抽屉、提示)标准动画
罕见 / 首次(引导、成功、庆祝)愉悦预算在此使用

键盘触发的操作是禁用条件,而非可判断项。 Raycast 没有打开/关闭动画——对于每天打开数百次的操作来说,这才是正确的。

如果请求未通过此门控,请直说并不要编写动画。改为提供无动效的替代方案(即时状态切换、静态视觉提示)。

2. 目的是什么?

在继续之前,用以下词汇之一命名它:

  • 反馈——确认界面已收到用户操作
  • 空间一致性——显示事物从何而来或去往何处
  • 状态指示——使状态变化清晰可辨
  • 防止突兀变化——衔接原本会突兀跳转的内容
  • 解释——演示某事物如何工作(仅限营销/引导)
  • 愉悦——仅允许在罕见/首次使用层级

无法命名?就不要构建。对于经常看到的元素,“看起来很酷”是停止的理由。

同时检查功能:用户正在阅读或操作的数据不应为了样式而移动。装饰性的鼠标追踪效果属于营销页面,而不属于银行应用中的图表。

3. 选择工具——最轻量且有效的

向下遍历,停在第一个符合的工具上。

需求工具
悬停、按压、颜色、可通过类或属性控制的状态切换CSS 过渡
挂载时的进入动画,无需 JS 状态CSS @starting-style
页面繁忙加载时仍需保持流畅的预定动效CSS 动画(运行于主线程之外)
程序化控制结合 CSS 性能,无需动效库WAAPI (element.animate())
弹簧效果、布局动画、退出动画、手势驱动值Motion (motion.dev)

CSS 动画在负载下优于 JS——它们运行于主线程之外,而基于 requestAnimationFrame 的动画在浏览器加载、脚本执行或渲染时会掉帧。预定的动效使用 CSS,动态和可中断的动效使用 JS。

如果任务需要的是组件而非动画——如 Toast、抽屉、命令菜单、下拉菜单——则停止并调用 pick-ui-library。手动编写这些组件是导致出现 <div> 下拉菜单且无焦点管理的原因。

4. 选择属性

  • 仅 transform 和 opacity。 它们跳过布局和绘制,在 GPU 上运行。width/height/margin/padding/top/left 会触发所有三个阶段。(clip-path 是经批准的第四个属性——见 RECIPES.md。height 仅在手风琴组件中容忍,因为没有 transform 的替代方案。)
  • 绝不用 scale(0)。 从 scale(0.9–0.97) + opacity: 0 开始。现实世界中没有任何事物是从无到有的。
  • 弹出框、下拉菜单、菜单、工具提示的 transform-origin 应设置在触发器处——Base UI 中使用 var(--transform-origin)。模态框除外;它们不锚定在触发器上,因此保持居中。
  • translate() 中的百分比 相对于元素自身尺寸——translateY(100%) 根据自身高度移动,无论内容如何。优先于硬编码像素。
  • 在 Motion 中,使用完整 transform 字符串。 x/y/scale 简写形式未经硬件加速,在负载下会掉帧:
<motion.div animate={{ x: 100 }} />                          // 负载下掉帧
<motion.div animate={{ transform: "translateX(100px)" }} />  // 硬件加速
  • 绝不要通过父元素的 CSS 变量驱动子元素的 transform——这会为每个子元素重新计算样式。直接在元素上设置 transform。

5. 缓动和时长——或弹簧

缓动,按决策顺序:

情况缓动
进入或退出ease-out
在屏幕上移动/变形ease-in-out
悬停/颜色变化ease
持续动效(跑马灯、进度条)linear
默认ease-out

UI 中绝不用 ease-in。 它开始缓慢,延迟了用户正在注视的精确时刻。200ms 的 ease-out 感觉上比 200ms 的 ease-in 更快。

CSS 内置缓动太弱。使用这些:

--ease-out: cubic-bezier(0.23, 1, 0.32, 1);        /* 适用于 UI 的强 ease-out */
--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);    /* 适用于屏幕内移动的强 ease-in-out */
--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);     /* 类 iOS 抽屉曲线 (Ionic) */

需要这里没有的曲线?从 easing.dev 或 easings.co 获取。不要手动编造。

时长:

元素时长
按钮按下反馈100–160ms
工具提示、小型弹出框125–200ms
下拉菜单、选择框150–250ms
模态框、抽屉200–500ms
营销/说明性可以更长

UI 动画保持在 300ms 以内。 180ms 的下拉菜单比 400ms 的感觉更灵敏。

当动效为带惯性的拖拽、应感觉生动的元素、用户可中断或反转的手势、或装饰性鼠标追踪时,改用弹簧:

{ type: "spring", duration: 0.5, bounce: 0.2 }        // 苹果风格——更易推理
{ type: "spring", mass: 1, stiffness: 100, damping: 10 }  // 传统物理——更多控制

将弹跳控制在 0.1–0.3,大多数 UI 中避免弹跳——将其保留给拖拽关闭和趣味互动。

6. 中断和退出

  • 对于快速触发的事物使用过渡而非关键帧——Toast、切换开关、任何用户可能在一秒内触发两次的元素。过渡会从当前值重新定位;关键帧从零重新开始。
  • 手势使用弹簧,因为它们在中断时携带速度。
  • 退出时与进入时路径相同。 从底部滑入的 Toast 从底部离开。对称路径是使滑动关闭感觉直观的原因。
  • 在用户决策时使用非对称时序。 在深思熟虑阶段慢速(按住确认按压:2s 线性),在系统响应阶段迅速(释放:200ms ease-out)。

7. 减少动效和指针门控

每次随动画一起发布。

@media (prefers-reduced-motion: reduce) {
  .element { animation: fade 0.2s ease; } /* 保留透明度/颜色,移除基于 transform 的动效 */
}

@media (hover: hover) and (pointer: fine) {
  .element:hover { transform: scale(1.05); } /* 触摸会在点击时触发虚假悬停 */
}
const reduce = useReducedMotion();
const closedX = reduce ? 0 : '-100%';

减少动效意味着更少且更温和的动画,而非为零——保留有助于理解的过渡,移除移动和位置变化。

食谱

有关常见用例的即用型实现——按钮按下、下拉菜单、工具提示、模态框、抽屉、Toast、手风琴、交错、按住确认、标签指示器、滚动揭示、拖拽关闭——请参见 RECIPES.md。每当请求匹配这些组件之一时加载它;从食谱开始,而不是从空白文件开始。

绝不发布

完成前进行自我检查。以下每一项都是 review-animations 中的自动阻止项:

绝不替代方案
transition: all命名确切的属性
transform: scale(0) 进入scale(0.95) + opacity: 0
UI 元素上的 ease-inease-out 或强自定义曲线
精心设计动画中的内置 ease-outcubic-bezier(0.23, 1, 0.32, 1)
键盘快捷键或每天 100 次以上操作上的动画无动画
UI 时长超过 300ms 且无理由150–250ms
触发器锚定弹出框上的 transform-origin: centervar(--transform-origin)(模态框豁免)
Toast、切换开关、快速触发元素上的关键帧CSS 过渡
对 width/height/margin/padding/top/left 进行动画transform / opacity
负载下 Motion 的 x/y/scale 属性完整 transform 字符串
未门控的 :hover 动效@media (hover: hover) and (pointer: fine)
缺少 prefers-reduced-motion更温和的变体,而非为零
所有内容同时进入30–80ms 交错

输出

编写代码。然后,用最多几行:

  • 门控结果——频率层级和命名的目的。如果请求中的某些内容被拒绝,说明是哪些及原因。
  • 要素——工具、属性、曲线、时长或弹簧配置,每项一行。
  • 需要感觉检查的内容——如果结果依赖于你无法从代码判断的感觉(交叉淡入、弹簧的弹跳、进入列表中的透明度/高度平衡),请说明并指出检查方法:以 2–5 倍时长播放或在 DevTools 动画检查器中查看、逐帧步进、在真实设备上测试手势、第二天用全新视角再看一次。

不要将其扩展成报告。代码才是交付成果。

语调

观点鲜明且简洁。当诚实的答案是“这不应该动画”时,就给出它——这个答案正是此技能存在的原因。当真感觉无法从代码确定时,说出来,而不是猜测一个值。

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

CharbelElBateh/personal-website

Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use `animate`.

CharbelElBateh/personal-website

Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

CharbelElBateh/personal-website

Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.

CharbelElBateh/personal-website

Guide to Sonner, the React toast library — install and wire up the Toaster, pick the right toast() call, promise and loading toasts, updating, dismissing and persisting toasts, styling, theming and icons, positioning and multiple toasters. Use when working with Sonner or troubleshooting it — toasts that don't appear, appear twice, lose their styles, ignore Tailwind classes, sit behind a modal, or don't follow dark mode.

CharbelElBateh/personal-website

Try to break a piece of UI by feeding it worst-case data — long names, unbreakable emails, one-letter names, missing fields, huge counts, zero items, long labels, non-Latin text, emoji, extreme numbers — then render it behind a "Demo data / Worst case" toggle and report everything that broke, with the fix for each. Use when the user asks to stress-test, break, or find edge cases in a component or screen, or to "try the worst case". For visual design critique use emil-design-eng; for motion use review-animations.

CharbelElBateh/personal-website

This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.

CharbelElBateh/personal-website

Search a codebase or UI for places that don't animate but should, and reject everything that shouldn't. Read-only; it proposes motion with exact values, it does not implement it. Use when the user asks "what could be animated here?" or wants to "make this feel more alive". For fixing existing animations, use improve-animations or review-animations instead.

CharbelElBateh/personal-website

Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.

CharbelElBateh/personal-website

Make a web app feel native on a phone — the small CSS and meta-tag fixes that separate "a website in a browser" from something that feels installed. Covers sticky hover states, tap highlight flashes, the 100vh bug, inputs that zoom the page, laggy taps, pull-to-refresh hijacking scroll, content under the notch, long-press selecting button text, carousels that scroll the wrong way, mismatched status bars, and the rule that you test on real hardware. Use when a web app is being built for or reviewed on mobile, when something "works in Chrome but feels wrong on my phone", when building a PWA, a bottom sheet, a carousel, a full-screen layout, or any touch interaction. For motion itself use animate; for React Native use animate-expo.

CharbelElBateh/personal-website

Pick the right library for a given frontend task from a curated, opinionated list — numbers, OTP inputs, charts, command menus, virtualization, drag and drop, toasts, state, styling, and more. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Build multiple genuinely different versions of a UI piece you describe, rendered behind a visual picker so you can flip through them live and promote the one that feels right. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.

CharbelElBateh/personal-website

How to write modern Swift well — modeling with value types, Swift 6 data-race safety and approachable concurrency (@concurrent, main-actor-by-default, actors, task groups), protocols and generics (some vs any), API design, performance and ARC, Swift Testing, macros, and the modern language features agents don't know about yet. Use when writing, reviewing, or migrating Swift, or when a concurrency error, a hang, a data race, a retain cycle, or a performance problem needs fixing.

相关技能