Carbon Design System 是 IBM 企业级设计规范体系，需手动引入样式、遵守设计约束、正确配置主题与浮层定位，否则易出现渲染异常。
Carbon Design System 是啥，值不值得在项目里用
它不是个“拿来就能跑”的 UI 库，而是 IBM 把自己多年企业级产品设计规则、组件交互逻辑、色彩语义、动效节奏全打包成一套可落地的规范体系。你直接拿 @carbon/react 装上就能写组件，但真要发挥价值，得接受它的设计约束——比如配色必须走 carbon--theme 变量，按钮尺寸和间距按 8px 基准缩放，图标必须用 CarbonIcon 而非随便贴 PNG。
安装 @carbon/react 后组件不渲染或样式错乱
常见现象是按钮没边框、文字颜色发灰、DataTable 表头对不齐。根本原因是 Carbon 不自动注入 CSS，也不依赖全局样式重置。
- 必须手动引入核心样式：在入口文件加
import '@carbon/styles/css/fonts.css'; import '@carbon/styles/css/vars.css'; import '@carbon/styles/css/theme.css'; - 如果用 Webpack，确认
css-loader和style-loader配置正确，且没被其他 CSS-in-JS 方案（如 Emotion）的 reset 覆盖掉carbon--*变量 -
DataTable类复合组件依赖@carbon/styles的网格类（如bx--grid），漏引会导致布局坍塌
主题切换时 carbon--theme 变量不生效
Carbon 的主题靠 CSS 自定义属性驱动，不是 JS 控制 class 切换。你改了 JS 里的 theme 状态，但没把变量写进 :root 或对应容器，样式不会变。
- 切主题必须调用
setCarbonTheme（来自@carbon/themes），它会往 document.documentElement 写入变量，不是更新 React state - 自定义主题对象里不能漏掉
interactive-01、ui-05这类语义色，缺一个就可能让Button失去悬停态 - SSR 场景下，服务端渲染时 document 不存在，需用
getInitialTheme提前注入变量，否则首屏闪白
用 ComboBox 或 MultiSelect 时下拉菜单定位偏移
Carbon 的浮层组件默认用 Popper.js 管理定位，但 Popper 版本冲突或父容器 transform 属性会破坏计算逻辑。
立即学习“前端免费学习笔记（深入）”；
- 确保项目中只存在一个
@popperjs/core实例，ComboBox依赖 v2.11+，v1.x 会直接失效 - 如果父元素有
transform: translateZ(0)或perspective，Popper 无法获取正确 offset，临时解法是给组件加menuOffset={{ top: 8 }} - 在 Shadow DOM 或 iframe 里使用时，必须传
menuAppendTo={document.body}，否则浮层被截断
Carbon 的坑不在 API 多难记，而在它把设计决策全编码进了 CSS 变量和 DOM 结构里——改一个 carbon--spacing-md 值，可能影响二十个组件的垂直节奏；删掉一行 @import，整个主题系统就哑火。别把它当普通组件库用，得当一套带编译器的设计语言来读。
