OpenMetadata UI 圆角设计规范深入解析--om-radius-*Token 体系与边框圆角最佳实践【免费下载链接】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本篇技术指南围绕 OpenMetadata 开源仓库中设计系统基础规范文档 radius.md 展开系统讲解 OpenMetadata UI 边框圆角border-radiusToken 的完整刻度表、三层架构、离刻度历史值与正确用法。读者读完将掌握在既有.less/.css组件中应如何使用var(--om-radius-*)替代硬编码像素值、如何规避yarn token-audit的告警以及如何理解 Token 与上游设计原语之间的映射关系。一、为什么需要一套圆角 Token 体系在 OpenMetadata UI 中圆角Radius与颜色、字号、间距、阴影一样属于设计系统的基础原语Foundation。直接书写border-radius: 8px;这样的裸像素值看似简单却会带来三方面问题视觉不一致不同组件各自为政圆角取值随意无法形成统一的视觉语言不可主题化无法随品牌或暗色主题全局调整任何变更都需要逐文件修改无法被工具审计仓库中的yarn token-audit脚本会把裸border-radius值标记为警告强制开发者回归 Token 化写法。这正是 radius 规范文档存在的意义它定义了完整的圆角刻度表并规定了 Token 的分层引用方式让组件代码只依赖语义化的--om-radius-*变量而不是具体的像素数字。从仓库中 specs/README.md 可以看到这套--om-*Token 层服务于遗留LegacyAnt Design Less 技术栈新工作优先使用 UntitledUI Tailwind 的tw:工具类但该层在迁移期间仍在持续维护是所有存量 UI 的圆角标准。二、标准圆角刻度表Scaleradius 规范文档给出了完整的圆角刻度表共 9 个标准 Token。下表在继承原文档的基础上补充了各 Token 的推荐使用场景说明Token值用途--om-radius-none0直角square如无圆角的容器或分隔场景--om-radius-xs2px微妙圆角subtle几乎不可感知的轻微倒角--om-radius-sm4px输入框、小型控件、标签inputs, small controls, tags--om-radius-md6px按钮buttons--om-radius-lg8px卡片、菜单、浮层cards, menus, popovers--om-radius-xl12px大卡片、模态框large cards, modals--om-radius-2xl16px更大尺寸的容器级圆角--om-radius-3xl24px超大圆角容器--om-radius-full9999px胶囊、头像、圆形控件pills, avatars, circular controls这套刻度在仓库源码 src/styles/tokens.css 中有精确对应实现例如/* -- Radius -- */ --om-radius-none: var(--radius-none, 0px); --om-radius-xs: var(--radius-xs, 2px); --om-radius-sm: var(--radius-sm, 4px); --om-radius-md: var(--radius-md, 6px); --om-radius-lg: var(--radius-lg, 8px); --om-radius-xl: var(--radius-xl, 12px); --om-radius-2xl: var(--radius-2xl, 16px); --om-radius-3xl: var(--radius-3xl, 24px); --om-radius-full: var(--radius-full, 9999px);注意这里的声明模式每个--om-*Token 都以var(--radius-*, 原始回退值)的形式引用上游原语即优先取上游 Token取不到时回退到原始像素值。这种写法保证了即使上游globals.css的--radius-*未加载UI 依然能正常渲染。三、离刻度值Off-scale Values与历史遗留 Token规范文档明确指出当前实际使用的 Token 中存在若干不在标准刻度表上的离刻度值off-scale values例如--om-radius-10、--om-radius-999以及小数形式的--om-radius-3_23.2px。这些值存在于 tokens.css 的生成块中属于历史遗留或局部特殊需求。在 src/styles/tokens.css 中Extended radius — off-scale values in use 注释下集中列出了这批扩展 Token/* Extended radius — off-scale values in use. */ --om-radius-1: 1px; --om-radius-3: 3px; --om-radius-3_2: 3.2px; --om-radius-5: 5px; --om-radius-7: 7px; --om-radius-9: 9px; --om-radius-10: 10px; --om-radius-13: 13px; --om-radius-14: 14px; --om-radius-15: 15px; --om-radius-18: 18px; --om-radius-20: 20px; --om-radius-30: 30px; --om-radius-200: 200px; --om-radius-999: 999px;与之对应specs/tokens/token-reference.md 的 Radius (24) 一节共收录了 24 个圆角 Token 的完整清单包括 9 个标准 Token 与 15 个扩展/离刻度 Token可直接作为查阅手册。关于离刻度值规范给出了一条关键约束--om-radius-999与--om-radius-full都能产生胶囊pill效果但优先使用--om-radius-full。原因在于--om-radius-full是标准刻度成员语义更明确、可被统一管理而--om-radius-999只是历史上为了足够大而随手写出的数值。对新代码而言应尽量收敛到标准刻度减少离刻度 Token 的进一步扩散。四、三层架构从上游原语到组件使用radius 规范将整个圆角 Token 体系划分为三个层级这与 specs/README.md 中描述的遗留 Less 系统分层完全一致Layer 1 globals.css 上游原语 --radius-*来源为 openmetadata/ui-core-components 是圆角数值的唯一事实来源source of truth Layer 2 --om-* 项目别名层tokens.css引用 Layer 1 Token 并带原始回退值 离刻度 / 遗留值直接持有原始值 Components (.less/.css) 组件层通过 var(--om-*) 引用 Layer 2绝不书写裸像素值逐层解读Layer 1 ——globals.css定义上游--radius-*原语以及--color-*、--text-*、--shadow-*等是整个设计系统的数值源头。规范文档中写为 globals.cssupstream--radius-*。Layer 2 ——--om-*别名层在 tokens.css 的:root中通过--om-radius-*: var(--radius-*, raw)的形式建立项目别名。组件只认识这一层不直接依赖上游命名。Components —— 组件层在组件样式.less/.css中写作border-radius: var(--om-radius-lg);实现只看语义、不看数值的解耦。此外遗留 Less 桥接文件 src/styles/variables.less 同样承担 Token 定义职责存量variable用法不算违规但新代码应优先使用var(--om-*)。五、正确用法与反例Do / Dontradius 规范用一段精简的 Less 代码示例明确了正反两种写法这也是每个组件开发/审查时必须遵守的硬性规则/* DO */ border-radius: var(--om-radius-lg); border-radius: var(--om-radius-full); /* DONT */ border-radius: 8px; border-radius: 50%; /* prefer --om-radius-full for pills; 50% only for true circles */要点拆解优先使用 Token所有圆角必须通过var(--om-*)引用禁止在组件中硬编码8px之类的像素值否则会触发yarn token-audit告警。胶囊pill用--om-radius-full需要胶囊按钮、头像等两头圆的形态时使用--om-radius-full9999px它能让任意尺寸的元素都呈现完美胶囊形。50%仅限真圆border-radius: 50%只应出现在本来就是圆形的控件如圆形头像、圆形状态点上用于确保正圆若元素是矩形或胶囊形用百分比会随宽高比例产生椭圆此时应改用--om-radius-full。六、用yarn token-audit验证圆角合规原文档提到裸border-radius值会被yarn token-audit标记为警告。在 package.json 中可以看到该工具的真实入口token-audit: node scripts/token-audit.js, token-audit:report: node scripts/token-audit.js --report,在openmetadata-ui/src/main/resources/ui目录下运行yarn token-audit # 常规审计报告硬编码 / 离刻度用法 yarn token-audit:report # 生成详细审计报告其工作逻辑可理解为扫描组件样式中的border-radius声明凡是未通过var(--om-*)引用的裸值包括直接像素值、50%等都会被标记。因此在提交涉及圆角的 UI 改动前运行一次审计是保证代码符合设计规范的最直接手段。七、与相邻基础规范的关系圆角不是孤立存在的基础原语它与 Elevation阴影/层级共同塑造组件的空间层次。radius 规范文档末尾的交叉引用指向两个文件已转换为仓库根目录相对路径elevation.md阴影与层级规范与圆角配合定义卡片、菜单、浮层的视觉身份token-reference.md完整的--om-*Token 参考手册含全部 24 个圆角 Token是组件开发时的速查表。同目录下的其他基础规范color.md、spacing.md、typography.md、motion.md与本文共同构成 OpenMetadata UI 设计系统的基础层建议在编写 UI 代码前先通读 specs/README.md 了解整体架构。八、实践小结在 OpenMetadata UI 中处理边框圆角时请遵循以下决策路径标准场景从 9 个标准 Tokennone/xs/sm/md/lg/xl/2xl/3xl/full中按用途表选择如按钮用--om-radius-md、卡片用--om-radius-lg、模态框用--om-radius-xl胶囊与圆形胶囊一律用--om-radius-full只有真正的圆形控件才允许border-radius: 50%遗留代码若在存量代码中发现离刻度值如--om-radius-10、--om-radius-3_2理解其历史来源新代码不要继续扩散--om-radius-999与--om-radius-full等价时优先选用后者提交前验证在openmetadata-ui/src/main/resources/ui下运行yarn token-audit确保没有裸border-radius告警查阅手册需要确认任意 Token 的确切取值时查阅 token-reference.md 的 Radius 章节。通过遵循上述规范OpenMetadata UI 的圆角体系得以保持全局一致、可主题化、可审计这也是设计系统 Token 化改造的核心目标。【免费下载链接】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），仅供参考