Carbon Design System

IBM 开源的企业级设计系统，提供统一的 React 组件库和设计语言，用于构建一致的企业产品体验。

技术简介说明

Carbon Design System 是 IBM 于 2016 年发布的开源设计系统，是 IBM 全线数字产品（包括 IBM Cloud、Watson、IBM Security 等）的统一视觉和交互语言的技术实现。Carbon 不仅仅是一个 React 组件库，它是一个完整的设计系统，包含设计原则、设计令牌（Design Tokens）、组件规范、图标系统、布局指南和 Figma 设计资源。其核心理念是"一致性、可访问性、模块化"。

Carbon 的技术架构经历了多次重大演进。当前版本（v11）是一个 React-first 的 Monorepo 项目，包含 React 组件库（@carbon/react）、Web Components 库（@carbon/web-components）、Sass 样式系统、Design Tokens、图标库（2000+ SVG 图标）和 Pictograms（200+ 信息图）等。Carbon 的样式方案采用 Sass（SCSS），通过 Design Tokens 驱动主题切换，支持从 v10 到 v11 的渐进式迁移。

截至 2026 年 7 月，@carbon/react 最新版本为 v11.111.0，GitHub 上拥有超过 9,300 颗星，累计超过 1,072 次发布。Carbon 正在向 v12 版本演进，v12 将正式支持 React 19（v19.2），同时废弃 React 18。2026 年最重要的新动向包括：Carbon MCP（Model Context Protocol）——让 AI 工具直接理解 Carbon 设计模式的 MCP 服务器，以及 Carbon AI Chat——用于构建 AI 聊天界面的前端框架。

基本信息

• 官网：https://carbondesignsystem.com/
• GitHub：https://github.com/carbon-design-system/carbon
• License：Apache-2.0
• 最新版本：@carbon/react v11.111.0（2026 年 7 月 1 日发布）；v12 开发中
• 主要维护者/公司：IBM
• 主要语言：TypeScript / JavaScript / SCSS

快速上手

安装

Carbon 的 React 实现使用 @carbon/react 包：

# 使用 npm
npm install @carbon/react @carbon/icons-react
 
# 使用 yarn
yarn add @carbon/react @carbon/icons-react
 
# 使用 pnpm
pnpm add @carbon/react @carbon/icons-react

如果需要 Sass 样式支持（自定义主题和 Token）：

npm install --save-dev sass

基础配置

Carbon 使用 Sass 作为样式基础。在应用入口中导入样式：

// 方式一：直接导入预编译 CSS（简单但不推荐用于定制）
import '@carbon/react/css/styles.css';
 
// 方式二：使用 Sass 导入（推荐，支持主题定制）
// 在你的主 .scss 文件中：
// @use '@carbon/react' with (
//   $font-path: '@ibm/plex'
// );

对于 Vite 项目，确保安装了 sass 依赖：

npm install --save-dev sass

最小示例

import React from 'react';
import {
  Theme,
  Button,
  TextInput,
  FormGroup,
  Header,
  HeaderName,
  Content,
  Grid,
  Column,
  Tile,
  ClickableTile,
} from '@carbon/react';
import { Add, Dashboard } from '@carbon/icons-react';
 
function App() {
  return (
    <>
      <Header aria-label="Carbon 示例">
        <HeaderName href="/" prefix="IBM">
          Carbon 示例应用
        </HeaderName>
      </Header>
      <Content>
        <Theme theme="white">
          <Grid>
            <Column lg={8} md={6} sm={4}>
              <Tile>
                <h4>欢迎使用 Carbon Design System</h4>
                <p>IBM 企业级设计系统的 React 实现</p>
              </Tile>
            </Column>
            <Column lg={8} md={6} sm={4}>
              <ClickableTile onClick={() => console.log('点击')}>
                <Dashboard size={32} />
                <h4>仪表板</h4>
                <p>查看系统概览</p>
              </ClickableTile>
            </Column>
          </Grid>
 
          <FormGroup legendText="用户信息">
            <TextInput
              id="username"
              labelText="用户名"
              placeholder="请输入用户名"
            />
            <TextInput
              id="email"
              labelText="邮箱"
              placeholder="请输入邮箱"
              type="email"
            />
            <Button renderIcon={Add} style={{ marginTop: 16 }}>
              创建用户
            </Button>
          </FormGroup>
        </Theme>
      </Content>
    </>
  );
}
 
export default App;

核心概念与架构

设计系统层次

Carbon 不仅仅是一个组件库，它是一个完整的设计系统：

Carbon Design System
├── 设计原则（Design Principles）
│   ├── 清晰（Clear）
│   ├── 自信（Confident）
│   └── 好客（Hospitable）
├── Design Tokens（设计令牌）
│   ├── 颜色 Token（$background, $text-primary 等）
│   ├── 排版 Token（$body-01, $heading-02 等）
│   ├── 间距 Token（$spacing-01 ~ $spacing-13）
│   └── 运动 Token（$duration-fast-01 等）
├── 组件库（React / Web Components）
├── 图标系统（2000+ 图标 + 200+ Pictograms）
├── 布局系统（16 列网格 + 断点）
└── Figma 设计资源

Monorepo 结构

Carbon 采用 Lerna + Yarn Workspaces 的 Monorepo 架构：

carbon/
├── packages/
│   ├── react/                    # @carbon/react - React 组件库
│   ├── web-components/           # @carbon/web-components - Web Components
│   ├── themes/                   # 主题定义
│   ├── themes-next/              # 下一代主题
│   ├── icons/                    # SVG 图标
│   ├── icons-react/              # React 图标组件
│   ├── pictograms/               # 信息图
│   ├── pictograms-react/         # React 信息图组件
│   ├── type/                     # 排版规范
│   ├── layout/                   # 布局工具
│   ├── motion/                   # 动画定义
│   ├── colors/                   # 颜色定义
│   ├── grid/                     # 网格系统
│   └── ... 更多工具包
├── docs/
└── examples/

主题系统

Carbon 使用 Sass 变量和 CSS Custom Properties 双轨制实现主题：

// 使用 Carbon 的 Token 系统
@use '@carbon/react/scss/themes';
@use '@carbon/react/scss/theme' with (
  $theme: 'g10'  // 可选：white, g10, g90, g100
);

内置主题：

排版系统

Carbon 使用 IBM Plex 字体家族，定义了标准化的排版 Token：

排版 Token 体系：
├── $label-01 (12px)
├── $label-02 (14px)
├── $body-01 (14px)
├── $body-02 (16px)
├── $heading-01 (14px, semibold)
├── $heading-02 (16px)
├── $heading-03 (20px)
├── $heading-04 (28px)
├── $heading-05 (32px)
├── $heading-06 (42px)
├── $heading-07 (54px)
└── $quotation-01 / $quotation-02

核心特性

• React-First 架构：Carbon 以 React 为主要平台，同时支持 Web Components、Angular、Vue、Svelte 等框架。React 组件库提供 67+ 个组件。

• Design Token 系统：基于 Sass 变量和 CSS Custom Properties 的双轨制 Token 系统，v11 对 Token 命名进行了逻辑化重命名，更易于理解和应用。

• IBM Plex 字体排版：使用 IBM 自研的 Plex 字体家族，定义了完整的排版 Token 体系，从 12px 标签到 54px 大标题全覆盖。

• 16 列响应式网格：基于 16 列的网格系统，配合 4 个标准断点（sm: 320px, md: 672px, lg: 1056px, xlg: 1312px, max: 1584px），支持 Grid、Row、Column 组件。

• 完整的图标系统：2000+ SVG 图标 + 200+ Pictograms（信息图），通过 @carbon/icons-react 和 @carbon/pictograms-react 提供 React 组件化使用。

• 可访问性：遵循 WCAG 2.1 标准，所有组件内建 ARIA 属性和键盘导航支持。

• 主题切换：支持 4 种内置主题（white/g10/g90/g100），通过 Theme 组件实现运行时主题切换和嵌套主题。

• Carbon MCP（2026 新功能）：Model Context Protocol 服务器，让 Cursor、Claude Code 等 AI 工具直接理解 Carbon 设计模式，生成符合 Carbon 规范的 UI 代码。

• Carbon AI Chat：专为构建 AI 聊天界面设计的前端框架（2025 年 10 月发布 v1），提供聊天气泡、消息列表、输入框等 AI 对话相关组件。

• Feature Flags 系统：v12 引入特性标志系统，允许渐进式启用新组件版本和设计变更，降低升级风险。

生态图

核心包

关键依赖

社区生态

IBM 内部使用

Carbon 被 IBM 全线产品采用：IBM Cloud、Watson、IBM Security、IBM Commerce 等，是经过大规模生产验证的企业级设计系统。

适用场景

• IBM 生态产品开发：如果你在为 IBM Cloud、Watson 或其他 IBM 产品构建扩展或集成工具，Carbon 是唯一的选择，确保与 IBM 产品线的设计一致性。

• 企业级 B2B SaaS 应用：Carbon 的组件（DataTable、Form、Notification、Modal 等）专为复杂的企业级 B2B 应用设计，提供数据表格、表单、导航等完整的后台功能。

• 大规模企业设计系统：需要为整个企业建立统一设计语言时，Carbon 提供了从设计原则到技术实现的完整方案，包括 Design Token、排版规范、颜色系统等。

• 合规性要求高的项目：需要满足 WCAG 2.1 可访问性要求、企业品牌一致性要求的政府、金融、医疗等行业项目。

• 多框架企业平台：Carbon 同时支持 React、Angular、Vue、Svelte 和 Web Components，适合技术栈多样化的大型企业。

• AI 对话界面：Carbon AI Chat 框架提供了构建 AI 聊天界面的专用组件，适合 IBM watsonx 等 AI 产品的 UI 开发。

• 数据密集管理工具：DataTable（支持排序、过滤、分页、展开行）、Pagination、Tabs、Accordion 等组件适合构建数据管理工具。

开发与工程化

开发流程

使用 Vite 快速开始 Carbon React 项目：

# 创建 Vite + React + TypeScript 项目
npm create vite@latest carbon-app -- --template react-ts
cd carbon-app
 
# 安装 Carbon 依赖
npm install @carbon/react @carbon/icons-react
npm install --save-dev sass
 
# 启动开发
npm run dev

Sass 配置

在项目主 SCSS 文件中配置 Carbon：

// src/styles/carbon.scss
@use '@carbon/react' with (
  $font-path: '@ibm/plex'
);

在入口文件中导入：

import './styles/carbon.scss';

构建优化

# 生产构建
npm run build
 
# Carbon 的 Tree-shaking 通过 ES Module 自动生效
# 确保构建工具支持 ES Module（Vite/Webpack 5+）

工程化最佳实践

1. Sass 模块化：使用 @use 替代 @import，v11 使用新的 Sass 模块系统减少编译时间：

   // ✅ 推荐
   @use '@carbon/react/scss/themes';
   @use '@carbon/react/scss/components/data-table';
   // ❌ 避免
   @import '@carbon/react/scss/styles';

2. Token 优先：始终使用 Design Token 而非硬编码值：

   // ✅ 推荐
   color: var(--cds-text-primary);
   padding: var(--cds-spacing-05);
   // ❌ 避免
   color: #161616;
   padding: 16px;

3. 图标按需导入：

   // ✅ 推荐 - 只导入需要的图标
   import { Add, Delete, Edit } from '@carbon/icons-react';
   // ❌ 避免 - 全量导入
   import * as Icons from '@carbon/icons-react';

4. TypeScript Stories：v12 新增支持 TypeScript Stories，便于文档编写和类型检查。

CI/CD 集成

# GitHub Actions 示例
name: Carbon App Build
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - run: npm run typecheck
      - run: npm test

性能与安全

性能特点

• Sass 编译时样式：Carbon 使用 Sass 编译为纯 CSS，运行时无样式计算开销，与 CSS-in-JS 方案相比性能更优。
• Tree-shaking：@carbon/react 支持 ES Module 按需导入，未使用的组件不会被打包。
• 图标体积优化：v11 引入了 size 属性，允许只加载需要尺寸的图标 SVG，减少图标包体积。
• Sass 模块系统：v11 使用新的 Sass 模块系统（@use/@forward）减少编译时间。

性能优化建议

1. 按需导入 Sass 组件：不要全量导入所有 Carbon 样式，只导入实际使用的组件样式：

   @use '@carbon/react/scss/components/button';
   @use '@carbon/react/scss/components/data-table';
   // 而非 @use '@carbon/react';

2. 图标尺寸控制：使用 size 属性导入特定尺寸的图标，避免加载所有尺寸变体。

3. DataTable 虚拟化：对于大数据集（1000+ 行），考虑配合虚拟滚动库（如 react-window）使用。

4. CSS 变量缓存：Design Token 通过 CSS Custom Properties 实现，浏览器会自动缓存，避免在 JS 中频繁读取 Token 值。

安全注意事项

• Carbon 组件遵循 React 默认 XSS 防护
• IBM 安全团队定期审计开源代码
• 通过 npm audit 和 IBM 内部安全流程监控依赖安全
• Sass 编译过程不存在运行时注入风险
• Carbon MCP 服务器需要验证 AI 生成代码的安全性

已知性能瓶颈

• Sass 全量编译时间较长（大型项目可能超过 30 秒），建议使用 Sass 模块按需导入
• DataTable 组件在没有虚拟化的情况下，大量行数据会导致 DOM 节点过多
• 首次加载的 CSS 文件较大（如果全量导入），需要配合代码分割

技术对比

Carbon 的独特优势

1. AI 工具集成（Carbon MCP）：2026 年推出的 MCP 服务器是同类设计系统中独一无二的，允许 AI 编码工具直接理解 Carbon 设计模式
2. 最完整的设计系统：从设计原则到技术实现的全链路覆盖，Figma 资源、Token 系统、排版规范一应俱全
3. 多框架支持：同时提供 React、Angular、Vue、Svelte 和 Web Components 实现
4. Sass 编译时方案：纯编译时样式，无运行时开销
5. Pictograms：200+ 独特的 Pictograms（信息图），适合企业级产品展示

Carbon 的相对劣势

1. 社区规模相对较小：相比 MUI/Ant Design，外部社区教程和第三方扩展较少
2. Sass 学习成本：深度定制需要了解 Sass 和 Carbon 的 Token 系统
3. 设计风格偏 IBM：默认外观与 IBM 产品线高度一致，品牌化定制需要较多工作
4. npm 下载量偏低：主要受 IBM 内部使用驱动，外部采用率不如 MUI/Ant Design

最佳实践

主题定制

// 自定义主题
@use '@carbon/react' with (
  $font-path: '@ibm/plex',
  $theme: (
    // 覆盖默认 Token
    'background': #f4f4f4,
    'text-primary': #161616,
    'interactive': #0f62fe,
    'support-success': #198038,
    'support-error': #da1e28,
  )
);

运行时主题切换：

import { Theme, Button, Content } from '@carbon/react';
 
function App() {
  return (
    <>
      <Theme theme="g10">
        <Content>
          <h4>浅灰主题区域</h4>
          <Button>操作</Button>
        </Content>
      </Theme>
 
      <Theme theme="g100">
        <Content>
          <h4>深色主题区域</h4>
          <Button>操作</Button>
        </Content>
      </Theme>
    </>
  );
}

DataTable 使用

import {
  DataTable,
  Table,
  TableHead,
  TableRow,
  TableHeader,
  TableBody,
  TableCell,
  TableToolbar,
  TableToolbarContent,
  TableToolbarSearch,
} from '@carbon/react';
 
const headers = [
  { key: 'name', header: '名称' },
  { key: 'age', header: '年龄' },
  { key: 'email', header: '邮箱' },
];
 
const rows = [
  { id: '1', name: '张三', age: '28', email: '[email protected]' },
  { id: '2', name: '李四', age: '34', email: '[email protected]' },
  { id: '3', name: '王五', age: '22', email: '[email protected]' },
];
 
function UserTable() {
  return (
    <DataTable
      rows={rows}
      headers={headers}
      isSortable
      render={({
        rows,
        headers,
        getHeaderProps,
        getRowProps,
        getTableProps,
        getTableContainerProps,
      }) => (
        <DataTable.TableContainer
          title="用户列表"
          description="管理系统用户"
          {...getTableContainerProps()}
        >
          <DataTable.TableToolbar>
            <DataTable.TableToolbarSearch />
            <DataTable.Button kind="primary" renderIcon={Add}>
              新增用户
            </DataTable.Button>
          </DataTable.TableToolbar>
          <Table {...getTableProps()}>
            <TableHead>
              <TableRow>
                {headers.map((header) => (
                  <TableHeader key={header.key} {...getHeaderProps({ header })}>
                    {header.header}
                  </TableHeader>
                ))}
              </TableRow>
            </TableHead>
            <TableBody>
              {rows.map((row) => (
                <TableRow key={row.id} {...getRowProps({ row })}>
                  {row.cells.map((cell) => (
                    <TableCell key={cell.id}>{cell.value}</TableCell>
                  ))}
                </TableRow>
              ))}
            </TableBody>
          </Table>
        </DataTable.TableContainer>
      )}
    />
  );
}

响应式布局

import { Grid, Row, Column } from '@carbon/react';
 
function ResponsiveLayout() {
  return (
    <Grid>
      <Row>
        <Column sm={4} md={4} lg={{ span: 4, offset: 0 }}>
          {/* 始终占满移动端，桌面端 4 列 */}
          <div>侧边栏</div>
        </Column>
        <Column sm={4} md={4} lg={{ span: 12 }}>
          {/* 移动端全宽，桌面端 12 列 */}
          <div>主内容区域</div>
        </Column>
      </Row>
    </Grid>
  );
}

常见陷阱

1. Sass 全量导入导致编译慢：不要 @use '@carbon/react' 导入所有组件样式，应只导入实际使用的组件。

2. Token 命名变更：v10 到 v11 的迁移中，大量 Token 名称发生了变化（如 $ui-01 → $background）。迁移时需要全局搜索和替换。

3. React 19 兼容性：v12 正式要求 React 19.2，React 18 在 v12 中将被废弃。提前规划 React 版本升级。

4. IBM Plex 字体加载：确保正确配置 $font-path，否则字体无法加载，导致排版异常。

5. Web Components 与 React 组件混用：@carbon/react 和 @carbon/web-components 不应在同一项目中混用，选择一种实现方式。

技术局限与边界

已知限制

1. Sass 依赖：Carbon 深度依赖 Sass 作为样式方案。如果项目不使用 Sass（如使用 Tailwind CSS 或纯 CSS），集成成本较高。

2. 设计风格绑定 IBM：Carbon 的默认视觉语言与 IBM 产品线高度一致。非 IBM 生态的项目需要投入较多精力进行品牌定制。

3. Sass 编译时间：大型项目中全量 Sass 编译可能较慢。虽然 v11 的 Sass 模块系统有所改善，但仍不如 CSS-in-JS 方案的开发体验即时。

4. 组件丰富度：67+ React 组件虽然覆盖了常见需求，但相比 Ant Design（70+）或 Material UI（100+），在高级组件（如虚拟滚动树、Transfer、复杂表单布局）方面仍有差距。

5. 社区生态有限：相比 MUI 和 Ant Design，Carbon 的第三方扩展、教程和社区讨论相对较少。

不适用场景

• 面向消费者的 C 端产品（如电商、社交网络，视觉风格不匹配）
• 已有 Tailwind CSS 或其他 CSS 框架的成熟项目（Sass 集成成本高）
• 追求极致现代感和动效的产品（Carbon 设计风格偏保守）
• 轻量级小型项目（Carbon 的学习和配置成本相对较高）

迁移注意事项

• v10 → v11：Token 重命名是主要工作量，使用 Carbon 提供的迁移指南和 codemod 工具辅助
• v11 → v12：需要升级到 React 19.2，React 18 将被废弃。Feature Flags 系统允许渐进式迁移
• React 16/17 用户：v12 对 React 16/17 发出废弃警告，建议尽快升级到 React 18+

学习资源

官方文档

• Carbon Design System 官网 - 设计原则、组件文档和使用指南
• Carbon GitHub - 源码、Issue 和 Release Notes
• Carbon Storybook - 组件交互演示
• Carbon Deprecations - 版本废弃说明
• Carbon v12 Feature Flags - v12 特性标志文档
• Carbon Release Schedule - 发版计划

教程与文章

• Up & Running with Carbon React in less than 5 minutes - Medium - 快速入门
• React + IBM Carbon Design Tutorial - 完整的构建教程
• Dynamic theming in React using IBM Carbon - IBM Developer - 动态主题教程
• Carbon Design System's Commitment to Web Components - Medium - Web Components 路线图
• Turning Design Systems into Conversations: How Carbon MCP Makes AI Carbon-Aware - Carbon MCP 介绍

社区资源

• Carbon GitHub Discussions - GitHub 讨论区
• Carbon on X (@_carbondesign) - 官方社交媒体
• Carbon Figma 社区资源 - Figma 设计文件
• Carbon AI Chat GitHub - AI 聊天框架源码
• IBM Developer - Carbon - IBM 开发者门户

2026 年现状

最新版本

发展趋势

• React 19 过渡：v12 将 React 19.2 作为推荐版本，React 18 进入废弃倒计时。v12 通过 Feature Flags 控制新组件版本的渐进启用。

• AI 集成：2026 年最重要的新方向是 AI 集成——Carbon MCP 让 AI 编码工具（Cursor、Claude Code、IBM Bob）直接理解 Carbon 设计系统知识，生成符合 Carbon 规范的生产级 UI 代码。

• Web Components：Carbon 明确承诺向 Web Components 方向发展，@carbon/web-components v2 已经发布，为框架无关的 Carbon 使用铺路。

• 站点重设计：Carbon 文档网站已经重设计，改进了导航和使用指南。

• TypeScript Stories：v12 新增支持 TypeScript 格式的 Storybook Stories。

社区活跃度

• GitHub Stars：9,300+
• 累计发布次数：1,072+
• IBM 全线产品使用（IBM Cloud、Watson、IBM Security 等）
• 活跃的 GitHub Issue 追踪
• 2026 年 MCP 和 AI Chat 引起新的关注

未来展望

1. v12 正式发布：React 19 完全支持，React 18 废弃，Feature Flags 系统稳定化
2. v13 规划：可能包含 Web Components 深度整合和更多 AI 能力
3. Carbon MCP 正式版：从公开预览到正式版的完善
4. Carbon AI Chat：持续迭代，增加更多 AI 对话界面组件和模式
5. UI 设计方向更新：2026 年及以后的 UI 设计方向正在规划中

总结：Carbon Design System 是 IBM 企业级设计系统的完整实现，特别适合 IBM 生态产品和需要严格设计一致性的企业级 B2B 应用。2026 年，Carbon 在 AI 集成方面走在同类设计系统前列（MCP + AI Chat），同时正在推进 React 19 迁移和 Web Components 发展。虽然社区规模不如 MUI/Ant Design，但其完整的设计系统覆盖和 IBM 企业背书使其在企业场景中具有独特价值。