react-bits apple-design 技能文档：把苹果「流体界面」设计哲学落地为 Web 动效工程实践

本文以 react-bits 仓库中 AGENTS/SKILLS/apple-design/SKILL.md 这份设计技能文档为主体，系统拆解苹果「流体界面」（Fluid Interfaces）方法论如何翻译成 Web 技术栈：从指针响应与 1:1 跟手、可中断弹簧动画，到速度交接、动量投影、橡皮筋边界、半透明材质、减动效适配与排版细节。读完你可以掌握一套完整的「Apple 式交互手感」实现清单与具体参数值，并能在仓库源码（如 Carousel、TiltedCard、Dock）中看到这些原则的实际应用。

这份文档源自苹果 WWDC 设计演讲的提炼——尤其是 2018 年的 Designing Fluid Interfaces——并将其转译到 CSS、Pointer Events、requestAnimationFrame 与 Motion/Framer Motion 等弹簧动画库上。它的一条主线可以概括为：

当运动从屏幕当前的实时值出发、继承用户手势的速度、向前投影动量、并且随时可以被抓住并反向时，界面就"活"了。弹簧是实现这一切的自然工具，因为它天然可中断、速度感知。

苹果的官方表述（文档原文引用）："When we align the interface to the way we think and move, something magical happens — it stops feeling like a computer and starts feeling like a seamless extension of us." 苹果将设计归结为服务四种人类需求：安全/可预期、理解、成就感、愉悦。文档中的每一条规则都在服务其中之一。

1. 响应性（Response）：消灭延迟

一旦出现滞后感，"直接操作"的错觉会"断崖式崩塌"。响应性是其他一切的地基，文档给出三条军规：

• 在 pointer-down（按下瞬间）就响应，而不是等释放。 按钮在被按下的瞬间就该高亮。等 click/touch-up 才给反馈，界面会显得"死"。
• 对一切延迟保持警惕。 审查防抖（debounce）、人为定时器、过渡等待、以及著名的 ~300ms tap 延迟——输入链路上任何非必需的环节都是退化。
• 反馈必须在交互"进行中"持续存在，而不只是结束时给一次。 拖拽、滑块、抽屉要全程 1:1 跟随指针，绝不能在手势完成时才动画。

文档给出的最小可复制示例：

/* 反馈发生在按压的瞬间，而且立刻 */
.button:active {
  transform: scale(0.97);
  transition: transform 100ms ease-out;
}

在 react-bits 中这类"瞬时反馈"大量存在，例如 Dock 组件 的图标放大就是 hover/press 即时触发的，而非延迟判定后补动画。

2. 直接操纵（Direct Manipulation）：1:1 跟手

"Touch and content should move together."（触控和内容应该一起动。）

拖拽时元素必须"粘"在手指上，并尊重用户从哪里抓起的偏移——抓起时元素中心跳到手指正下方，会立刻破坏错觉。文档要求的实现要点：

• 使用 Pointer Events 配合 setPointerCapture，即使指针移出元素边界也持续跟踪；
• 记录一段速度/位置历史（最近几次 pointermove 的时间戳+坐标），因为释放时需要速度值。

el.addEventListener('pointerdown', (e) => {
  el.setPointerCapture(e.pointerId);
  const grabOffset = e.clientY - el.getBoundingClientRect().top; // 尊重抓取点偏移
  // ...记录位置 + 时间戳历史以计算速度
});

react-bits 的 TiltedCard 组件 就是这个原则的典型应用：handleMouse 中先用 getBoundingClientRect() 算出指针相对元素中心的 offsetX/offsetY，再映射为 rotateX/rotateY——旋转中心始终是元素几何中心而非指针位置，保证了 1:1 的空间对应关系。

3. 可中断性（Interruptibility）：最重要的单一原则

"The thought and the gesture happen in parallel."（思维和手势并行发生。）

每一个动画都必须在任意时刻可中断、可改向。 用户要能中途抓住一个正在运动的元素并反向它，而不必等动画播完。一个正在关闭的 modal 若被再次抓住，应该跟手——而不是"先关完再重开"。文档给出的工程规则：

• 过渡期间绝不锁死输入。
• 永远从 presentation（当前实时呈现）值开始动画，而不是目标值。 中断时读取元素屏幕上的实时 transform，从那里开始新动画；从逻辑/目标值开始会产生肉眼可见的跳变。
• 手势驱动的动画避免用 CSS transition 和 @keyframes——它们无法在飞行途中被平滑抓住反向。弹簧默认从当前值开始，正是中断所需要的。
• 手势反向时要"混合速度"而不是硬切换。 在反向点用一个动画替换另一个会产生速度不连续——文档称之为"撞墙感"（brick wall）。iOS 的 additive animations 原生做到这一点；Web 上要选一个支持"从当前速度重新定向"的弹簧库。
• 把 2D 运动分解为独立的 X 和 Y 两个弹簧。 单个弹簧作用于 2D 距离上，当 X、Y 速度不同时会产生失步。

仓库源码印证了最后一条：TiltedCard 为 rotateX、rotateY、scale 各自建立了独立的 useSpring（参数 damping: 30, stiffness: 100, mass: 2），而不是用单个弹簧去驱动一个合成的 3D 变换——这正是"独立轴弹簧"原则在 React + Motion 中的落地。

4. 行为优于动画（Behavior over Animation）：使用弹簧

"Think of animation as a conversation between you and the object, not something prescribed by the interface."（把动画看作你与对象之间的对话，而非界面预先规定好的脚本。）

固定时长的脚本化动画无法响应新输入；弹簧可以——新输入只是改变目标值，运动保持连续。凡是可以被用户触碰的东西，都应使用弹簧。

苹果刻意用两个设计师友好的参数取代了物理三参数（mass/stiffness/damping）。用这套词汇思考：

• Damping ratio（阻尼比）——控制过冲。1.0 = 临界阻尼，无回弹、平滑落位；< 1.0 = 过冲并振荡；越小越"弹"。
• Response（响应速度）——数值到达目标所需时间（秒）。越小越干脆。注意它不是"duration"——弹簧没有固定时长，落位时间是参数涌现出来的。

默认值策略：

• 大多数 UI 从 damping 1.0（临界阻尼）起步——优雅、不抢注意力。
• 只有当手势本身携带动量时（flick、throw、拖拽释放）才加回弹（damping ~0.8）。一个淡入菜单带过冲是错的；一张你甩出去的卡片带过冲是对的。

苹果实际出厂的具体数值（文档原表，务必保留为项目 house style 参考）：

交互	Damping	Response
Move / reposition（如 PiP 窗口）	1.0	0.4
Rotation	0.8	0.4
Drawer / sheet	0.8	0.3

Web 映射（Motion / Framer Motion）： bounce + duration 的弹簧 API 与苹果的 damping + response 映射关系很近。文档给出的安全 house style 是：默认处处使用 damping: 1.0 的弹簧；回弹只保留给动量驱动的物理交互。

import { animate } from 'motion';

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

// 动量交互——一点回弹，仅因为前面有一个 flick
animate(el, { y: target }, { type: 'spring', bounce: 0.2, duration: 0.4 });

react-bits 中大量组件基于 motion/react 构建（如 TiltedCard 顶部 import { motion, useMotionValue, useSpring } from 'motion/react'），与文档推荐的库完全一致。

5. 速度交接（Velocity Handoff）：拖拽与动画之间的接缝

手势结束时，动画必须以手指当时的精确速度继续，拖拽与动画之间才没有可见接缝。这是区分"流畅"与"还行"的关键细节。

做法：把指针释放速度作为弹簧的初始速度传入。部分弹簧 API 需要的是相对速度——用剩余距离归一化：

relativeVelocity = gestureVelocity / (targetValue − currentValue)

示例：元素在 y=50，目标 y=150（还差 100px），手指速度 50px/s → 弹簧初始速度 = 50 / 100 = 0.5。Framer Motion / Motion 直接接受绝对 px/s 速度（velocity 选项），所以你通常直接传原始值。

仓库中 Carousel 组件 的 handleDragEnd 就在消费这个速度：const { offset, velocity } = info; 并用 velocity.x 与 VELOCITY_THRESHOLD（500）比较来决定翻页方向——用速度的正负/大小，而不是仅看位置，来决定"继续"还是"回弹"，这正是 Quick Reference 表中"Decide reverse vs. commit: Use velocity sign, not position"的实现。

6. 动量投影（Momentum Projection）：向手势"将要去的地方"动画

"Take a small input and make a big output."（用小输入产生大输出。）

不要从释放点吸附到最近边界。要用速度投影出静止位置——完全像滚动减速一样——然后吸附到离投影点最近的目标。这就是 flick 有"把元素甩出去"感觉的原因。

文档给出了苹果的精确投影函数（出自 Designing Fluid Interfaces 示例代码）：

// 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) 不是苹果实际使用的公式——请用上面的指数衰减形式。这也是优质 bottom-sheet 和轮播库（Vaul、Embla）的标准行为。

7. 空间一致性（Spatial Consistency）：对称路径、锚定原点

"If something disappears one way, we expect it to emerge from where it came."

• 进出走同一条路径。 从右侧滑入的面板必须向右滑出。"右边进、下面出"会显得割裂、令人困惑。
• 交互锚定在源头。 菜单、popover、sheet 应从触发它的元素处展开——把 transform-origin 设到触发器上，让按钮与内容的空间关系一目了然（与"popover 从触发器放大而非从自身中心放大"是同一个原点感知问题）。
• 可逆过渡要镜像缓动曲线，使去程与回程匹配（两个方向各用互为反函数的 cubic-bézier 控制点）。

8. 朝手势方向给出提示（Hint in the Direction of the Gesture）

人类会从轨迹预测终态。中间帧应该"预告"事物要去哪里——例如 Control Center 的模块"朝你的手指生长"。中间帧要指向结果，而不是盲目地插值过去。

9. 橡皮筋（Rubber-banding）：软边界

到达边缘时渐进抵抗，而不是硬停。硬停读起来像"卡死了"；连续阻力读起来像"还活着，只是这里没有更多内容了"。做法是应用一个随越界距离递增的阻尼。文档给出苹果的公式：

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

10. 手势设计细节（"手感"清单）

• Tap： touch-down 高亮（瞬时），touch-up 提交。目标周围加约 10px 迟滞/命中扩展，并允许"拖走又拖回来即取消"。
• Drag/swipe： 先要求一个小的移动阈值（迟滞，约 10px）再确认方向，然后 1:1 跟踪。仓库 Carousel 中的 DRAG_BUFFER 常量即对应这个"位置迟滞"，与 VELOCITY_THRESHOLD（500px/s）共同构成方向判定双阈值。
• 从第一次 move 起并行检测所有可能手势，意图明确后再果断取消落选者。避免只报告"最终状态"的识别器（swipeleft 类事件）——它们丢掉了连续反馈所需的跟踪数据。
• 最小化消歧延迟。 双击检测不可避免地延迟单击 tap；只在双击真实存在的场景支付这个成本。

11. 帧级平滑（Frame-level Smoothness）

平滑关乎帧里装了什么，而不只是帧率：

• 每帧位移变化保持在感知阈值之下，避免频闪（strobing）。
• 极快速运动时，微妙的运动模糊/拉伸比生硬的锐利拖影更能编码速度感。
• requestAnimationFrame 是 Web 上与显示器同步的时钟（对应苹果的 CADisplayLink）。只动画对合成器友好的属性——transform 和 opacity——在运动即将发生时用 will-change 提示浏览器。

12. 材质与景深（Materials & Depth）：半透明传达层级

苹果把半透明材质当作"悬浮的功能层"——建立结构但不抢焦点。Web 上用 backdrop-filter 近似。文档的六条规则：

• 导航/工具栏/sheet 做成半透明层（backdrop-filter: blur() + 半透明背景），让内容从其下滚动——而不是占用固定条带的不透明条。
• 材质重量编码层级： 更暗/更重的材质分隔结构性区域（侧边栏）；更轻的材质把注意力引向交互元素（按钮）。绝不在另一个半透明面上叠加浅色半透明面——可读性会崩塌。
• 更大的表面应读起来更"厚"： 更强的模糊 + 更深的阴影，对比小 chip。考虑上下文感知阴影——覆盖在繁忙/文字内容上时更重以制造分离，覆盖在素背景上时更轻。
• 用变暗聚焦，用分离保流程。 模态任务：表面配变暗 scrim，把背景推远/压低。并行、非阻塞面板：用半透明与偏移、不加 scrim，不断流。多层 sheet 时逐层渐进变暗并推远每一层父级。
• Vibrancy 保证文字在变化背景上的可读性。 在模糊/半透明表面上不要用扁平灰字——用更高对比度、稍重的字重和一点点字距增量。颜色放实底层，不要放半透明前景。
• 用滚动边缘效果替代硬分隔线。 不要 sticky header 下的 1px border；在浮动 UI 真正与内容重叠的地方，淡出一小片模糊/渐变遮罩。
• 让材质"物化"，而不只是淡入。 玻璃/模糊表面进出时同时动画 blur 半径与 scale，让表面读起来像"一块真实的材质到达"，而非一次纯不透明度淡入。

.toolbar {
  background: rgba(255, 255, 255, 0.6);
  backdrop-filter: blur(20px) saturate(180%);
  border-top: 1px solid rgba(255, 255, 255, 0.4); /* 亮色顶边 = 光打在材质上 */
}

这一风格在 react-bits 的展示站界面与 GlassSurface 组件、FluidGlass 组件 中有直接对应物——后者即"blur + 饱和度 + 流动高光"的液态玻璃实现。

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

来自 Designing Audio-Haptic Experiences 的三条规则：

1. 因果性（Causality）——必须明显是什么引发了反馈。在实际的因果事件（开关翻转、元素落位吸附）上触发，并让反馈"性格"匹配动作的物理质感。
2. 和谐性（Harmony）——视觉、声音、触觉必须同一帧触发。三者之间的延迟会摧毁错觉。别让 CSS 过渡滞后于音频/触觉（Vibration API）。
3. 效用（Utility）——只在挣得位置的地方加反馈。把触觉/声音留给有意义的时刻（成功、出错、提交、吸附）。过度反馈会训练用户忽略一切反馈。

14. 减动效与无障碍（Reduced Motion）

减动效不等于没有反馈——而是更温和、非前庭刺激的等价物。要响应三个独立信号并内建到组件中：

• prefers-reduced-motion: reduce —— 把滑动/弹簧/视差换成短的不透明度交叉淡入或静态过渡；去掉弹性/过冲；保留辅助理解的不透明度/颜色变化。
• prefers-reduced-transparency: reduce —— 让半透明面更"磨砂/实底"：提高背景不透明度，去掉模糊。
• prefers-contrast: more —— 近实底背景 + 明确、有对比的边框。

此外：避免整屏移动背景；避免缓慢循环振荡（接近 0.2 Hz / 约 5 秒一周期）；避免突兀的明暗跳变（dark↔light 主题切换要缓动）。大运动物体在飞行途中保持半透明；大幅重定位时让大表面先淡出、落位后再淡入。

@media (prefers-reduced-motion: reduce) {
  .sheet { transition: opacity 200ms ease; transform: none !important; }
}
@media (prefers-reduced-transparency: reduce) {
  .toolbar { background: white; backdrop-filter: none; }
}

这一点在 react-bits 中得到大面积印证：仓库源码中 ElasticMesh、PixelSwap、RippleDistortion 等数十个组件都内置了 prefers-reduced-motion 分支，说明减动效适配是组件交付的标配而非可选项。

15. 排版（Typography）：光学尺寸、字距、行距

苹果为"字随尺寸改变形状"而设计字体，同一纪律适用于 Web（出自 WWDC 2020 The Details of UI Typography）：

• 字距（tracking）是分尺寸的——绝不是一个值走天下。 大号展示文字要负字距（字越大显得间距越开）；小号文字要微正字距以保证可读性。固定 letter-spacing 在某处一定是错的。收紧标题，正文接近 0。
• 行高（leading）与尺寸成反比。 大标题紧凑，正文松散。对高升部/降部字母的脚本加大行高；对信息密集 UI 收紧。
• 用"字重 + 尺寸 + 行高"作为一套组合构建层级，而不只是尺寸。用字重强调——它增加存在感却不占更多空间。
• 尊重用户的文字大小设置（Dynamic Type）。让布局随文字一起缩放——间距用 rem/em 而非固定 px——这样放大字体不会撑破布局。
• 默认用平台系统字体，再考虑自定义字体；系统字体已内置光学尺寸、字距表和可读性调优。覆盖它必须有个理由。

:root { font: 100%/1.5 system-ui, sans-serif; } /* 正文：系统字体，舒适行高 */

.display {
  font-size: clamp(2rem, 5vw, 4rem);
  line-height: 1.05;        /* 大文字用紧凑行高 */
  letter-spacing: -0.02em;  /* 尺寸增大时用负字距 */
  font-optical-sizing: auto;
}

16. 设计基础：八大原则

上述动效与工艺最终服务于苹果的八大设计原则（Principles of Great Design，WWDC 2026）。文档要求把它们作为"推理时的名字"：

1. Purpose（目的）。 有意图地构建；决定不构建什么。每个功能都在索取用户的时间、注意力和信任——只把这笔预算花在回报之处。
2. Agency（自主权）。 让人保持控制：提供选择，不强迫单一路径。以"宽恕"托底——手误有便捷的撤销；确认对话框只留给真正破坏性且不可逆的动作（谨慎使用，滥用会训练用户无脑点掉）。
3. Responsibility（责任）。 站在用户利益行事。隐私：在对的时刻、只索取需要的、透明地询问。安全：预判误用与伤害——尤其涉及 AI（对过敏原感知的菜谱 App 不能建议有害食材）。加预览、确认与免责声明；风险大于价值的功能就砍掉。
4. Familiarity（熟悉感）。 建立在人们已知之上。隐喻既不许太直白也不许太抽象（垃圾桶=删除），并尊重隐喻的物理。保持一致：看起来一样的东西必须行为相同、位置相同（macOS 上关闭永远在左上），让人能预测下一步。只有在能证明更好时才打破熟悉模式——然后去测试，别想当然。
5. Flexibility（灵活性）。 为不同上下文、设备和能力范围设计。适配平台（iPhone = 快速触控；桌面 = 精确指针的深度工作流）与情境。包容性设计（年龄、语言、专业度、无障碍）。当单一布局无法服务所有人时，允许个性化——重排控件、隐藏用不上的东西。
6. Simplicity（简洁——不是极简主义）。 剥去不必要的让核心目的发光；把一切都埋进一个地方"看起来极简"但并不简单。简洁（平实语言、少行话、少步骤）且清晰（用层级——顺序、间距、对比——让最重要的东西最显眼）。每个元素都要挣得自己的位置；有时增加上下文反而简化（视频 scrubber 显示剩余时间）。先展示常用路径，高级选项放深一层。
7. Craft（工艺）。 毫不妥协的细节关注建立信任：漂亮的排版、适配明暗模式的颜色、清晰的图标、给予即时自然反馈的响应式动画。没有什么是随机的——每个间距、时长、对齐值都是你能为之辩护的刻意选择。抖动滚动、错位图标、旋转屏幕即破的布局，读起来就是"粗心"。工艺需要迭代与长期主义——随功能与硬件变化持续演进设计。
8. Delight（愉悦）。 是做好前七件事的结果，不是事后撒的彩纸。决定你希望用户感受到什么情绪（平静、自信、兴奋），并在每个决策中强化它。

服务于这些原则的战术规则：

• 反馈分四类： status、completion、warning、error。确认有意义的动作、暴露进行中的状态、在问题发生前预警、内联校验（而非提交时）。
• Wayfinding（寻路）。 每个屏幕都应回答：我在哪？我能去哪？那里有什么？我怎么出去？永远不困住用户。
• 分组与映射。 邻近即关系；把控件放在它影响的东西旁边，排列方式镜像它所改变的对象。如果需要一个标签来解释控件，说明映射很弱。
• 直接具体的命名胜过年经的泛化命名。 导航项用内容命名（"Progress"、"Library"），不用模糊的伞形词（"Home"）。具体性创造可预期性。

17. 流程（Process）

• 交互式原型——一个可交互 demo 值"百万个静态设计"。 你是在构建和把玩中发现界面的；可工作的原型还设定了一条具体的验收线，防止最终实现平庸化。
• 交互与视觉一起设计。"你不应该能分辨出哪一段是交互、哪一段是视觉。"动效不是像素完成之后加上去的一层。
• 在真实情境中与真实用户测试，并以新鲜的眼睛审查动效——用慢放/逐帧播放去捕捉全速下看不见的东西。

Quick Reference：速查表（文档原表，可直接作为项目 house style）

需求	技术	具体取值
默认 UI 弹簧	临界阻尼，无过冲	damping 1.0，response 0.3–0.4
动量 / flick 弹簧	欠阻尼，轻微回弹	damping ~0.8，response 0.3–0.4
手势 → 弹簧速度	交接释放速度	归一化时 gestureVelocity / (target − current)
Flick 落点	投影动量	current + (v/1000)·d/(1−d)，d ≈ 0.998
干净中断	从 presentation（实时）值开始	读取屏幕上的 transform
避免反向"撞墙"	重定向时携带速度	选择会混合速度的弹簧
可逆过渡	镜像缓动曲线	反函数 cubic-bézier
判定"反向还是提交"	用速度的符号而非位置	在释放时刻判定
1:1 拖拽	Pointer Events + capture	尊重抓取点偏移
反馈	pointer-down 时、持续	绝不在结束时才给
边界	橡皮筋，不硬停	渐进阻力
半透明 chrome	backdrop-filter 层	内容从其下滚动
字距	分尺寸，绝不固定	大字收紧（-0.02em），正文接近 0
减动效	交叉淡入，不滑动/不弹簧	@media (prefers-reduced-motion)

如何在 react-bits 中继续验证与实践

这份技能文档位于仓库的 AGENTS/SKILLS/ 目录——它是与 improve-animations、review-animations、find-animation-opportunities 并列的一组"动画工程"技能文档，专供 AI Agent 在构建或评审组件时引用。对开发者而言，最直接的实践路径是：

1. 以 Quick Reference 速查表 为自己的动效验收清单；
2. 用 Carousel（速度阈值 + 拖拽约束）、TiltedCard（独立轴弹簧）、Dock（紧凑弹簧参数 mass: 0.1, stiffness: 150, damping: 12）作为参照实现；
3. 在交付任何带手势的组件前，对照第 14 节补上 prefers-reduced-motion / prefers-reduced-transparency 分支——这也是仓库组件的普遍做法。

文档中引用的 WWDC 2018 Designing Fluid Interfaces 与 WWDC 2020 The Details of UI Typography 等演讲，提供了上述每一条规则的一手出处；仓库源码则证明这些规则并非纸面规范，而是被组件代码逐条兑现的实现纪律。