Semi Design

抖音前端与 UED 团队设计系统，企业级 React 组件库，3000+ Design Tokens 支持深度主题定制

技术简介说明

Semi Design 是由字节跳动抖音前端与 UED 团队开发并开源的企业级 React 组件库。作为字节跳动内部大规模使用的 UI 解决方案，Semi Design 经过抖音等核心产品的验证，具有极高的稳定性和成熟度。

Semi Design 的核心竞争力在于其 3000+ Design Tokens 系统和 DSM（Design System Manager） 设计系统管理能力。开发者无需 CSS 知识即可灵活定制主题样式，实现全局或局部的品牌定制。同时，Semi Design 独创了 Foundational/Adapter 架构范式，将逻辑层与 DOM 操作分离，为多框架适配提供了优雅的架构方案。

截至 2026 年，Semi Design 在 GitHub 上拥有超过 10,000 颗 Star，累计发布 304 个版本，NPM 包 @douyinfe/semi-ui 持续活跃更新。项目已推出 AI 专属组件系列，紧跟前端智能化趋势，是国内最具创新力的组件库之一。

基本信息

• 官网：https://semi.design
• GitHub：https://github.com/DouyinFE/semi-design
• NPM：https://www.npmjs.com/package/@douyinfe/semi-ui
• License：MIT
• 最新版本：v2.88.2（2025 年 11 月发布）
• 主要维护者/公司：字节跳动 / 抖音前端与 UED 团队（DouyinFE）
• GitHub Stars：~10.1k ⭐
• 总发布版本：304 次
• 总提交数：4,960+ commits
• React 版本支持：>= 16.8（React 19 适配中）

快速上手

安装

# npm
npm install @douyinfe/semi-ui
 
# yarn
yarn add @douyinfe/semi-ui
 
# pnpm
pnpm add @douyinfe/semi-ui

基础配置

Semi Design 的样式引入方式灵活，支持按需加载：

// 方式一：全量引入样式
import '@douyinfe/semi-ui/dist/css/semi.min.css'
 
// 方式二：使用 unocss / tailwind 等工具时，可单独引入组件样式
import '@douyinfe/semi-ui/essentials/index.css'

如需自定义主题，可通过 DSM 平台生成主题包：

# 安装 DSM CLI
npm install @douyinfe/semi-dsm -g
 
# 或直接在平台生成
# 访问 https://semi.design/dsm

最小示例

import React from 'react'
import { Button, Toast } from '@douyinfe/semi-ui'
import '@douyinfe/semi-ui/dist/css/semi.min.css'
 
function App() {
  return (
    <Button
      theme="light"
      type="primary"
      onClick={() => Toast.success('欢迎使用 Semi Design!')}
    >
      Hello Semi
    </Button>
  )
}
 
export default App

核心概念与架构

架构设计

Semi Design 采用独创的 Foundational/Adapter 架构范式：

┌──────────────────────────────────────┐
│          应用层 (Application)         │
├──────────────────────────────────────┤
│        Adapter 层（框架适配器）        │
│   负责 DOM 操作、事件绑定、渲染       │
├──────────────────────────────────────┤
│       Foundational 层（逻辑基础）      │
│   纯逻辑、状态管理、业务规则          │
├──────────────────────────────────────┤
│        Design Tokens（设计令牌）       │
│   3000+ 变量，颜色/字体/间距/圆角...  │
└──────────────────────────────────────┘

• Foundational 层：纯逻辑实现，不依赖任何 DOM API，理论上可运行在任何 JavaScript 环境
• Adapter 层：负责与具体 Web 框架（React）的适配，处理 DOM 操作和渲染

主题系统

• 3000+ Design Tokens：覆盖颜色、字体、间距、圆角、阴影等全方位设计变量
• DSM（Design System Manager）：可视化的设计系统管理平台
• 多主题共存：支持全局主题和组件级主题覆盖
• 暗色模式：内置暗色主题，支持自动切换

核心特性

• 80+ React 组件：覆盖基础、输入、导航、展示、反馈等全品类，满足企业级开发需求
• 3000+ Design Tokens：业内领先的设计令牌体系，通过 DSM 平台可视化管理
• AI 组件内置：提供 AIIcon、AIButton、AITag、AIFloatButton、AIChatInput、AIChatDialogue 等 AI 专属组件
• 暗色模式：自动暗色模式支持，提供 CLI 一键迁移工具
• 国际化支持：内置 10+ 语言的全球本地化方案（LocaleProvider）
• 无障碍支持：组件遵循 WAI-ARIA 规范，支持键盘导航
• Design to Code：Figma 插件支持设计稿直接生成 React 代码，样式输出支持 SCSS、Tailwind、Emotion 格式
• SSR 兼容：完整支持服务端渲染（Next.js / Remix 等）
• RTL 支持：支持从右到左布局，适配阿拉伯语等 RTL 语言
• TypeScript 严格支持：完全基于 TypeScript 构建，提供精确的类型提示
• Web Components 兼容：可在 Shadow DOM 中运行，适合微前端场景
• Plus 组件扩展：CodeHighlight、Markdown、Lottie、Chat、HotKeys、DragMove 等扩展组件

生态图

核心生态

设计工具

社区生态

• 在知乎、掘金等国内社区有较高的推荐度
• 被列为 2025/2026 年推荐的 React 组件库之一
• 字节跳动内部大规模使用验证

适用场景

• 企业中后台系统：Semi Design 的核心定位，80+ 组件覆盖所有常见后台需求
• 大型 SaaS 产品：3000+ Design Tokens 支持深度品牌定制，适合多品牌 SaaS
• 国际化产品：内置多语言支持和 RTL 布局，适合出海产品
• AI 驱动的应用：内置 AI 专属组件，快速构建 AI 对话、AI 助手等界面
• 微前端架构：支持 Shadow DOM / Web Components，适合微前端场景
• 设计驱动的团队：DSM 平台和 D2C 能力打通设计与开发的工作流
• 暗色模式产品：内置暗色模式支持，适合需要夜间模式的产品

开发与工程化

开发流程

# 克隆仓库
git clone https://github.com/DouyinFE/semi-design.git
cd semi-design
 
# 安装依赖
npm install
 
# 启动开发服务器（Storybook）
npm run dev
 
# 运行测试
npm run test
 
# 构建
npm run build
 
# Lint 检查
npm run lint

自定义主题开发

# 1. 使用 DSM CLI 创建自定义主题
npx @douyinfe/semi-dsm init my-theme
 
# 2. 编辑主题变量
# 在生成的配置文件中修改 Design Tokens
 
# 3. 编译主题
npx @douyinfe/semi-dsm build
 
# 4. 引入自定义主题
import './semi-theme/index.css'

Design to Code 工作流

Figma 设计稿
    ↓ (Semi D2C 插件)
生成 React 代码
    ↓ (选择样式格式)
SCSS / Tailwind / Emotion
    ↓
集成到项目中

按需加载配置

使用 webpack / vite 的 tree-shaking 自动按需加载：

// vite.config.js - 无需额外插件，自动支持 tree-shaking
export default {
  // Semi Design 组件自动按需引入
}

性能与安全

性能特点

• 按需加载：支持 tree-shaking，未使用的组件不会被打包
• Foundational/Adapter 分离：纯逻辑层可独立测试和优化
• 虚拟滚动：Table、Select 等组件支持虚拟滚动
• 懒加载：部分组件支持动态导入

性能优化建议

• 使用按需引入而非全量引入
• 大表格场景开启虚拟滚动
• 合理使用 React.memo 避免不必要的渲染
• 在 Next.js 中使用 SSR 时注意 hydration 性能

安全注意事项

• Semi Design 不直接处理 HTML 字符串，天然防御 XSS
• dangerouslySetInnerHTML 使用时需对内容进行消毒
• 表单组件内置基础的输入校验，复杂校验需自定义
• 定期更新依赖，关注安全公告

技术对比

与同类组件库对比

优势分析

• AI 组件独特：是目前唯一内置 AI 专属组件的主流组件库
• 设计令牌体系：3000+ Design Tokens 在国内组件库中领先
• D2C 工作流：Figma 到代码的完整链路，提升设计-开发协作效率
• 字节内部验证：在抖音等亿级用户产品中验证，稳定性有保障

劣势分析

• 社区规模不及 Ant Design
• 部分高级文档以中文为主，国际化程度有限
• 组件 API 较多，学习曲线相对较陡

最佳实践

主题定制最佳实践

import { ConfigProvider } from '@douyinfe/semi-ui'
 
// 全局主题配置
const globalConfig = {
  // 组件级样式覆盖
  prefixCls: 'custom',
}
 
function App() {
  return (
    <ConfigProvider {...globalConfig}>
      <YourApplication />
    </ConfigProvider>
  )
}

表单最佳实践

import { Form, Toast } from '@douyinfe/semi-ui'
 
function MyForm() {
  return (
    <Form
      onSubmit={(values) => {
        Toast.success('提交成功')
        console.log(values)
      }}
      onChange={(values) => {
        console.log('表单变化:', values)
      }}
    >
      <Form.Input field="username" label="用户名" rules={[{ required: true }]} />
      <Form.Input field="password" label="密码" type="password" rules={[{ required: true }]} />
      <Form.Checkbox field="remember" label="记住我" />
      <Button htmlType="submit">提交</Button>
    </Form>
  )
}

AI 组件使用示例

import { AIChatInput, AIChatDialogue } from '@douyinfe/semi-ui'
 
function AIApp() {
  return (
    <div>
      <AIChatDialogue
        messages={chatMessages}
        onSend={(message) => handleSend(message)}
      />
      <AIChatInput
        placeholder="输入消息..."
        onSubmit={(value) => handleSubmit(value)}
      />
    </div>
  )
}

常见陷阱

• 避免全量引入图标：使用按需引入图标方式减少包体积
• DSM 主题与代码主题同步：确保 DSM 平台配置与代码中的变量保持一致
• React 19 兼容：当前 React 19 适配仍在进行中，生产环境建议使用 React 18
• Form 字段命名：field 属性是表单数据提交的 key，确保命名规范

技术局限与边界

已知限制

1. React 19 适配中：v2.88.x 开始兼容 React 19，但完全适配仍在推进
2. 部分组件 API 较重：Form、Table 等复杂组件的配置项较多
3. 移动端组件独立：移动端需要单独使用 @douyinfe/semi-mobile，不与 React 版共享
4. 社区生态相对集中：第三方插件和扩展相对较少

不适用场景

• 纯移动端应用（需使用 Semi Mobile）
• 对组件库体积有极致要求的项目（Design Tokens 系统较大）
• 需要使用大量第三方扩展的场景

迁移注意事项

• 从其他组件库迁移时，注意表单 API 的差异（Semi 使用 field 而非 name）
• 样式定制方式与 Ant Design 的 Less 变量不同，需要适应 Design Tokens 体系
• 建议渐进式迁移，先迁移基础组件再迁移复杂组件

学习资源

官方资源

• Semi Design 官方文档
• GitHub 仓库
• DSM 设计系统管理平台
• Design to Code
• GitHub Wiki

教程与文章

• Semi Design 快速上手
• Semi Design 组件文档
• 字节跳动 Semi Design 开源之路

社区资源

• GitHub Issues
• GitHub Discussions
• 知乎 - Semi Design 相关讨论
• 掘金 - Semi Design 专栏

2026 年现状

版本状态

• 最新版本：v2.88.2（2025 年 11 月发布）
• NPM 最新发布：2026 年 5 月 22 日仍有包发布，持续维护中
• React 19 适配：v2.88.x 系列已开始 React 19 兼容适配
• 总版本数：304+ releases，4,960+ commits

发展趋势

• ✅ 持续活跃：2026 年仍有持续的版本发布和功能迭代
• ✅ AI 方向发力：AI 组件系列持续扩展，紧跟智能化趋势
• ✅ React 19 适配：正在逐步完成 React 19 的全面兼容
• ✅ D2C 能力增强：Design to Code 工具持续完善
• 社区 Star 数突破 10k，国内认可度持续提升

社区活跃度

• Open Issues：1 个（响应极快）
• Open PRs：29 个（社区贡献活跃）
• NPM 周下载量：稳定增长
• 被知乎等平台推荐为 2025/2026 年 React 组件库选型推荐

选型建议

• 强烈推荐：企业中后台系统、需要深度主题定制的产品、AI 应用
• 适合：大型团队协作、设计驱动的开发流程、字节技术栈项目
• 参考：与 Arco Design 同属字节系，两者在组件丰富度上各有侧重