Semi Design 设计资源与 Semi Toolbox 插件：从 Figma UI Kit 到 DSM 主题同步的设计研发协作指南

本文围绕 Semi Design 官方「设计资源」体系展开，系统梳理其面向设计师与开发者开放的 UI Kit 资源包、Semi Toolbox 插件的四大提效能力（内容填充、表格生成、数据可视化生成、Semi 主题同步），并结合仓库内的主题包源码与插件实现，讲清楚“设计资源 → Design Token → 主题包 → 工程化接入”的完整链路。读完本文，你将掌握如何在 Figma 中借助 Semi 资源快速还原界面、生成真实组件代码，以及如何将 DSM 主题无缝同步到代码工程。

设计资源概览：为设计师与开发者提供同一套语言

Semi Design 的设计资源体系定位明确：让设计师与开发者在同一套视觉语言下高效协作。无论你是社区用户还是 ByteDance 内部设计师，都可以在 Design Resources 设计资源（英文版见 index-en-US.md）中找到适合自己的资源包。

整套资源的核心价值体现在两点：

1. 组件与规范的统一：UI Kit 中封装了 Semi 完整的组件库与设计规范，设计稿中的组件与线上代码中的组件一一对应，避免“设计一套、代码一套”的割裂；
2. 从设计稿直达代码：配合 Semi Toolbox 插件与 D2C（Design to Code）能力，设计稿可以还原为可运行的 React JSX 与 CSS 代码，设计资产的复用效率大幅提升。

UI Kit：覆盖主流设计场景的组件资产包

Semi Design UI Kit 提供了完整的组件库与设计规范，覆盖按钮、表单、表格、导航等主流设计场景，帮助设计师快速搭建高质量界面，便于团队协作与资产复用。官方按用户群体分为两个版本：

目标用户	资源名称	获取方式
社区用户	Semi Design library	在 Figma Community 搜索「Semi Design library」即可找到（文档中登记的 Community 文件，可直接在线打开与复制）
ByteDance Design 用户	Semi Design library – ByteDance	在 ByteDance Design 内部资源库中搜索「Semi Design Base」相关文件

说明：原始文档中的直接跳转链接维护在 content/advanced/design-source/index.md 中，需要直达链接时请以仓库内文档为准。

UI Kit 与代码库的对应关系可以从仓库结构中得到印证：packages/semi-ui 下每个组件目录（如 button、table、form）都有配套的 tsx 组件实现与 jsx 兼容层，设计稿中的每个组件都能在 packages/semi-ui 中找到对应的 React 实现，这正是“设计资源可还原为代码”的基础。

Semi Toolbox：为设计师提效的 Figma 功能插件

Semi Toolbox 是 Semi 团队打造的一款 Figma 功能插件，核心目标是为设计师提效，同时打通设计与研发。插件共提供四类能力：

1. 内容填充（Content Filling）
2. 表格生成（Table Generation）
3. 数据可视化生成（Data Visualization Generation）
4. Semi 主题同步（Theme Synchronization）

插件按分发渠道分为三个版本：

渠道	说明
社区用户版	面向所有 Figma 社区用户，在 Figma Community 搜索「Semi Toolbox」即可安装
ByteDance Design 版	面向字节跳动内部设计师，功能最全
国际化版本	面向海外用户，界面与资源为英文环境优化

不同渠道版本在功能上存在差异，例如「表格生成」当前仅在 ByteDance Design 版与国际化版中支持（详见下文），选择版本时需要留意。

📝 内容填充：一键批量填充，深度适配 Semi 组件

内容填充是 Semi Toolbox 的基础能力：一键批量填充带格式的文本与图片，且深度适配 Semi 组件。

在实际设计流程中，设计师经常需要为同一套界面反复填充演示数据（如用户头像、昵称、金额、状态标签等）。Semi Toolbox 将这一过程自动化：

• 支持带格式文本的批量填充，保持字体、字号、颜色等样式属性不丢失；
• 支持图片批量填充，可快速替换头像、封面等位图内容；
• 填充逻辑对 Semi 组件（如 Avatar、Tag、List、Table 等）做了专门适配，填充后组件结构与样式依然成立，不会出现错位或溢出。

配合仓库中的演示数据可以更好地理解其使用场景：cypress/fixtures/example.json 与 cypress/fixtures/placeholder.json 展示了典型的数据驱动填充模式；而 packages/semi-ui 中 Avatar、Tag、List 等组件的实现则说明了插件“深度适配组件”背后的依据——填充内容本质上是对这些组件 Props 所驱动的数据结构进行批量赋值。

📊 表格生成：基于 Semi Table 组件快速搭建专业表格

表格生成能力借助 Semi Table 组件 快速搭建专业表格，轻松满足数据呈现需求。设计师在 Figma 中框选区域后，插件可以按列结构自动生成符合 Semi Table 规范的数据表格，包括表头、列宽、行高、对齐方式等细节。

需要注意的使用限制：

⚠️ 当前表格生成能力仅在 ByteDance Design 版以及国际化版插件中支持，社区版暂未开放该能力。

Semi Table 组件的实现位于 packages/semi-ui/table，其在代码侧支持列配置、排序、筛选、固定列、虚拟滚动等丰富能力（对应 packages/semi-foundation/table 中的 Foundation 逻辑）。这意味着插件生成的表格不只是“画出来的静态图形”，而是携带了列结构与数据的结构化对象，后续可以通过 D2C 能力直接还原为带 columns 配置的 <Table /> 代码。

📈 数据可视化生成：打通 Semi DV 样式库，同步输出代码

数据可视化生成能力打通 Semi DV 样式库，同步输出代码，实现设计开发无缝衔接。

这里的「Semi DV」指 Semi 体系下的数据可视化（Data Visualization）样式库。该能力让设计师无需手工绘制图表，而是基于真实的数据配置生成图表，并在生成时同步产出对应代码——图表在 Figma 中是可视化图形，在代码侧则对应可运行的图表组件实例。

仓库中与数据可视化强相关的佐证是 packages/semi-illustrations 与 semi-icons 等图形资产体系（见 packages/semi-illustrations），它们与 Semi Toolbox 一样遵循“一份设计资产、多端消费”的理念。对于图表类组件（如 Progress、Rating、Skeleton 等带数据语义的展示组件），其代码实现均可在 packages/semi-ui 中找到对应目录，便于设计师按图索骥、开发者按需取用。

🎨 Semi 主题同步：DSM 主题一键同步，统一设计风格

主题同步是 Semi Toolbox 与 Semi DSM（Design System Manager，设计系统管理站点） 联动的能力。设计师在 DSM 中配置好主题后，可以通过插件将主题快速同步到 Figma 设计稿中，让设计稿始终与线上代码使用同一套 Design Token，避免“设计稿用一套色、代码用另一套色”的偏差。

主题同步背后的 Design Token 体系

主题同步的本质是 Design Token（设计变量）的同步。Semi Design 提供了 3000+ 个 Design Token，将设计中的基础元素与具体样式解耦（详见 Tokens 设计变量）：

• 基础色：基于品牌色动态生成，包含 160 个颜色、16 个不同色相的梯度色盘，可通过 DSM 配置品牌色后动态生成新的基础色盘；
• 功能色：从基础色盘中引用，应用于界面背景、文本图标、链接、描边等元素，包括 primary、secondary、tertiary、info、success、warning、danger 等语义色；
• 全局变量：涵盖圆角、字体排版、描边、阴影、布局间距等视觉语言。

正是因为界面样式全部由 Token 驱动，修改某个 Token 的默认值即可完成整套产品 UI 的迭代，这也是主题同步能够“一键生效”的根本原因。

主题包的落地形态：semi-theme-default

主题同步的最终产物是 npm 主题包。仓库中 packages/semi-theme-default 就是 Semi 的默认主题包，其 README.md 说明了目录结构与分层原则：

├── scss
│   ├── _font.scss     // 字体相关 scss mixin
│   ├── _palette.scss  // 全局原始色盘（css variable）
│   ├── global.scss    // 全局 Design Token（css variable，含明暗模式）
│   ├── index.scss     // 入口
│   ├── mixin.scss     // 额外 mixin（如阴影）
│   └── variables.scss // 尺寸、间距、z-index、字体相关 token

分层原则是：运行时无需切换的（如尺寸间距）由 Sass 变量承载；需要运行时切换的（如暗色模式相关颜色）由 CSS 变量承载。这套机制保证了主题既可以编译期替换，也支持运行时动态切换，是 Semi 暗色模式（详见 dark-mode）与多主题能力的底层支撑。

从主题包到工程：插件的消费方式

DSM 生成的主题包发布到 npm 后，工程侧通过构建插件消费。以 Webpack 为例，semi-theme-loader.ts 中明确展示了加载逻辑：

• 未指定主题时默认使用 @douyinfe/semi-theme-default（semi-theme-loader.ts 第 9 行）；
• 指定 theme 后，loader 会解析 ${theme}/scss/local.scss 作为组件级变量入口（第 29 行），并通过 @import "~${theme}/scss/local.scss" 注入（第 36 行）。

这与 定制主题 文档中的三种接入方式一一对应（优先级由低到高）：

1. 通过 DSM 生成的 npm 主题包（theme 字段）；
2. 通过项目内本地 Scss 文件（include 字段）；
3. 通过插件参数传入键值对覆盖（variables 字段）。

若在定制主题时修改了组件级变量，则需要用如下配置使改动生效：

{
    theme: {
        name: '你的主题npm包名称',
        include: '~你的主题npm包名称/scss/local.scss'
    }
}

设计到代码的闭环：与 D2C 联动

Semi Toolbox 解决的是“设计稿里快速产出高质量内容与真实组件”，而 Semi D2C（Design to Code） 解决的是“设计稿如何转成代码”（详见 Design to Code 设计稿转代码）。

两者组合形成完整闭环：

1. 设计师侧：用 UI Kit 搭建界面 → 用 Semi Toolbox 填充内容、生成表格/图表、同步主题；
2. 开发者侧：在 Figma DevMode 中启动 Semi 插件，点击图层直接获取对应代码，支持 React JSX + CSS 输出；
3. 主题侧：DSM 同步保证设计稿与代码使用同一套 Design Token，转码结果与线上样式天然一致。

Semi D2C 基于 Figma to Code 的结构化信息转换路线，原生支持设计系统组件级转码识别，可识别出 Semi 组件的 Props；同时借助多模态 AI 大模型对基础代码做进一步改写（子组件拆分、列表 map render、className 语义化、jsx → tsx 类型补充）。需要说明的是，OpenApi 与 NodeSdk 两种调用方式目前仅字节内部可用，社区版本暂未提供该能力。

小结

Semi Design 的设计资源体系是一套以 Design Token 为核心、Figma 为协同载体、代码工程为最终落点的完整协作方案：

• UI Kit 提供与代码一一对应的组件资产与设计规范；
• Semi Toolbox 提供内容填充、表格生成、数据可视化生成、主题同步四项提效能力；
• DSM + Design Token 保证设计稿、Figma 插件与线上代码三者共享同一套视觉变量；
• 主题包 + 构建插件 将设计资产以 npm 包形式接入 Webpack / Vite 等工程（semi-webpack / semi-vite）。

无论是个人开发者快速搭建演示界面，还是团队级的设计系统治理，都可以在这套资源体系上找到对应的工具与依据。安装插件后，建议从仓库文档 Design Resources 设计资源 中登记的官方链接开始体验，并结合 D2C 示例设计稿与 Codesandbox 对照 快速验证“设计稿 → 代码”的还原效果。