Communitygithub.com

CharbelElBateh/personal-website

将 Apple 的界面设计与流畅物理动效理念应用于 Web 开发。适用于构建或审查基于手势的 UI、弹簧动画、拖拽/滑动/表单交互、动量与可中断过渡、半透明材质与景深、排版(光学尺寸、字距、行距)、减少动效以及 Apple 风格界面背后的设计基础(反馈、空间一致性、克制)。

personal-website 是什么?

此技能将 Apple 在 WWDC 设计讲座(尤其是《设计流畅界面》)中阐述的界面设计原则翻译并应用于 Web 平台。其核心思想是:一个界面之所以生动,是因为动效从当前屏幕上的值开始,继承用户的运动速度,投射出向前的动量,并且可以在任何瞬间被抓住并反向。该技能指导开发者使用弹簧动画(而非固定时长动画)来实现可中断、速度感知的交互,并涵盖了从即时反馈、直接操纵(1:1 跟踪)、动量投射、橡皮筋效果到半透明材质与景深等一整套设计原则。它支持所有现代 Web 平台,并提供了具体的 CSS、JavaScript(Pointer Events、requestAnimationFrame)及 Motion/Framer Motion 库的代码示例。

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

在你喜欢的 AI 中提问

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

文档

Apple 设计理念

初始回应

当此技能首次被调用且无特定问题时,仅回复:

我已准备好帮助你在 Web 上构建流畅、Apple 风格的界面,我的知识源自 Apple 的 WWDC 设计讲座,并已转化为 Web 实践。

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

Apple 如何构建那些不再像电脑、而更像是你自身延伸的界面。这些知识来自 Apple 的 WWDC 设计讲座——主要是《设计流畅界面》(WWDC 2018)——经过提炼并转化为 Web 平台(CSS、Pointer Events、requestAnimationFrame、像 Motion/Framer Motion 这样的弹簧库)。

核心线索是:当一个界面从当前屏幕上的值开始动效,继承用户的速度,向前投射动量,并且可以在任何时刻被抓住并反向时,它才是有生命的。 弹簧是实现这一切自然流畅的工具,因为它们本质上是可中断且速度感知的。

核心理念

"当我们让界面与我们的思考和移动方式保持一致时,就会发生神奇的事情——它不再感觉像一台电脑,而开始感觉像我们自身无感的延伸。"

当界面表现得像物理世界时,它就是流畅的:事物即时响应、连续移动、携带动量、在边界处施加阻力,并且可以在运动中途被重定向。以下所有内容都是为了更接近这个目标。

Apple 将设计定义为服务于四种人类需求:安全性/可预测性、理解力、成就感、以及愉悦感。 这里每一条规则都服务于其中一种需求。

1. 响应——消除延迟

延迟出现的瞬间,直接操作的感觉就会 "断崖式下跌"。响应是构建其他一切的基础。

  • 在指针按下时响应,而非释放时。 按钮被按下的瞬间就应高亮。等待 click/触摸结束才显示反馈会感觉死板。
  • 警惕每一次延迟。 审查防抖、人为计时器、过渡等待以及约 300ms 的点击延迟。任何输入路径上非必需的东西都是倒退。
  • 反馈必须在交互过程中持续进行,而不仅仅在结束时。 对于拖拽、滑块或抽屉,整个过程中 UI 必须与指针 1:1 更新——绝不仅仅在手势完成时做动画。
/* 反馈存在于按下时,并且是即时的 */
.button:active {
  transform: scale(0.97);
  transition: transform 100ms ease-out;
}

2. 直接操纵——1:1 跟踪

"触摸和内容应该一起移动。"

当用户拖拽某物时,它必须紧贴手指——并且尊重 他们抓住它时 的偏移量。在抓取时将其吸附到元素中心会立即破坏这种幻觉。

  • 使用带有 setPointerCapture 的 Pointer Events,以便即使在指针离开元素边界时也能继续跟踪。
  • 跟踪一段简短的 速度/位置历史记录(最近几次 pointermove 事件),而不仅仅是当前点——在释放时你需要用到速度。
el.addEventListener('pointerdown', (e) => {
  el.setPointerCapture(e.pointerId);
  const grabOffset = e.clientY - el.getBoundingClientRect().top; // 尊重他们的抓取点
  // ...记录位置和时间戳历史以计算速度
});

3. 可中断性——最重要的单一原则

"思维和手势是并行发生的。"

每个动画都必须在任何时刻可中断、可重定向。用户必须能够抓住一个正在移动的元素并使其反向,而无需等待动画完成。对于一个用户再次抓住的正在关闭的模态框,它应该跟随手指——而不是先完成关闭再重新打开。

  • 永远不要在过渡期间锁定输入。
  • 始终从 呈现(当前)值开始动画,而不是目标值。 中断时,读取元素实时的屏幕变换并从那里开始新的动画。从逻辑/目标值开始会导致可见的跳跃。
  • 对于任何手势驱动的场景,避免使用 CSS 过渡和 @keyframes——它们无法在中途被平滑地抓住和反向。弹簧默认从当前值开始动画,这正是中断所需的。
  • 当手势反向时,要融合速度——不要硬切。 在反转点用一个动画替换另一个动画会产生速度不连续,即"撞墙"。那些在重新定位时继承当前速度的弹簧库可以避免这种情况。(这就是 iOS 的 叠加动画 的原生做法;在 Web 上,选择一个能从当前速度重新定位的弹簧库。)
  • 将 2D 运动分解为独立的 X 和 Y 弹簧。 当 X 和 Y 具有不同速度时,单个用于 2D 距离的弹簧会失步。

4. 重行为而非动画——使用弹簧

"把动画想象成你和对象之间的对话,而不是界面规定的脚本。"

一个预设好固定时长的动画无法响应新输入。但弹簧可以——新输入只是改变了目标,运动保持连续。凡是用户可能触摸到的东西都用弹簧。

Apple 有意用两个对设计师更友好的参数取代了物理三元组(质量/刚度/阻尼)。请用这些参数思考:

  • 阻尼比——控制过冲。1.0 = 临界阻尼,无弹跳,平滑稳定。< 1.0 = 过冲并振荡。越低越弹。
  • 响应——值到达目标的速度,以秒为单位。越低越敏捷。这不是 "持续时间"——弹簧没有固定的持续时间;其稳定时间是由参数决定的。

默认值:

  • 绝大多数 UI 从 阻尼 1.0(临界阻尼)开始——优雅且不分散注意力。
  • 只在手势本身带有动量时(一次轻弹、抛出、拖拽释放)添加弹跳(阻尼约 0.8)。在一个刚刚淡入的菜单上过冲感觉不对;但在一张你轻弹过的卡片上过冲感觉就很自然。

Apple 实际使用的具体值:

交互阻尼响应
移动/重新定位(例如画中画)1.00.4
旋转0.80.4
抽屉/表单0.80.3

Web 映射(Motion / Framer Motion): bounce + duration 弹簧 API 与 Apple 的阻尼 + 响应非常接近。一个安全的默认风格是默认在所有地方使用 damping: 1.0 的弹簧;仅为动量驱动的、物理性的交互保留弹跳。

import { animate } from 'motion';

// 临界阻尼默认值(无过冲)
animate(el, { y: 0 }, { type: 'spring', bounce: 0, duration: 0.4 });

// 动量交互——有一点弹跳,仅因轻弹在前
animate(el, { y: target }, { type: 'spring', bounce: 0.2, duration: 0.4 });

5. 速度交接——拖拽与动画之间的接缝

当手势结束时,动画必须 以手指的精确速度继续,这样拖拽和动画之间就没有可见的接缝。这是最能区分 "流畅" 和 "还行" 的细节。

将指针的释放速度作为弹簧的初始速度传递。某些弹簧 API 需要 相对 速度——通过剩余到目标的距离将其归一化:

relativeVelocity = gestureVelocity / (targetValue − currentValue)

示例:元素在 y=50,目标 y=150(还有 100px),手指移动速度 50px/s → 初始弹簧速度 = 50 / 100 = 0.5。Framer Motion / Motion 直接接受绝对 px/s 速度(velocity 选项),所以通常你直接把原始值给它。

6. 动量投射——动画到手势 要去 的地方

"用小输入产生大输出。"

不要从 释放点 吸附到最近的边界。使用速度来 投射静止位置——就像滚动减速一样——然后吸附到离该投射点最近的目标。这就是为什么一次轻弹感觉像把元素扔出去了。

Apple 的精确投射函数(来自《设计流畅界面》示例代码):

// decelerationRate ≈ 0.998 用于普通滚动感受;0.99 用于更敏捷
function project(initialVelocity /* px/s */, decelerationRate = 0.998) {
  return (initialVelocity / 1000) * decelerationRate / (1 - decelerationRate);
}

const projectedEndpoint = currentPosition + project(releaseVelocity);
const target = nearestSnapPoint(projectedEndpoint);   // 从投射中选择目标
animateSpringTo(target, { velocity: releaseVelocity }); // 然后交接速度(§5)

注意:物理教科书中的 v²/(2·decel) 不是 Apple 的实际做法——请使用上面的指数衰减形式。这是好的底部表单和轮播(Vaul、Embla)中的标准行为。

7. 空间一致性——对称路径,锚定原点

"如果一个东西以一种方式消失,我们期望它从它来的地方出现。"

  • 沿着相同路径进入和退出。 一个从右侧滑入的面板必须从右侧关闭。从右进/从底出会让人感觉脱节和困惑。
  • 将交互锚定到其源头。 菜单、弹出框或表单应该从触发它的元素处产生——将 transform-origin 设置为触发器,这样按钮和内容之间的空间关系就一目了然了。(这和弹出框从触发器缩放,而不是从其中心缩放是同一个原点感知点。)
  • 在可逆过渡上镜像缓动效果,使退出路径与返回路径匹配(为两个方向使用反向的立方贝塞尔控制点)。

8. 手势方向提示

人类通过轨迹预测最终状态。中间运动应该预示事物要去哪里——控制中心模块 "朝着你的手指向上并向外生长"。让中间帧指向结果,而不仅仅是盲目地向其插值。

9. 橡皮筋效果——软边界

在边界处,渐进地施加阻力而不是生硬地停止。生硬的停止读作 "冻结";持续的阻力读作 "有响应,但这里没有更多内容了"。应用阻尼,用户拖过边界越远,阻尼越大。

// 越过边界越远,元素跟随得越少——真实物体在停止前会减速
function rubberband(overshoot, dimension, constant = 0.55) {
  return (overshoot * dimension * constant) / (dimension + constant * Math.abs(overshoot));
}

10. 手势设计细节("感受" 检查清单)

  • 点击: 触摸 按下 时高亮(即时),触摸 抬起 时提交。为目标添加约 10px 的迟滞/命中填充,并允许通过拖走再拖回取消。
  • 拖拽/滑动: 在提交方向之前,需要一个小幅度的移动阈值(迟滞,约 10px),然后 1:1 跟踪。
  • 从第一次移动开始并行检测所有可能的手势,一旦意图明确,自信地取消失败的候选。避免只报告 最终 状态的识别器(如 swipeleft 类型的事件)——它们丢弃了你需要用于反馈的连续跟踪。
  • 最小化歧义消除延迟。 双击检测不可避免地会延迟单击;只有在确实存在双击交互时才付出这个代价。

11. 帧级别平滑度

平滑度关乎的是 帧里有什么,而不仅仅是帧率。

  • 保持每帧的位置变化低于感知阈值,以避免闪烁。
  • 对于非常快的运动,微妙的 运动模糊 / 拉伸 可以编码速度,比坚硬的清晰条纹看起来更好。
  • requestAnimationFrame 是 Web 的显示同步时钟(Apple 使用 CADisplayLink)。仅制作合成器友好属性的动画——transform 和 opacity——并在运动即将发生时用 will-change 提示。

12. 材质与景深——半透明传达层级

Apple 使用半透明材质作为浮动功能层,在不夺取焦点的情况下带来结构感。在 Web 上,用 backdrop-filter 近似。

  • 将导航栏/工具栏/表单构建为半透明层(backdrop-filter: blur() + 半透明背景),内容在其下滚动——而不是消耗固定区域的纯色条。
  • 材质重量编码层级: 更暗/更重的材质分隔结构区域(侧边栏);更轻的材质吸引注意力到交互元素(按钮)。永远不要在另一个浅色半透明表面上叠加一个——可读性会崩溃。
  • 更大的表面应显得更厚: 比小的碎片更强的模糊和更深的阴影。考虑上下文相关的阴影——在繁忙/文本内容上更重以实现分离,在纯色背景上更轻。
  • 调暗以聚焦,分离以保持流畅。 模态任务将表面与调暗的遮罩配对,并将背景推远/下压。并行的、非阻塞的面板使用半透明度和偏移量而 不用 遮罩,以保持流程不断裂。对于堆叠的表单,逐渐调暗并将每个父层推后。
  • 活力(Vibrancy)使文本在变化的背景上保持可读性。 在模糊/半透明表面上,不要使用平面灰色文本——使用对比度更高、稍粗的字重以及小幅字间距增加。将颜色放在实心层上,而不是半透明前景上。
  • 使用滚动边缘效果,而不是硬分隔线。 而不是在粘性标题下放一条 1px 边框,在内容遇到浮动 “镀铬” 区域的地方淡化一个小模糊/渐变遮罩——仅在浮动 UI 实际与内容重叠的地方。
  • 实体化,而不仅仅是淡入淡出。 对于玻璃/模糊表面,在进入/退出时一起动画化模糊半径和缩放,使表面看起来像真实材料到达,而不是简单的透明度淡入淡出。
.toolbar {
  background: rgba(255, 255, 255, 0.6);
  backdrop-filter: blur(20px) saturate(180%);
  border-top: 1px solid rgba(255, 255, 255, 0.4); /* 亮色顶部边缘 = 材料捕捉光线 */
}

13. 多模态反馈——运动 + 声音 + 触觉

结合多种感官的三个规则(来自《设计音频-触觉体验》):

  1. 因果关系——反馈的原因必须显而易见。在实际的因果事件上触发反馈(例如开关翻转、项目归位),并使其特征与动作的物理性相匹配。
  2. 和谐——视觉、声音和触觉必须在 同一帧 上触发。它们之间的延迟会破坏这种错觉。不要让一个…

…

[此处原文被截断]

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

Build an animation from scratch, making the decisions in the order that determines whether it feels right — should it animate at all, what purpose, which tool, which properties, which curve and duration, how it interrupts, how it exits. Writes the implementation. Use when asked to animate something, add motion, make a component feel alive, or build a transition. For critiquing existing motion use review-animations; for auditing a whole codebase use improve-animations.

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

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.

相关技能