carbon-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Carbon Design System

Build UIs conforming to IBM's Carbon Design System v11. Carbon provides a token-based, accessible, enterprise-grade component library.

构建符合IBM Carbon Design System v11规范的UI。Carbon提供了一套基于令牌、支持无障碍访问的企业级组件库。

Rendering Context

渲染上下文

Determine the output target before writing code.

编写代码前先确定输出目标。

HTML Artifacts (no build pipeline)

HTML产物（无需构建流水线）

Use pre-built CSS via CDN. Add to

<head>

html

<link rel="stylesheet" href="https://unpkg.com/@carbon/styles/css/styles.css" />
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;600&family=IBM+Plex+Mono:wght@400;600&display=swap" />

Apply Carbon classes to HTML elements. See

references/html-classes.md

通过CDN使用预构建的CSS，添加到

<head>

中：

html

<link rel="stylesheet" href="https://unpkg.com/@carbon/styles/css/styles.css" />
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;600&family=IBM+Plex+Mono:wght@400;600&display=swap" />

给HTML元素应用Carbon类名，参考

references/html-classes.md

。

React Artifacts

React产物

@carbon/react

is not in Claude's default artifact environment. For React artifacts, load the CDN CSS above and apply Carbon class names to standard HTML/JSX elements. The visual output is identical.

@carbon/react

不在Claude的默认产物环境中。对于React产物，加载上述CDN CSS，然后给标准HTML/JSX元素应用Carbon类名即可，视觉输出完全一致。

Full Projects (file creation)

完整项目（创建文件）

bash

npm install @carbon/react sass

jsx

import { Button } from '@carbon/react';
// Styles: @use '@carbon/react'; in root SCSS

Requires Dart Sass. All styles, components, icons ship in the single

@carbon/react

package.

bash

npm install @carbon/react sass

jsx

import { Button } from '@carbon/react';
// 样式：在根SCSS文件中添加 @use '@carbon/react';

需要Dart Sass。所有样式、组件、图标都打包在单个

@carbon/react

包中。

Design Foundations

设计基础

Typography

排版

Always use IBM Plex. Never substitute.

Role	Family	Weights
Body, UI	IBM Plex Sans	300, 400, 600
Code	IBM Plex Mono	400, 600
Editorial	IBM Plex Serif	300, 400, 600

始终使用IBM Plex字体，禁止替换。

角色	字体系列	字重
正文、UI	IBM Plex Sans	300, 400, 600
代码	IBM Plex Mono	400, 600
编辑内容	IBM Plex Serif	300, 400, 600

Color Themes

颜色主题

Theme	Background	Context
White	`#ffffff`	Default light
g10	`#f4f4f4`	Subtle light
g90	`#262626`	Dark
g100	`#161616`	High-contrast dark

Primary action: Blue 60

#0f62fe

. See

references/tokens.md

for full palette.

主题	背景色	使用场景
White	`#ffffff`	默认浅色
g10	`#f4f4f4`	柔和浅色
g90	`#262626`	深色
g100	`#161616`	高对比度深色

主操作色：Blue 60

#0f62fe

。完整调色板参考

references/tokens.md

。

Spacing

间距

8px base grid, 2px mini-unit. Component spacing: 2, 4, 8, 12, 16, 24, 32, 40, 48 px. Layout spacing: 16, 24, 32, 48, 64, 96, 160 px.

8px基础网格，2px迷你单位。组件间距：2、4、8、12、16、24、32、40、48 px。布局间距：16、24、32、48、64、96、160 px。

2x Grid

Breakpoint	Width	Columns	Margin
sm	320px	4	0
md	672px	8	16px
lg	1056px	16	16px
xlg	1312px	16	16px
max	1584px	16	24px

Grid classes:

cds--grid

cds--row

cds--col

cds--col-sm-N

cds--col-md-N

cds--col-lg-N

断点	宽度	列数	外边距
sm	320px	4	0
md	672px	8	16px
lg	1056px	16	16px
xlg	1312px	16	16px
max	1584px	16	24px

网格类名：

cds--grid

、

cds--row

、

cds--col

、

cds--col-sm-N

、

cds--col-md-N

、

cds--col-lg-N

。

Motion

动效

Token	Duration	Use
fast-01	70ms	Micro-interactions
fast-02	110ms	Toggle, expand
moderate-01	150ms	Buttons, fields
moderate-02	240ms	Modal, dropdown
slow-01	400ms	Page transitions
slow-02	700ms	Complex choreography

Standard easing:

cubic-bezier(0.2, 0, 0.38, 0.9)

. Entrance:

cubic-bezier(0, 0, 0.38, 0.9)

. Exit:

cubic-bezier(0.2, 0, 1, 0.9)

令牌	时长	用途
fast-01	70ms	微交互
fast-02	110ms	切换、展开
moderate-01	150ms	按钮、输入框
moderate-02	240ms	模态框、下拉菜单
slow-01	400ms	页面过渡
slow-02	700ms	复杂交互动画

标准缓动：

cubic-bezier(0.2, 0, 0.38, 0.9)

。入场缓动：

cubic-bezier(0, 0, 0.38, 0.9)

。退场缓动：

cubic-bezier(0.2, 0, 1, 0.9)

。

References

参考资料

Component HTML classes and usage:
```
references/html-classes.md
```
Full design token values:
```
references/tokens.md
```

Read the appropriate reference when building specific components or when exact token values are needed.

组件HTML类名与用法：
```
references/html-classes.md
```
完整设计令牌数值：
```
references/tokens.md
```

构建特定组件或需要精确令牌数值时，请查阅对应的参考资料。

Implementation Checklist

实现检查清单

IBM Plex loaded (Sans minimum; Mono for code)
Theme class applied:
```
cds--white
```
,
```
cds--g10
```
,
```
cds--g90
```
, or
```
cds--g100
```
Correct prefix:
```
cds--
```
(v11). Never
```
bx--
```
(v10 legacy)
Grid layout:
```
cds--grid
```
>
```
cds--row
```
>
```
cds--col-*
```
Spacing from scale only — no arbitrary pixel values
Focus states preserved — 2px blue outline
Color by role via tokens, not raw hex
Icons at Carbon sizes: 16, 20, 24, 32px

已加载IBM Plex字体（至少加载Sans字体；代码内容需加载Mono字体）
已应用主题类：
```
cds--white
```
、
```
cds--g10
```
、
```
cds--g90
```
或
```
cds--g100
```
正确的前缀：
```
cds--
```
（v11版本），禁止使用
```
bx--
```
（v10旧版本）
网格布局：
```
cds--grid
```
>
```
cds--row
```
>
```
cds--col-*
```
层级结构
仅使用间距规范内的数值，禁止使用任意像素值
保留焦点状态：2px蓝色外边框
通过令牌按角色使用颜色，不要直接用十六进制色值
图标使用Carbon标准尺寸：16、20、24、32px

Common Patterns

常用模式

Page Shell

页面框架

html

<div class="cds--white" style="min-height:100vh">
  <header class="cds--header" role="banner">
    <a class="cds--header__name" href="#">[App Name]</a>
  </header>
  <div class="cds--grid" style="padding-top:3rem">
    <div class="cds--row">
      <div class="cds--col-lg-3"><!-- Side nav --></div>
      <div class="cds--col-lg-13"><!-- Content --></div>
    </div>
  </div>
</div>

html

<div class="cds--white" style="min-height:100vh">
  <header class="cds--header" role="banner">
    <a class="cds--header__name" href="#">[App Name]</a>
  </header>
  <div class="cds--grid" style="padding-top:3rem">
    <div class="cds--row">
      <div class="cds--col-lg-3"><!-- 侧边导航 --></div>
      <div class="cds--col-lg-13"><!-- 内容区域 --></div>
    </div>
  </div>
</div>

Theme Nesting

主题嵌套

html

<div class="cds--g100"><!-- dark header --></div>
<div class="cds--white"><!-- light body --></div>

html

<div class="cds--g100"><!-- 深色头部 --></div>
<div class="cds--white"><!-- 浅色内容区 --></div>

Data Dashboard

数据仪表盘

Combine

cds--tile

containers for metric cards with

cds--data-table

for tabular data, all within the 2x grid.

在2x网格内，将

cds--tile

容器用于指标卡片，搭配

cds--data-table

展示表格数据。

Anti-Patterns

反模式

Non-IBM Plex fonts
```
bx--
```
prefix (v10; use
```
cds--
```
for v11)
Arbitrary border-radius (Carbon: 0px default, 4px for tags/pills only)
Drop shadows on components that lack them in spec
Overriding focus ring styles
Colors outside the Carbon palette
Spacing values not on the scale

使用非IBM Plex字体
使用
```
bx--
```
前缀（v10版本；v11版本请使用
```
cds--
```
）
随意设置border-radius（Carbon默认值为0px，仅标签/药丸状元素使用4px）
给规范中没有阴影的组件添加阴影
覆盖焦点环样式
使用Carbon调色板外的颜色
使用不在间距规范内的数值