组件级 Token
自定义组件样式
更新时间: 9/1/2023, 6:00:28 PM

组件样式定制

设计变量介绍

Semi Design 将所有组件表现层的样式都进行了抽象，将过往通过硬编码方式声明的 CSS 属性，都抽象成了 Design Token。

什么是 Design Token (设计变量)？

具体说来，Design Tokens是一种视觉原子化的设计系统，它将视觉控件和界面属性重新梳理归纳进行语义化命名，代替前端代码中的复杂代码（例如十六进制的颜色代码），这样可以方便设计师进行统一的管理和扩展，保证产品的一致性，也大大提升开发效率。

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

💁 对于研发
对于研发来说，为了配合产品风格的更新迭代，使用 Design Token 时可以更快速地完成所有组件的样式更新，而无需一处处地进行修改，相比于使用CSS侵入式修改样式，使用Design Token进行样式定义，可以做到样式与 DOM结构解耦。最大程度避免DOM结构变动后导致的自定义CSS失效。
这也是为什么在开发的过程尤其需要注意使用变量而不是固定的数默认值。如果产品的风格有多个平台共用的话，也能事半功倍。我们只需发布一次主题包，即可完成多个应用的风格更新。

除此之外，对于有暗色模式需求的平台，使用 Semi Design 的颜色变量可以快速实现一键切换明暗色的效果。

publish

哪些样式可以被定义为 Design Token

理论上，凡是可以用描述视觉样式都可以通过 Design Token 的方式来定义，比如 颜色 / 字体 / 描边 / 阴影 等等...

Design token: { 颜色 , 间距 , 字体 , 字号 ... 一切样式描述 }

结合一些最佳实践，Semi Design 目前已经将 颜色 / 字体排版 / 圆角 / 阴影 / 尺寸 / 间距 / Z-Index 作为设计变量进行抽象并提供定制的能力，

对于这部分的内容可以查看 设计变量文档 了解这些 Design Token 在 Semi Design 中的用法。

查看组件设计变量

Semi 除了有全局级别的设计变量外，每个组件也有自己的设计变量。通过组件级别设计变量，你可以单独定制某个组件的表现样式。

查看所有可修改的变量

在 DSM 中，当你切换至 组件页时， 可以点击右上方「查看设计变量」 查看当前组件所有可配置的 Design Token

token1

另外在 组件开发文档中，我们也提供了针对每个组件的设计变量，支持按照颜色、字体排版、圆角、间距、阴影等维度查询，并标注了不同变量的作用域。用户可以根据不同的样式定制需求，查询对应的变量，并快速复制到编辑器中.

token1

查看组件某一特定形态下应用的设计变量

当你希望查看/修改某个特定条件下，组件的样式时（例如不同校验状态下 Input 的样式配置）

  1. 找到对应的组件 Demo 用例，

inspect-4

  1. 按住 Command ⌘ 键（MacOS）或 Ctrl 键（Windows系统）

inspect-5

  1. 在左侧 Demo 区中选择你期望修改的元素，点击选择
  2. 此时右侧操作面板会自动根据点击元素，筛选出该状态下正在应用所有可修改的 Token，你可以按照实际需求进行修改
  3. 可以通过上方撤回按钮，对上一操作步骤进行回退

修改组件设计变量

Semi DSM 提供了两种交互方式，用以修改组件级的 Design Token

通过 Inspect 方式修改组件 Token

无需输入代码，直接点击组件区域右上角的「改样式」按钮即可选择样式进行修改，所有与组件元素有关的token都可以通过该方式进行修改。

inspect-1

可以通过按住Command⌘（Ctrl on windows）+ 鼠标悬浮组件的具体元素过滤到希望改动的组件token，提升修改组件token的效率

inspect-2

在下方有撤回和重做的按钮，可以根据需要进行调整

inspect-3

通过 Code 编辑器方式修改组件 Token

如果你是研发角色，我们提供了 Code 编辑器 方式对 组件级 Token 进行修改。直接以 key/value 的方式对样式进行修改的方式你可能会更加熟悉

🌰 例如，当我们希望定制 Input 组件的 背景色、圆角、文本颜色属性时

// 原有的默认配置
$color-input_default-bg-default: var(--semi-color-fill-0);    // 输入框背景颜色 - 默认
$radius-input_wrapper: var(--semi-border-radius-small);       // 输入框圆角大小
$color-input_default-text-default: var(--semi-color-text-0);  // 输入框文本颜色 - 默认

我们可以在 Code 编辑器中，声明我们具体想应用的值。它将覆盖组件原有的默认配置。

// 你新设置的配置
$color-input_default-bg-default: #FFFFFF;      // 输入框背景颜色 - 白色
$radius-input_wrapper: '6px';                  // 输入框圆角大小
$color-input_default-text-default: black;      // 输入框文本颜色 - 黑色

左侧为组件的 Design Token 命名，右侧为该变量具体的值。 每配置一个属性后，记得需要以 ';' 结尾;

  • 颜色类变量：允许设置为全局颜色类 Token，或者任意合法的 css value值，例如 rgba、hex色值、hsl色值、hwb色值
$color-input_default-bg-default: var(--semi-color-bg-2);         // 功能色 Token
$color-input_default-bg-default: rgba(var(--semi-indigo-0), 1);  // 基础色 Token 
$color-input_default-bg-default: rgba(247, 233, 247, 1);         // rgba 色值 
$color-input_default-bg-default: #ED4545;                        // hex 色值
  • 圆角、尺寸、间距、描边类变量：允许直接设置数字型值，或者合法的 Semi 全局圆角、尺寸、间距、描边类Token
$radius-input_wrapper: 6px;
$radius-input_wrapper: var(--semi-border-radius-small);

实时预览效果

对单个组件进行预览

当你在右侧操作面板中对 组件级 Token 进行修改时，左侧 Demo 区中的样式即可实时进行预览
我们尽可能将组件定制流程中，涉及到的组件状态及用例都进行了枚举展示，上下滑动可查阅更多使用例子

preview-demo

在现有的页面模板中进行预览

当前阶段，我们提供了在发布主题后，在主题商店中内置的模板预览的能力。

p-page

在任意基于 Semi 打造的 Web 应用中预览

在任意基于 Semi 打造的 应用中，我们都可以进行主题预览，例如 Semi Design 官网站点。我们可以加载任意已发布的主题，将其应用在 Semi Design 文档站点上。详细操作可查阅 主题商店-在线上应用预览

theme-switch

同步到 UiKit 中

当你完成了对组件级 Token 的修改后，你可以将其同步到 UiKit 中，以便在后续的设计工作中，直接使用你修改后的组件样式。在 Figma 中同步组件 Token