设计变量 - Semi Design Next

为什么要使用 Design Token

Design Token 设计变量实际上是将设计中的基础元素与具体的样式进行解耦。

对于设计师来说，如果产品的风格需要迭代更新，比如需要更新危险的功能色，即 color-danger，只需要修改其对应的颜色默认值，既可以完成整套产品的 UI 迭代。

对于研发来说，为了配合产品风格的更新迭代，使用 Design Token 时可以更快速地完成所有组件的样式更新，而无需一处处地进行修改，这也是为什么在开发的过程尤其需要注意使用变量而不是固定的数默认值。如果产品的风格有多个平台共用的话，也能事半功倍。

特别地，对于有暗色模式需求的平台，需要使用 Semi Design Next 的颜色变量才能实现一键切换明暗色的效果。因此这里向大家详细地介绍 Semi Design Next 的 Design Token 体系以及如何使用它们。

基础色

包含 160 个颜色在内的，16 个不同色相的梯度色盘。通常情况下，我们用使用基础色中的颜色来进一步定义功能色。

颜色转换

功能色

从基础色盘中引用，应用在包括界面背景，文本图标，链接，描边在内的各类用户界面元素上。

主要颜色 - primary

用户界面主强调色及各交互态颜色，通常用于主操作按钮等

次要颜色 - secondary

第三颜色 - tertiary

用户界面中非强调色及各交互态颜色，通常用于常规、非强调功能操作按钮等

信息 - info

通常用于表达客观、中立信息，在带有上述语义的场景下使用

成功 - success

通常用于表达成功、完成、开启状态，在带有上述语义的场景下使用

警示 - warning

通常用于表达警告、不安全状态，在带有上述语义的场景下使用

危险 - danger

通常用于表达危险状态，在带有上述语义的场景下使用

AI - general

用于 AI 场景的背景色，字体颜色

AI - purple

用于 AI 相关的次要场景的背景色，字体颜色

AI - background

用于 AI 场景的背景色

文本与图标颜色 - text

四个不同层级的文本/图标颜色，依次代表产品界面中最主要、次主要、稍次要和最次要的内容

链接色 - link

用于产品中超链接的文本

背景色 - bg

应用中各级背景色，包括容器、菜单、导航栏等。在暗色模式下，我们通常用背景色来区分前后层级

填充色 - fill

对于一个元素，如果其所处的容器背景颜色不固定，且这个元素的填充色与最上层背景色的对比度比较小，使用填充色作为 backgroundColor，确保这个元素不会“融于”某一级别背景颜色中，如表单控件。

描边色 - border

界面中带有描边属性的颜色

禁用态 - disabled

用于界面中各类表达禁用的元素填充，如背景、文本、描边、填充等

常量色 - static

界面中不跟随主题及明暗模式切换的颜色

拟阴影色 - shadow

浅阴影，通过 border 模拟的扁平阴影效果，主要用在 Table 组件

字体排版

字体排版用来传达信息内容，并界面看起来有秩序

字号

决定不同层级文本的大小

字重

决定不同层级文本的粗细

字体

应用中各级文本使用的字体，为减少打包体积，默认英文字体 Inter 需要单独引入

业务侧如果想使用，需要在你的 CSS 中增加font-face声明（不自带在Semi中，是由于该字体略大，默认加载可能会影响业务首屏速度），由业务自行决定是否需要使用

@font-face {
    font-family: 'Inter';
    src: url('/assets/fonts/Inter-Regular.ttf') format('truetype');
}

@font-face {
    font-family: 'Inter-Bold';
    src: url('/assets/fonts/Inter-Bold.ttf') format('truetype');
}

圆角

使用圆角来描述容器与界面元素的轮廓，从一定程度决定产品的视觉调性

阴影

阴影通常用来表达界面元素的层级，阴影越重的元素距离用户越近

尺寸

尺寸变量被应用在各个组件及内部元素中，用来调整控件的大小、描边的粗细等

高度

描边尺寸

间距

间距变量被应用在各个组件内部，或组件与组件之间，用来调整产品整体的密集和紧凑程度

z-index

用来描述界面元素的前后顺序关系

动画

尚未支持的变量

目前，Semi 尚未支持以下类别的全局变量，如果你有相关需求，可以通过issue进行反馈，详细描述你的预期需求，我们会在评估后进行处理

段落行高 line height

字间距 letter spacing

媒体查询 media query

定制

本页列出的 --semi-* CSS 变量是 Semi 的全局定制入口，在应用自己的样式中覆写即可，不需要编译插件或主题包：

:root {
    --semi-color-primary: var(--semi-violet-5);
    --semi-border-radius-medium: 8px;
}

亮色值写在 :root 上，暗色值写在 [theme-mode='dark'] 上，见暗色模式。
Semi 的样式位于 @layer semi 中，应用中不分层的 CSS 规则总是优先，可以直接覆盖某个组件的具体样式，不需要 !important。
使用 Tailwind 时，引入 @fibrous/semi-ui-react/tailwind.css（Vue 为 @fibrous/semi-ui-vue/tailwind.css）后，这些变量会映射为 Tailwind 的主题值（如 bg-semi-color-primary）。
组件文档中的 Design Token 表列出的是组件内部的 Sass 变量，不能覆写。