Semi UI：抖音现代设计系统 React 组件库安装与使用指南

官方信息

项目	内容
项目名称	Semi-UI（Semi Design）
开源方	抖音前端团队（DouyinFE）
代码仓库	DouyinFE/semi-design
官方网站	semi.design
npm 包	@douyinfe/semi-ui
开发语言	TypeScript / React
设计 Token	3000+
开源协议	MIT
更新状态	自 2019 年起稳定更新

Semi Design 官方图

项目背景：一个打通设计与研发的设计系统

Semi UI 是抖音前端团队开源的一套现代化、全面、灵活的设计系统与 UI 组件库，目标是连接 DesignOps（设计运营）与 DevOps（研发运维），帮助团队快速构建美观、一致、可维护的 React 应用。它不只是一个组件库，更是一整套从设计稿到代码、再从代码反哺设计的工作流：官方提供 Design to Code（D2C）能力，能把 Figma 设计稿在几秒钟内转换成真实可用的代码；同时也提供 Code to Design（C2D）能力，能根据不同主题自动生成对应的 Figma UI Kit，让设计与代码始终保持一致。

为什么这件事值得做？因为在很多团队里，「设计」和「研发」是两个交接频繁但又经常脱节的角色。设计师在 Figma 里画稿，研发照着稿手写 JSX 和 CSS，还原度全靠人盯；一旦设计稿改版，研发要手动改一堆样式，时间一长，线上的界面和设计稿就越差越远。Semi 想把这道鸿沟用工具填平：设计稿里用的就是 Semi 组件，转出来的代码也直接用 Semi 组件，两边天然一致，改版时只改 Token 或组件，两端同步更新。

这种双向打通是 Semi 区别于普通组件库的核心。在传统流程里，设计稿和代码往往是两套并行、容易走样的东西，设计师改了配色、研发没跟上，或者研发在代码里临时改了样式、设计稿上看不出来，久而久之产品视觉就会失控。Semi 通过 DSM（Design System Management）把设计 Token 统一管理起来，让设计和研发共享同一份 Token，从而从根上保证一致性。

除了组件本身，Semi 还在工程质量上下了很大功夫：它同时维护单元测试、端到端测试和视觉回归测试，视觉回归借助 Chromatic 平台来发现 UI 改动引起的视觉回归，端到端测试借助 Cypress 来保证关键交互链路不被破坏。这种多重测试体系，保证了这个被抖音大量业务使用的组件库在每次迭代时都不会轻易破坏现有业务。

核心特性（Features）

80+ 高质量组件：自 2019 年以来持续稳定更新，覆盖表单、导航、数据展示、反馈等绝大多数业务场景。
官方 Design to Code（D2C）：配合 Semi Figma 插件，几秒钟把 Figma 设计稿转成真实代码，支持多种输出格式。
Code to Design（C2D）：根据不同主题自动生成 Figma UI Kit，保持设计与代码一致。
完整的无障碍（A11y）支持：遵循 W3C 标准，为所有组件提供键盘交互、焦点管理和 ARIA 属性。
设计系统管理 Semi DSM：提供 3000+ Design Token，可快速把「Semi Design」定制成「Any Design」。
多语言国际化：支持数十种语言，同时支持时区和 RTL（从右到左）布局。
严格的质量保障：覆盖单元测试、端到端（E2E）测试和视觉回归测试。
TypeScript 编写：提供友好的静态类型支持，基于 Foundation/Adapter 架构，易读易贡献。
SSR（服务端渲染）兼容：可在 Next.js 等 SSR 框架中直接使用。
Web Components 兼容：提供完整的适配方案，更适合构建 SDK、浏览器插件等需要 DOM 隔离的场景。

这些特性里，最值得单独展开的是无障碍与国际化。无障碍方面，Semi 严格遵循 W3C 的 ARIA 规范，所有组件都支持键盘导航、焦点可见与焦点管理，屏幕阅读器也能正确朗读组件语义——这对内审要求较高的企业级产品尤其重要。国际化方面，它内置了数十种语言的文案，日期、时区、RTL 布局都一并处理，做海外业务时不用自己再写一套语言包。

另外，Semi 在架构上采用 Foundation/Adapter 分层：Foundation 负责组件逻辑，Adapter 负责与 React 的桥接，这种结构让它不仅易于阅读和维护，也为未来适配其他 MVVM 框架留下了空间。它对 Web Components 的兼容方案，则让你可以把 Semi 组件封装进 SDK 或浏览器插件里，而不用担心样式与宿主页面互相污染。

环境要求与安装

Semi-UI 是一个 npm 包，使用前提是项目里已经有 React 环境。三种主流包管理器任选其一：

npm install @douyinfe/semi-ui

yarn add @douyinfe/semi-ui

pnpm add @douyinfe/semi-ui

安装后即可按需引入组件。它支持 Chrome、Firefox、Safari、Edge 和 Electron 的最近两个大版本，其中 Edge 明确支持，现代前端项目基本都能直接使用。Semi 采用按需加载的设计，你只 import 用到的组件，打包体积就不会被未使用的组件撑大；样式方面跟随组件引入，不需要单独再引一份全量 CSS，配合构建工具时也能很好地做 tree-shaking。

使用方法

组件用法

下面是一个最小可运行示例：引入 Button 和 Form，渲染一个带输入框和提交按钮的表单。整个组件库的用法都和这个示例一样简单——从 @douyinfe/semi-ui 里按需 import 组件，然后像普通 React 组件一样使用。

import React from 'react';
import { createRoot } from 'react-dom/client';
import { Button, Form } from '@douyinfe/semi-ui';

const App = () => (
    <Form>
        <Form.Input field='name' initValue='semi design'></Form.Input>
        <Button htmlType='submit'>submit</Button>
    </Form>
);

const root = createRoot(document.querySelector('#app'));

root.render(<App />);

Semi UI 文档站提供了数百个可编辑示例和实时预览，推荐直接在文档站里动手试。从这个最小示例可以看出，Semi 的组件都是「声明式」的：你只要在 JSX 里写上组件标签和属性，表单字段、提交按钮的样式和交互就已经是一套经过打磨的设计语言，不需要自己再写 CSS。对于业务研发而言，这意味着大部分精力可以花在业务逻辑上，而不是反复调像素、对齐边框。

Design to Code 用法

安装 Semi Figma 插件，即可把 Figma 设计稿在几秒内翻译成真实代码。它支持多种输出格式：JSX + SCSS、Emotion/Tailwind，或者 JSON Schema DSL。在 Figma 的 Dev Mode 里选中某个图层，右侧就能直接得到对应的代码；也可以一键跳到 CodeSandbox 继续编辑，省去手动搬运样式的工作。

这套 D2C 能力的价值在于把「设计稿还原」这一最容易走样的环节自动化了：设计师在 Figma 里画好的间距、颜色、组件层级，插件会直接转成使用 Semi 组件的 JSX，研发复制过去就能用，从源头消除了「设计稿是一套、代码又是一套」的问题。

DSM 用法

借助 DSM，你可以基于 Semi UI 一键定义自己的设计系统。它提供超过 3000 个 Token，允许你配置从色板、字号到圆角、间距的每一个细节，并且在 Figma 和代码之间双向同步，始终保持一致。换句话说，Semi 不只是给你一套默认皮肤，而是给你一个可以持续运营的设计系统平台：品牌方换色、业务线定制、深浅色切换，都通过 Token 一次性完成，不需要逐个组件去改样式。

浏览器与平台支持

Semi UI 支持所有主流现代浏览器：Chrome、Firefox、Safari、IE/Edge 以及 Electron，其中 Chrome、Firefox、Safari、Electron 支持最近两个大版本，Edge 明确支持。对于 Electron 桌面端内嵌页面，Semi 也做了适配，可以直接用于桌面类应用。也就是说，无论是普通 Web 后台、移动端 H5，还是基于 Electron 打包的桌面客户端，Semi 都能覆盖，不需要额外引入一套兼容层。

图标、全局配置与生态

除了组件本身，Semi 还提供了一套独立的图标库（Semi Icons），配合组件一起使用；通过全局配置组件（ConfigProvider）可以统一设置文案语言、主题方向等全局行为。文档站还专门整理了 Design Tokens、暗黑模式、国际化等专题章节，以及一份持续更新的 CHANGELOG，方便你从某个版本升级时对照看有哪些破坏性变更。官方也会在 Twitter、Medium、Dev.to 等渠道发布版本动态和设计研发实践文章，背后还有 VisActor 提供数据可视化能力作为生态补充。

Semi 欢迎外部贡献者参与，仓库里有完整的 CONTRIBUTING 文档说明开发流程、如何提交 bug 修复与改进、如何构建和测试自己的改动。对于希望在企业内部推广设计系统的团队来说，Semi 不只是一个能直接用的组件库，更是一套可以照着搭建自己 DesignOps 体系的范本。它把「设计—研发」之间最容易扯皮的环节，用 Token、D2C、C2D 和一套严格的测试体系固定下来，让产品体验不再依赖某几个设计师或前端的个人功力。

常见问题（FAQ）

问：Semi-UI 和 Ant Design 有什么区别？ 答：Semi 是抖音团队开源的设计系统，最大特色是设计与研发双向打通的工作流——D2C 把设计稿转代码、C2D 把代码反哺成 Figma UI Kit，再加 DSM 统一管理 3000+ Token。它同样基于 React 和 TypeScript，适合看重设计一致性和研发效率的团队。

问：组件库支持 TypeScript 吗？ 答：支持，整个组件库就是用 TypeScript 编写的，类型定义完整，并且基于 Foundation/Adapter 架构，内部结构清晰，方便二次贡献。

问：服务端渲染（SSR）能用吗？ 答：可以，Semi UI 明确兼容 SSR，在 Next.js 等框架中可以直接使用，不会有 hydration 问题。

问：怎么做主题定制？ 答：通过 DSM 修改 Design Token，或者参考文档中的「定制主题」章节。Token 数量超过 3000，从全局色板到单个组件的细节都可以调整。

问：有没有暗黑模式和国际化？ 答：都有。文档站提供暗黑模式章节和国际化（locale）章节，支持数十种语言、时区和 RTL 布局。

问：如何加入官方用户群？ 答：可以通过仓库 README 中的飞书 / Lark 用户群链接加入，与官方团队和其他使用者交流。

问：Semi 支持哪些包管理器？ 答：npm、yarn、pnpm 三种都可以，安装命令完全一致，都是 @douyinfe/semi-ui 这一个包。

问：D2C 转出来的代码可以直接用吗？ 答：可以。插件支持输出 JSX + SCSS、Emotion/Tailwind，或者 JSON Schema DSL，转出来的就是标准的 Semi 组件用法；如果需要继续调整，还可以一键跳到 CodeSandbox 在线编辑。

问：这个项目的维护活跃度如何？ 答：Semi 自 2019 年起持续稳定更新，背后是抖音前端团队，同时维护着单元测试、E2E 测试和视觉回归测试体系，更新有保障。

问：开源协议是什么？商用是否免费？ 答：Semi UI 采用 MIT 协议，商用免费，几乎没有使用限制。

问：组件数量大概有多少？够用吗？ 答：官方提供 80 多个高质量组件，覆盖表单、导航、反馈、数据展示等常见业务场景，并且自 2019 年以来持续迭代，绝大多数中后台和营销活动页都能直接用。

问：Semi 支持暗色模式吗？怎么开启？ 答：支持，文档站有专门的「暗黑模式」章节。配合 Design Token 体系，暗色模式不是额外做一套皮肤，而是通过 Token 切换自动适配所有组件。

问：能不能把 Semi 组件用在浏览器插件或 SDK 里？ 答：可以。Semi 提供了与 Web Components 兼容的完整适配方案，考虑到了 DOM 隔离问题，适合构建 SDK、浏览器插件等不能污染宿主页面的场景。

问：官方有没有中文文档？ 答：有，文档站同时提供中英文版本，默认中文，示例、主题定制、国际化、FAQ 都有中文说明，国内团队上手没有语言障碍，也不需要额外翻译或查英文资料。

问：Semi 适合什么类型的项目？ 答：它最适合需要长期维护、并且对设计一致性有要求的中后台系统、营销活动页和前端组件化项目；如果团队同时有设计师在使用 Figma，再配合 D2C 插件，整套设计研发流程会顺畅很多，也能显著减少 UI 走样带来的返工。