OpenMetadata 设计系统 Motion 规范实战动画时长、缓动曲线与 z-index 层级令牌【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadataOpenMetadata 前端在从 Ant Design Less 向 UntitledUI Tailwind 迁移的过程中将动效时长、缓动曲线与层叠层级统一收敛为--om-*设计令牌。本文基于仓库中的 motion 规范文档完整梳理时长、缓动、z-index 三类令牌的定义与语义阶梯并结合 tokens.css 与各组件.less文件中的真实用法给出可复制、可审计的动效编写规范帮助你在 OpenMetadata UI 开发中写出不产生yarn token-audit告警的动效代码。1. 背景motion 令牌在双层设计系统中的位置OpenMetadata 的设计系统规范openmetadata-ui/src/main/resources/ui/specs/是机器与人都可读的规格说明编写或修改任何 UI 代码前都应先阅读对应 spec。当前仓库同时维护两套栈栈样式方式令牌审计命令Go-forward推荐UntitledUI Tailwindtw:工具类 /var(--color-*)yarn tw-auditLegacy已弃用Ant Design Lessvar(--om-*)yarn token-auditmotion.md 隶属于 legacy 侧的 foundations基础规范与 color.md、spacing.md、typography.md、radius.md、elevation.md 平级。legacy LESS 体系的令牌分层如下见 specs/README.mdLayer 1 globals.css 上游原语--color-*、--radius-*、--shadow-* 等 来自 openmetadata/ui-core-components是事实来源 Layer 2 --om-* 项目别名定义于 tokens.css引用 Layer 1 令牌并带原始值兜底 Components (.less/.css) 通过 var(--om-*) 引用 Layer 2绝不写裸 hex / pxmotion 相关令牌就定义在 Layer 2tokens.css 中组件层通过var(--om-duration-*)、var(--om-ease-*)、var(--om-z-*)消费。遗留的 Less 桥接文件 variables.less 也是令牌定义文件但新工作应优先使用var(--om-*)。2. 时长Durations语义阶梯与迁移保留值motion 规范把时长分为两类新工作使用的语义命名阶梯以及迁移时从代码库中完整保留的精确数值令牌。2.1 语义时长阶梯新工作使用Token值适用场景--om-duration-instant100ms微反馈如图标颜色变化--om-duration-fast150mshover、小的状态变化--om-duration-base200ms默认过渡--om-duration-slow300ms抽屉drawer、展开的面板--om-duration-slower500ms大型布局过渡这五个语义令牌在 tokens.css 中有明确实现--om-duration-instant: 100ms; --om-duration-fast: 150ms; --om-duration-base: 200ms; --om-duration-slow: 300ms; --om-duration-slower: 500ms;设计意图清晰反馈越细微、交互越轻量时长越短。100ms 只够完成颜色变了这一级感知而抽屉、面板这类大块头动效需要 300ms 让用户跟上布局变化。2.2 迁移保留的精确时长不要改变时序迁移过程中代码库里出现的每一个精确时长都被原样保留为--om-duration-ms形式如--om-duration-120、--om-duration-240写入生成的令牌块中避免迁移期间任何组件的动效时序发生变化。从 tokens.css 可以看到完整的保留清单Token值--om-duration-100100ms--om-duration-120120ms--om-duration-150150ms--om-duration-160160ms--om-duration-180180ms--om-duration-200200ms--om-duration-220220ms--om-duration-240240ms--om-duration-250250ms--om-duration-300300ms--om-duration-450450ms--om-duration-500500ms--om-duration-10001000ms--om-duration-14001400ms--om-duration-15001500ms--om-duration-16001600ms--om-duration-20002000ms--om-duration-30003000ms这些值在 token-reference.mdMotion 一节共 26 个令牌中同样有完整登记。规则这些--om-duration-ms只用于保持既有组件时序不变新写代码一律使用 2.1 节的五个语义命名阶梯不要在组件里再引入新的裸毫秒值。2.3 源码中的真实用法迁移保留值在现有.less中被广泛引用例如app.less 中transition: var(--om-duration-300) ease-in;484 行、animation: highlight-fade var(--om-duration-3000) ease-out forwards;519 行用于高亮渐隐动画card.less 中transition: all var(--om-duration-200) ease;121 行menu.less 中transition: all var(--om-duration-200) ease-in-out;130 行entity-version-time-line.less 中transition: display var(--om-duration-300) ease-out;49 行radio.less 中transition: all var(--om-duration-300) ease;52 行。可以看到迁移后组件里不再出现0.2s、300ms之类的裸值全部通过var()引用令牌这正是yarn token-audit所要求的形态。3. 缓动曲线Easing三个标准贝塞尔曲线Token值--om-ease-standardcubic-bezier(0.4, 0, 0.2, 1)--om-ease-incubic-bezier(0.4, 0, 1, 1)--om-ease-outcubic-bezier(0, 0, 0.2, 1)三者均定义于 tokens.css--om-ease-standard: cubic-bezier(0.4, 0, 0.2, 1); --om-ease-in: cubic-bezier(0.4, 0, 1, 1); --om-ease-out: cubic-bezier(0, 0, 0.2, 1);3.1 三个曲线的语义standard标准cubic-bezier(0.4, 0, 0.2, 1)即 Material Design 的默认减速加速曲线。开始快速进入、结尾柔和收束适合绝大多数 UI 过渡是默认首选。in加速cubic-bezier(0.4, 0, 1, 1)曲线后段陡峭元素冲入或冲出适合强调进入感或离场感如元素从屏幕边缘快速滑入。out减速cubic-bezier(0, 0, 0.2, 1)曲线前段陡峭、后段平缓元素减速停稳适合出现类动效。3.2 代码库中的自有曲线bespoke curves规范明确规定代码库中自有的cubic-bezier(...)曲线保持原样不强行收编为令牌缓动不属于令牌分类范畴。也就是说迁移时审计工具对这类曲线不做强制替换但新写代码应优先使用上述三个命名缓动而不是在组件里随手编写新的贝塞尔值。4. z-index 语义阶梯堆叠层级z-index 不属于 Motion 范畴但规范将其顺带记录于此以便查阅——它是动效尤其抽屉、弹层、气泡这类浮层动效落地时的必备配套知识。迁移过程同样保留了代码库中每一个精确的 z-index 值为--om-z-n例如--om-z-5、--om-z-999、--om-z-1001等token-reference.md 中 z-index 一节共登记 31 个令牌。新工作则使用下面的语义阶梯Token值层级--om-z-base0常规文档流in-flow--om-z-raised1抬升元素--om-z-docked10sticky 子标题--om-z-sticky100sticky 页头--om-z-dropdown1000下拉框、下拉选择--om-z-overlay1050抽屉、遮罩scrim--om-z-modal1500模态框--om-z-popover2000气泡、tooltip--om-z-toast9000toast 通知--om-z-max9999最顶层实现在 tokens.css--om-z-base: 0; --om-z-raised: 1; --om-z-docked: 10; --om-z-sticky: 100; --om-z-dropdown: 1000; --om-z-overlay: 1050; --om-z-modal: 1500; --om-z-popover: 2000; --om-z-toast: 9000; --om-z-max: 9999;为什么用语义阶梯而不是裸数字裸数字1000无法表达这是一个下拉层而var(--om-z-dropdown)自解释且全局一致。数值阶梯按数量级递进0 → 1 → 10 → 100 → 1000 → 1050 → 1500 → 2000 → 9000 → 9999每一层之间预留了扩展空间避免日后出现1 压不住的魔数堆叠。组件中的既有用法示例app.less 中z-index: var(--om-z-5);412 行、z-index: var(--om-z-10);416 行、z-index: var(--om-z-400);420 行、z-index: var(--om-z-1001);908 行drawer.less 中z-index: var(--om-z-1);41、45 行om-rdg.less 中z-index: var(--om-z-999);69、98 行profiler.less、radio.less 中z-index: var(--om-z-0);。这些迁移保留的精确--om-z-n保证浮层顺序与迁移前完全一致只有新写的层级才使用语义阶梯。5. Do / Dont最小可运行代码范式规范给出了最直接的正反对照原文完整保留/* DO */ transition: all var(--om-duration-base) var(--om-ease-standard); z-index: var(--om-z-dropdown); /* DONT */ transition: all 0.2s ease; z-index: 1000;正确写法时长用var(--om-duration-base)缓动用var(--om-ease-standard)层级用var(--om-z-dropdown)——全部通过令牌引用任何一处都有全局唯一的语义与取值改动令牌即可全站同步。错误写法0.2s ease与1000都是裸值。它们的问题在于0.2s无法被审计工具识别为--om-duration-200/--om-duration-base对应的语义时长ease也不是三个标准缓动曲线之一z-index: 1000无法表达语义层级且与--om-z-dropdown1000值相同却不可维护裸值会触发yarn token-audit告警而原始时长值在审计中被标记为 warning警告进而影响 CI 门禁。6. 令牌审计与生成工具链motion 令牌不是孤立的文档概念而是被工具链强制约束的工程实践。相关脚本定义在 package.json命令作用yarn token-auditlegacy扫描 CSS/LESS 中的硬编码值有任何错误即退出码 1可接入 CIyarn token-audit:report全量分组清单每个值及其建议替换的令牌yarn token-migrateCodemod 把裸值自动改写为var(--om-*)安全、幂等yarn token-gen重新生成tokens.css的生成块与 token-referenceyarn token-test扫描器/codemod 引擎的单元测试motion.md 开头明确指出原始时长raw durations会被yarn token-audit标记为 warning。结合 specs/README.md 的说明审计的硬性失败error针对硬编码颜色与硬编码间距而非常规值如小数尺寸、特殊时长属于 warning——这正是--om-duration-ms这类非常规时长被单独保留并允许存在的原因它们不是错误但不应出现在新代码中。对 motion 而言CI 语义就是新代码不允许再引入任何裸时长、裸缓动、裸 z-index既有特殊时长以--om-duration-ms形式受控保留。7. 与其他规范的交叉引用令牌总表全部--om-*令牌共 804 个含 31 个 z-index 令牌与 26 个 motion 令牌见 token-reference.md规范索引motion 在 specs/README.md 的 Contents 表中与 color、spacing、typography、radius、elevation 并列统一由yarn token-audit守护上游来源--om-*令牌引用 Layer 1 的 globals.css 原语其事实来源是openmetadata/ui-core-components提供的--color-*、--shadow-*等见 specs/README.md 的分层说明。8. 小结动效令牌的使用决策速查时长新工作从instant / fast / base / slow / slower五个语义值中选择base200ms是默认不要新写裸毫秒值--om-duration-ms仅用于保持迁移前时序。缓动优先standard进入强调用in收束强调用out代码库自有的cubic-bezier(...)可原样保留但不作为新工作的模板。z-index新层级按base → raised → docked → sticky → dropdown → overlay → modal → popover → toast → max阶梯取值--om-z-n仅服务存量代码。落地检查提交前运行yarn token-audit确认零 error并避免引入新的 warning需要自动化改写时可借助yarn token-migrate。遵循以上规范你写出的动效代码将具备全局一致的时序手感、可语义化维护的层级结构并且能顺畅通过 OpenMetadata 的令牌审计门禁。【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考