carbon-design-system/carbon 딥다이브
— "디자인을 코드로 굳힌" IBM의 오픈소스 디자인 시스템

1한 줄 정체 — Carbon은 무엇인가

Carbon Design System은 웹사이트 하나가 아니라 패키지 27개짜리 모노레포다. 그 안에는 색상표(@carbon/colors), 간격·타이포 규칙(@carbon/layout, @carbon/type), 그리드(@carbon/grid), 아이콘(@carbon/icons), 그리고 이 모든 걸 "테마"로 묶는 @carbon/themes가 있고, 그 위에 React 버전(@carbon/react)과 표준 웹 컴포넌트 버전(@carbon/web-components)이 나란히 올라간다.

즉 Carbon은 "예쁜 컴포넌트 라이브러리"가 아니라, 디자인 결정(색·간격·글꼴 크기)을 데이터로 만들고, 그 데이터를 여러 프레임워크가 공유하게 만드는 파이프라인이다. 실제로 색상 값 하나는 JSON(DTCG 토큰) 한 곳에만 적혀 있고, 그것이 Sass 맵으로, 다시 CSS 커스텀 속성과 JS 상수로 자동 생성된다.

2왜 지금 다시 주목받는가

Carbon은 신생 트렌드 저장소가 아니다. 10년 가까이 이어져 온 성숙한 엔터프라이즈 디자인 시스템이다. 그런데도 최근 다시 자주 언급되는 데는 세 가지 맥락이 있다.

① "토큰 우선(token-first)" 흐름의 표준 사례

Figma·Style Dictionary 등 디자인 툴 생태계가 DTCG(Design Tokens Community Group) 포맷으로 수렴하는 중인데, Carbon은 이미 white.json·g10.json·g90.json·g100.json 같은 실제 DTCG 토큰 파일을 Sass/JS로 컴파일하는 파이프라인을 운영 중이다. "토큰 기반 디자인 시스템을 실전 규모로 보고 싶다"는 사람들에게 Carbon은 몇 안 되는 완전히 공개된 실물 예시다.

② AI가 화면을 생성하는 시대의 "기준 부품함"

LLM 코딩 에이전트가 프론트엔드를 즉석에서 생성하는 일이 흔해지면서, 일관된 접근성·다크테마·간격 규칙을 이미 갖춘 컴포넌트 라이브러리의 가치가 오히려 커졌다. shadcn/ui 같은 "코드 복사형" 라이브러리와 달리 Carbon은 토큰 계층이 있는 "정책형" 시스템이라서, AI가 생성한 화면도 회사 표준에서 벗어나지 않게 잡아주는 역할을 한다. IBM 자체도 watsonx 등 생성형 AI 제품 UI를 Carbon 위에 짓는다.

③ v11 안에서 이미 시작된 v12 준비

저장소에는 docs/working-with-v12.md라는 별도 가이드가 있고, v12는 새 브랜치가 아니라 v11 코드베이스 안에서 feature flag(enable-v12-release)로 개발되고 있다. React·웹 컴포넌트 양쪽에 별도 포트의 v12 전용 Storybook(:3012, :6012)까지 마련돼 있어, "다음 메이저 버전을 어떻게 안전하게 준비하는가"를 보여주는 사례로도 주목받는다.

3무엇을 해결하는가

큰 조직이 여러 팀에서 각자 UI를 만들면 반드시 벌어지는 문제들이 있다. Carbon은 그 문제들을 정면으로 겨냥해 설계됐다.

4전체 구조 — 27개 패키지 지도

packages/ 아래 27개 패키지가 있지만, 의존 방향을 따라가면 4개 층으로 요약된다.

핵심은 "층 3(스타일)까지는 프레임워크 중립"이고, 층 4에서만 React냐 웹 컴포넌트냐가 갈린다는 것이다. 실제로 @carbon/react의 배포용 index.scss는 이렇게 돼 있다.

// packages/react/index.scss (빌드 시 자동 생성, "DO NOT EDIT" 주석 포함)
@forward '@carbon/styles';

즉 @carbon/react는 자기 스타일을 새로 만들지 않고 @carbon/styles를 그대로 재수출(re-export)한다. 웹 컴포넌트 쪽 버튼(src/components/button/button.scss)도 마찬가지로 같은 @carbon/styles 계층을 가져다 쓴다 — React 버전과 웹 컴포넌트 버전이 "따로 그려진 두 가지 버튼"이 아니라 같은 도안(Sass)을 각자 언어로 조립한 결과라는 뜻이다.

5핵심 설계 · 동작 원리

설계 ① — "JSON 토큰 → Sass 맵 → CSS 커스텀 속성"이라는 3단 변환

Carbon 색상 체계의 진짜 원천은 사람이 손으로 고치는 packages/themes/src/dtcg/white.json 같은 DTCG JSON 파일이다. 이 안에는 다음처럼 토큰 간 참조(alias)가 담겨 있다.

{
  "background": {
    "$type": "color",
    "$value": "{white.default}",
    "$description": "전체 페이지 기본 배경색"
  },
  "background-inverse": {
    "$type": "color",
    "$value": "{gray.80}"
  }
}

이 JSON은 tasks/builders/dtcg-themes.js·dtcg-js-themes.js 같은 빌더를 거쳐 scss/generated/themes/와 js/generated/themes/로 컴파일된다. 이후 _theme.scss의 theme() 믹스인이 이 맵을 순회하며 CSS 커스텀 속성(--cds-background 같은 변수)으로 뿌린다.

// packages/themes/scss/_theme.scss (요지)
@mixin theme($active-theme: $theme, $component-tokens...) {
  @each $token, $value in $active-theme {
    @include -custom-property($token, $value);  // --cds-{token}: {value};
  }
}

이 구조 덕분에 테마 전환이 CSS 재컴파일 없이 이뤄진다. 어떤 요소에 g100 테마의 커스텀 속성 값을 다시 뿌리기만 하면, 그 요소 아래 모든 컴포넌트가 즉시 다크 테마로 바뀐다. "값을 바꾸는 게 아니라, 같은 이름표(--cds-background)가 가리키는 실제 값만 바꾼다"는 것이 핵심이다.

설계 ② — white·g10·g90·g100, 4개 공식 테마

네 테마 모두 background·text-primary 같은 동일한 토큰 이름 집합을 갖고 값만 다르다. 그래서 컴포넌트 Sass·React 코드는 "지금이 무슨 테마인지" 전혀 몰라도 되고, 오직 --cds-* 커스텀 속성만 참조한다 — 테마 독립성이라 부르는 이 원칙이 Carbon 전체를 관통한다.

설계 ③ — 2x Grid: "필요한 변경만 내보내는" CSS 커스텀 속성 그리드

Carbon 그리드는 cds--grid·cds--row·cds--col 세 클래스로 구성되고, breakpoint(sm/md/lg/xlg/max)마다 컬럼 수·거터·마진을 CSS 커스텀 속성으로 노출한다. 흥미로운 점은 @carbon/grid의 믹스인이 "이전 breakpoint와 값이 달라졌을 때만" 새 규칙을 내보내도록 짜여 있다는 것 — 불필요한 CSS 중복을 스스로 줄이는 설계다.

:root {
  --cds-grid-gutter: #{$grid-gutter};
  --cds-grid-columns: /* 가장 작은 breakpoint 값 */;
  --cds-grid-margin: /* 가장 작은 breakpoint 값 */;
}
/* 이후 breakpoint는 "직전과 다를 때만" 재정의 */

설계 ④ — 기능 플래그 하나로 Sass·JS·React·웹 컴포넌트 4개 층을 동시에 통제

packages/feature-flags/feature-flags.yml에 등록된 플래그 하나(예: enable-v12-release)가 다음 4곳에서 동시에 인식된다.

• FeatureFlagScope.ts — 런타임 JS에서 enabled('enable-v12-release')
• feature-flags/index.scss — Sass의 enabled(...) 함수
• <FeatureFlags enableV12Release> — React 컴포넌트 트리
• <feature-flags enable-v12-release> — 웹 컴포넌트 커스텀 엘리먼트

그리고 enable-v12-release가 켜지면 enable-v12-로 시작하는 다른 모든 플래그가 자동으로 함께 켜지는 규칙까지 있다. 이 메커니즘 위에서 Carbon v12는 별도 브랜치가 아니라 v11 메인 코드베이스 안에서, 플래그로 가려진 채로 개발되고 있다 — React·웹 컴포넌트 양쪽에 v12 전용 Storybook 포트(3012/6012)까지 따로 준비해 미리보기만 분리한 상태다.

설계 ⑤ — AVT(Accessibility Verification Testing) 3단계가 CI에 내장

Carbon 컴포넌트는 만들어지면 끝이 아니라 AVT1(자동 검증) → AVT2(수동: 키보드·화면 확대) → AVT3(스크린 리더 확인) 3단계를 거친다. 저장소에는 achecker.js(IBM의 accessibility-checker 설정)와 *-test.avt.e2e.js 패턴의 Playwright 테스트가 80개 가까이 있으며, CI에서 자동 실행된다.

6기술 스택 · 의존성

7설치 · 요구사항

8실제 사용 흐름

9함정 · 오해 방지

10대안 비교

Carbon을 다른 시스템과 가르는 가장 뚜렷한 축은 "React 전용이 아니라 표준 웹 컴포넌트까지 1급으로 지원"한다는 점과, 토큰 원천이 DTCG JSON으로 완전히 공개돼 있고 4개 공식 테마가 처음부터 병렬 설계돼 있다는 점이다. 반대로 MUI·Spectrum류는 React 생태계 안에서의 개발 속도·컴포넌트 다양성에 좀 더 강점이 있다.

11정리 — 누가 쓰면 좋은가

Carbon은 "디자인 결정을 데이터(토큰)로 굳히고, 그 데이터를 여러 프레임워크가 공유하게 만드는" 성숙한 엔터프라이즈 디자인 시스템이다. 색 하나, 간격 하나까지 이름 붙여 관리하고, 그 위에 접근성 검증까지 마친 React·웹 컴포넌트 두 구현체를 함께 제공한다.