跳转至

主题动效系统规范

{
  "paths": ["packages/core/src/theme/**", "packages/core/src/motion/**"]
}

意图

主题通过三个旋钮设定其动效的快慢与生动程度,以及是否面向所有人减少动效。同样的旋钮驱动 CSS 动效令牌和动画器的弹簧与曲线,且一起运行的动画会同时开始并同时落定。每个按使用场景设置的动效值都保持为内部值。

非目标

  • 不为主题提供按角色或按组件的动效设置。
  • 不放松 Reduce Motion:没有任何选项可以关闭请求了 design:reduced-motion DR1–DR4 的用户的该效果。
  • 不提供主题动效值的公开解析器(OQ1)。

公开契约

defineTheme({
  name: 'Brand',
  motion: {tempo: 1, character: 'standard', reducedMotion: 'system'},
});

需求

  • FR1 — 三个动效旋钮。 defineTheme 的 motion 接受 {tempo, character, reducedMotion}:
    • tempo 是数字,默认 1,限制在 0.75–1.5;它缩放所有动效时长;
    • character 为 'crisp'、'standard'(默认)或 'expressive';它选择入场和移动曲线及弹簧回弹。不提供连续回弹。没有任何 character 会把曲线变成弹簧,也不会播放平台测量的曲线;哪些动效使用弹簧、哪些播放曲线令牌由 spec:AST-094 FR45 决定;点击触发的展开和折叠,包括 animated-layout 滑动(spec:AST-105 FR4),播放曲线令牌;
    • reducedMotion 为 'system'(默认)或 'always';'always' 对所有人应用 design:reduced-motion DR1–DR3,'system' 遵循每个人的系统设置。没有任何值会放松 Reduce Motion。
  • FR2 — 这些旋钮生成 CSS 动效令牌。 主题的 --duration-* 令牌是其基础值乘以 tempo。character 只设置按任务命名的 --ease-entrance 和 --ease-move 令牌(在 tokens.stylex.ts 中声明)。现有退场效果读取的 --ease-standard 和默认值为 cubic-bezier(0.3, 0, 0.6, 0.6) 的 --ease-exit 在所有 character 下都保持不变,因此退场保持低调。当 tempo 为 1、character 为 'standard' 时,令牌保持其发布值:--duration-* 为 130、175、230、310、410、550、730、975 和 1300 ms,--ease-standard 为 cubic-bezier(0.24, 1, 0.4, 1);在 'standard' 下 --ease-entrance 和 --ease-move 等于 --ease-standard。'crisp' 和 'expressive' 下的曲线分别是纯减速曲线和带轻微过冲的曲线。
  • FR3 — 动画器的表从相同旋钮派生。 动画器的基础表,即 spec:AST-094 FR4 中的每个角色,都在源头处从主题的 tempo 和 character 派生:弹簧的持续时间按 tempo 缩放,character 按角色固定权重的一个倍数来偏移该角色的实测回弹:'standard' 不加任何偏移,'crisp' 和 'expressive' 分别将其向下和向上偏移;因此权重为零的角色(如退场、淡入淡出或全屏移动)在任何 character 下都保持其实测回弹。当 tempo 为 1、character 为 'standard' 时,每个角色都精确播放其测量值。弹簧保持其测量的物理特性,按 tempo 缩放,并由 character 塑形;它不跟随 CSS 持续时间或缓动的对应物。角色及其权重保持内部。
  • FR4a — 协调动画共享同一个时钟。 一起运行的动画同时开始并同时落定:它们要么播放相同的动效角色,要么 CSS 部分以弹簧的计算稳定时间为基准计时,而绝不会作为两条独立计时的曲线。这涵盖一个元素及其周围滑动的兄弟元素(spec:AST-105 的单一共享计时)、元素的入场和退场、面板及其遮罩、菜单的展开及其内容,以及 CSS 淡入淡出与 JavaScript 弹簧配对的情况,例如 MobileNav 的关闭以其计算持续时间为基准计时,BottomSheet 的遮罩其淡变持续时间为面板的计算稳定时间。当这一部分还必须逐帧跟随弹簧时(例如遮罩在触摸轻扫关闭时就是这样),它会将弹簧的进度作为 CSS linear() 缓动。Core 的 motion/linearEasing 会将该进度采样为 linear() 的 stop,每帧一个,供所有这样做的部分使用。动画器在脚本中逐步推进弹簧,而 CSS 本身没有弹簧计时,因此没有现有模块能为 CSS 部分提供这些 stop。
  • FR4 — 有些动效是刻意固定的。 tempo 和 character 不会影响手指跟随和拖拽动效、滚动动量和衰减、橡皮筋回弹、屏幕键盘的动效(spec:AST-099 FR8)、按压模型的时钟(其起始延迟、取消距离和点按闪光)、悬停意图延迟、手势阈值(spec:AST-002 FR3)、忙碌指示器(如 Spinner 和 Skeleton)的循环周期——它们读取主题在 tempo 缩放之前设置的持续时间,因此 MotionScaleConfig 仍会为它们计时——以及 200 ms 的 Reduce Motion 上限;tempo 可以缩短 Reduce Motion 的交叉淡变,但绝不会延长它。
  • FR5 — 现有动效配置继续可用。 defineTheme 的 motion 也接受现有的 MotionScaleConfig,且 expandMotionScale 和 MotionScale* 类型保持不变。MotionScaleConfig 继续生成其 CSS 持续时间令牌,且其隐含的 tempo 只驱动这些持续时间:除非主题自身设置了 tempo,否则动画器的表保持在 tempo 1,因此现有主题的渲染与之前完全相同,弹簧也不例外。显式的 MotionScaleConfig 字段和显式的 tokens 优先于 tempo 和 character;扩展主题逐字段继承:子主题未设置的 MotionScaleConfig 字段或旋钮保留其基础主题的值。适配规则可以像设置任何其他 motion 值一样设置 tempo 和 character(spec:AST-012 FR4);reducedMotion 设置在主题自身之上,因为其根标记没有条件形式。
  • FR6 — 服务端渲染获得相同的值。 主题是纯数据,主题工具在服务端运行。'system' 不添加主题 CSS:组件样式已经以 prefers-reduced-motion 作为减少动效的关键条件,因此服务端从不猜测,水合时也不会闪烁。'always' 标记主题的根,且每个以 prefers-reduced-motion 作为减少动效关键条件的组件样式,也会以该标记作为关键条件;动画器、每个读取 prefers-reduced-motion 的脚本(matchMedia 或 useMediaQuery 检查)以及每个以 when: {motion}(spec:AST-012 FR2)为关键条件的适配规则,都会将该偏好视为已设置。该标记只会增加:祖先的 'always' 会延伸到每个嵌套主题内部,嵌套主题可以添加 'always',但绝不能移除祖先的,因为没有任何东西会放松 design:reduced-motion DR1–DR3(DR2a)。服务端和客户端从主题解析出相同的动效值,且导入主题和动效模块不会触碰 DOM(architecture:theme-authoring-contract)。动画器只在动画启动时于客户端读取用户的 Reduce Motion 设置。
  • FR7 — 文档随功能一起发布。 动效、持续时间令牌和缓动令牌文档、主题模板、主题编写指南以及 architecture:theme-authoring-contract 会在实现落地之前描述这三个旋钮、固定列表和优先级。

当前状态影响

  • defineTheme 的 motion 扩展到在现有 MotionScaleConfig 之外接受这三个旋钮;现有主题的渲染与之前完全一致。
  • 在 reducedMotion: 'always' 发布之前,公开的 motion 类型没有 reducedMotion 字段,每个主题都像 'system' 那样遵循每个人的设置(即 architecture:theme-authoring-contract 中已知的缺口)。
  • 核心层新增了 --ease-entrance、--ease-move 和 --ease-exit,以及一个用于 reducedMotion: 'always' 的主题根标记;所有根据 prefers-reduced-motion 来键控减弱动效的组件样式也会同时键控该标记。Carousel 的分页、BottomSheet 的面板和 sheet 手势、Item 的滑动释放、MobileNav、AppShell、Chat、Markdown 的流式揭示、BottomSheet 的键盘滚动,以及 animated-layout 的滑动动画——这些在脚本中读取偏好的行为也会遵循该标记;以 when: {motion} 键控的适配规则同样如此(spec:AST-012)。
  • design:reduced-motion 新增了 DR2a:主题可以为所有人减弱动效。
  • Spinner 和 Skeleton 会在 tempo 缩放它们之前读取各自的循环时长(FR4),因此它们在所有现有主题下的时序不变;component:Spinner 的 FR3 和 component:Skeleton 的 FR4 对此作了说明。
  • BottomSheet 的 sheet 和 scrim 共用 --duration-medium;当 sheet 以 springs.settle 稳定时,其 scrim 的淡入淡出采用该弹簧的稳定时间(FR4a)。
  • spec:AST-094 的 FR1、FR4 和 DEC-15、design:reduced-motion 的 DR2a、spec:AST-012 的 FR4(reducedMotion 仍归根节点所有)、architecture:theme-application 的 INV1('always' 会到达嵌套的 provider)、architecture:theme-authoring-contract(内部 motion 解析器)、component:Button 的 FR15(其释放淡出通过 --duration-exit 跟随 tempo,而 --duration-exit 引用的是按 tempo 缩放的时长)、草案 design:motion 的 DR3,以及 spec:AST-090 均已修订以保持一致。

验证

契约 验证 代表性状态 变更或失败预期
FR1, FR2 对生成的 CSS 进行主题单元测试 每个 tempo 边界和 1;每个 character;reducedMotion 的两种取值;没有 motion 某个 token 偏离其公式、已发布的 token 在默认值下发生变化、退出曲线发生变化,或某个值超出 clamp 范围,则失败
FR3 测试 CSS token 和动画器的表是否源自相同的旋钮值 每个角色在默认值和每个旋钮值下的状态;一个设置 tempo 或 character 的适配规则 某个角色在默认值下偏离其测量值、某个角色忽略其跟随的旋钮,或某个 weight-0 角色的弹跳随 character 变化,则失败
FR4a 在每个旋钮值下对每对配对动画进行浏览器测试 一个元素及其滑动中的兄弟元素、一个元素的进入和退出、一个 sheet 及其 scrim、一个菜单的展开和内容、一个带弹簧的 CSS 淡入淡出 结束时间相差超过一帧的配对动画失败
FR4 每个固定项的单元测试 手指跟踪、动量、橡皮筋效果、键盘、按压和悬停时钟、循环、Reduce Motion 上限;Spinner 和 Skeleton 在每个 tempo 下的循环 某个固定项随 tempo 或 character 移动,或交叉淡入淡出超过 200 毫秒,则失败
FR5 使用已发布配置的主题测试 一个 MotionScaleConfig 主题、显式 token、一个扩展主题;一个设置 tempo 或 character 的适配规则 现有主题的输出发生变化,或某个旋钮覆盖显式字段,则失败
FR6 服务端渲染测试和导入检查 对每个 reducedMotion 取值进行服务端渲染;导入主题和动画模块;在用户关闭系统动画偏好时使用 'always',并应用于所有依赖 prefers-reduced-motion 的组件;在 'always' 主题下嵌套一个子主题 预期失败:在导入时或服务端访问 DOM、为 'system' 生成主题 CSS、发生 hydration 变化,或组件样式、脚本读取器或 when: {motion} 规则在 'always' 下忽略根标记,或嵌套主题在祖先的 'always' 下恢复动画
FR7 文档审查 每个列出的文档 缺少旋钮、固定列表或优先级规则的文档失败

决策日志

DEC-1 —— 主题的运动由三个旋钮控制;按角色的表格保持内部

参考: spec:AST-108/DEC-1 决策者: cixzhang, 2026-10-26

主题作者可以设置动画的速度感和活泼感,以及是否为所有人减少动画;很少有人需要按使用场景区分不同的值。推荐采用三个特征档位,而非连续弹跳,作为与旋钮配套的建议。三个旋钮从同一组值驱动 CSS token 和 JavaScript spring,而测量出的按角色值保持内部。本决定取代 spec:AST-094 DEC-11 中恰好针对这三个旋钮的“全部内部”规定。

已否决:为每个运动组提供一个公开 token。

未决问题

  • OQ1 —— 主题的运动值是否会获得公开的解析器。 (human-design) 未决。resolveThemeMotion 是内部的。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx