主题动效系统规范¶
意图¶
主题通过三个旋钮设定其动效的快慢与生动程度,以及是否面向所有人减少动效。同样的旋钮驱动 CSS 动效令牌和动画器的弹簧与曲线,且一起运行的动画会同时开始并同时落定。每个按使用场景设置的动效值都保持为内部值。
非目标¶
- 不为主题提供按角色或按组件的动效设置。
- 不放松 Reduce Motion:没有任何选项可以关闭请求了
design:reduced-motionDR1–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-094FR45 决定;点击触发的展开和折叠,包括 animated-layout 滑动(spec:AST-105FR4),播放曲线令牌;reducedMotion为'system'(默认)或'always';'always'对所有人应用design:reduced-motionDR1–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-094FR4 中的每个角色,都在源头处从主题的tempo和character派生:弹簧的持续时间按tempo缩放,character按角色固定权重的一个倍数来偏移该角色的实测回弹:'standard'不加任何偏移,'crisp'和'expressive'分别将其向下和向上偏移;因此权重为零的角色(如退场、淡入淡出或全屏移动)在任何 character 下都保持其实测回弹。当tempo为 1、character为'standard'时,每个角色都精确播放其测量值。弹簧保持其测量的物理特性,按tempo缩放,并由character塑形;它不跟随 CSS 持续时间或缓动的对应物。角色及其权重保持内部。 - FR4a — 协调动画共享同一个时钟。 一起运行的动画同时开始并同时落定:它们要么播放相同的动效角色,要么 CSS 部分以弹簧的计算稳定时间为基准计时,而绝不会作为两条独立计时的曲线。这涵盖一个元素及其周围滑动的兄弟元素(
spec:AST-105的单一共享计时)、元素的入场和退场、面板及其遮罩、菜单的展开及其内容,以及 CSS 淡入淡出与 JavaScript 弹簧配对的情况,例如 MobileNav 的关闭以其计算持续时间为基准计时,BottomSheet 的遮罩其淡变持续时间为面板的计算稳定时间。当这一部分还必须逐帧跟随弹簧时(例如遮罩在触摸轻扫关闭时就是这样),它会将弹簧的进度作为 CSSlinear()缓动。Core 的motion/linearEasing会将该进度采样为linear()的 stop,每帧一个,供所有这样做的部分使用。动画器在脚本中逐步推进弹簧,而 CSS 本身没有弹簧计时,因此没有现有模块能为 CSS 部分提供这些 stop。 - FR4 — 有些动效是刻意固定的。
tempo和character不会影响手指跟随和拖拽动效、滚动动量和衰减、橡皮筋回弹、屏幕键盘的动效(spec:AST-099FR8)、按压模型的时钟(其起始延迟、取消距离和点按闪光)、悬停意图延迟、手势阈值(spec:AST-002FR3)、忙碌指示器(如 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-012FR4);reducedMotion设置在主题自身之上,因为其根标记没有条件形式。 - FR6 — 服务端渲染获得相同的值。 主题是纯数据,主题工具在服务端运行。
'system'不添加主题 CSS:组件样式已经以prefers-reduced-motion作为减少动效的关键条件,因此服务端从不猜测,水合时也不会闪烁。'always'标记主题的根,且每个以prefers-reduced-motion作为减少动效关键条件的组件样式,也会以该标记作为关键条件;动画器、每个读取prefers-reduced-motion的脚本(matchMedia或useMediaQuery检查)以及每个以when: {motion}(spec:AST-012FR2)为关键条件的适配规则,都会将该偏好视为已设置。该标记只会增加:祖先的'always'会延伸到每个嵌套主题内部,嵌套主题可以添加'always',但绝不能移除祖先的,因为没有任何东西会放松design:reduced-motionDR1–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