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

"팀마다 조금씩 다른 파랑, 조금씩 다른 여백"

디자이너와 개발자가 각자 감으로 색·간격을 정하면 제품군 전체가 미묘하게 어긋난다. Carbon은 spacing01~spacing13, background·text-primary 같은 이름 있는 토큰으로 이 결정을 한 곳에 고정하고, 코드에서는 값이 아니라 이름을 쓰게 강제한다.

제품마다 다시 하는 접근성 검증

버튼·모달·표를 새로 만들 때마다 키보드 포커스·ARIA·명도 대비를 처음부터 검증하는 건 비효율적이다. Carbon 컴포넌트는 이미 IBM의 3단계 접근성 검증(AVT1/2/3)을 통과한 상태로 배포되므로, 그 검증 비용을 팀마다 반복하지 않아도 된다.

라이트/다크 테마를 손으로 두 벌 유지보수

많은 프로젝트가 다크모드를 "나중에 CSS 뒤집어서" 대응하다 깨진다. Carbon은 처음부터 white·g10·g90·g100 4개 테마를 토큰 레벨에서 병렬로 정의해, 컴포넌트 코드는 그대로 두고 테마만 갈아 끼우면 전부 대응되게 만든다.

"React 팀"과 "표준 웹 팀"의 UI 이원화

사내에 React 앱도 있고 Vue/Angular나 순수 HTML 프로젝트도 있으면 UI 라이브러리를 두 벌 만들게 된다. Carbon은 같은 Sass 스타일(@carbon/styles)을 React 컴포넌트와 Lit 기반 웹 컴포넌트가 함께 가져다 쓰게 해, 프레임워크가 달라도 화면이 갈라지지 않게 한다.

1단계 — 패키지 설치와 스타일 임포트

npm install @carbon/react react react-dom 후, 앱 전역 스타일 파일에서 반드시 @use '@carbon/react/index.scss';(또는 필요한 컴포넌트 scss만 선택 임포트)를 해야 한다. JS 컴포넌트 import만으로는 겉모습이 나오지 않는다.

2단계 — 테마 지정

<Theme theme="g100">(React) 또는 최상위 요소에 대응하는 클래스/속성을 지정해 white·g10·g90·g100 중 하나를 활성화한다. 이 시점에 --cds-* 커스텀 속성이 그 테마 값으로 채워진다.

3단계 — 그리드로 레이아웃 뼈대 잡기

<Grid><Column sm={4} md={8} lg={16}>...</Column></Grid> 형태로 breakpoint별 컬럼 폭을 지정한다. 내부적으로 cds--grid/cds--col-* 클래스와 CSS 커스텀 속성이 동작한다.

4단계 — 컴포넌트 조립

import { Button, DataTable, Modal } from '@carbon/react' 형태로 필요한 컴포넌트를 가져와 조합한다. 웹 컴포넌트 프로젝트라면 import '@carbon/web-components/es/components/button/index.js' 후 HTML에 <cds-button> 태그를 직접 쓴다.

5단계 — Storybook·MDX 문서로 실제 props 확인

각 컴포넌트 폴더에는 *.mdx 문서와 *.stories.js가 함께 있다. 저장소를 직접 클론했다면 yarn storybook으로 실행해 실제 소스가 반영된 props 표와 예제를 즉시 확인할 수 있다 — 공식 사이트 문서보다 로컬 Storybook이 더 최신 소스에 가깝다.

기여(contribute) 흐름

포크 → yarn install → 원하는 패키지 디렉터리(예: packages/react)에서 yarn test(Jest) / e2e는 루트에서 yarn test:e2e(Playwright, AVT·VRT 포함) → PR 제출. 접근성에 영향을 주는 변경은 AVT 테스트 통과가 사실상 필수다.

같은 토큰 이름이 테마마다 무엇을 가리키는지 추적하기

목표: 배경색을 직접 적는 방식과 background라는 역할 이름을 사용하는 방식의 차이를 설명합니다.

1. 아래 명령으로 packages/themes/ 안의 JSON 파일을 찾고, background와 text-primary의 정의를 검색하세요.
2. white·g10·g90·g100에서 두 토큰의 $value를 기록하세요. 값이 {gray.80} 같은 별칭이면 packages/colors/의 원천 JSON에서 gray 아래 80을 찾아 실제 색까지 연결하세요.
3. packages/themes/tasks/build.js에서 생성 작업의 진입점을 찾고, packages/themes/scss/_theme.scss의 theme() 믹스인이 토큰 이름을 CSS 커스텀 속성으로 내보내는 부분을 읽으세요.

rg --files packages/themes -g '*.json'
rg -n -A 5 '"(background|text-primary)"' packages/themes -g '*.json'
rg --files packages/colors -g '*.json'

완료 기준: 네 테마와 두 토큰의 비교표를 만들고, 그중 한 항목을 원천 JSON부터 --cds-background 또는 --cds-text-primary까지 설명할 수 있습니다. 생성된 파일을 직접 고치는 대신 어느 원천과 빌드 작업을 확인해야 하는지도 적으세요.

Vite 예제에 밝은 테마와 어두운 테마 전환 붙이기

목표: 컴포넌트별 색상을 다시 지정하지 않고 Theme의 적용 범위를 바꿔 화면을 전환합니다.

1. examples/vite/src/main.jsx가 index.scss를 불러오는지 확인하고, examples/vite/src/App.jsx를 아래처럼 구성하세요.
2. examples/vite/src/index.scss의 기존 @use '@carbon/react' 설정은 유지하고, 아래 main 규칙을 덧붙이세요. Theme가 제공하는 토큰을 화면 배경과 글자색에 실제로 사용하기 위한 규칙입니다.
3. 루트에서 아래 실행 명령을 사용하고, 터미널에 표시되는 로컬 주소에서 버튼을 눌러 보세요. 개발자 도구로 Theme가 만든 요소의 클래스와 --cds-background 값을 비교하세요.
4. packages/react/src/components/Theme/index.tsx와 Theme.stories.js를 읽고, 같은 화면 안에 서로 다른 테마 영역을 둘 수 있는 이유를 설명하세요.

examples/vite/src/App.jsx의 구성 예시입니다.

import React, { useState } from 'react';
import { Button, Theme } from '@carbon/react';

export default function App() {
  const [dark, setDark] = useState(false);

  return (
    <Theme theme={dark ? 'g100' : 'white'}>
      <main>
        <p>{dark ? '어두운 테마' : '밝은 테마'}</p>
        <Button onClick={() => setDark(value => !value)}>
          테마 바꾸기
        </Button>
      </main>
    </Theme>
  );
}

examples/vite/src/index.scss에 추가할 규칙과 예제 실행 명령입니다.

main {
  background: react.$background;
  color: react.$text-primary;
  padding: 1rem;
}

npm --prefix examples/vite run dev

완료 기준: 버튼을 누를 때 안내 문구·배경·글자색이 함께 바뀌고, 키보드로 버튼에 이동해 전환할 수도 있습니다. 추가한 스타일에 색상 값을 직접 적지 않고, 테마 클래스가 바뀌어 토큰 값이 달라지는 과정을 설명할 수 있어야 합니다.

React 버튼과 웹 컴포넌트 버튼의 동작 계약 비교하기

목표: 같은 스타일을 공유하는 두 구현에서 입력 속성, 실제 HTML 요소, 접근성 동작을 구분합니다.

1. packages/react/src/components/Button/Button.tsx와 ButtonBase.tsx를 읽고, 기본 버튼·href 지정·disabled 지정·두 속성 동시 지정의 네 경우를 따라가세요.
2. packages/web-components/src/components/button/button.ts에서 같은 조건의 렌더링 분기를 찾으세요. 바깥의 <cds-button>과 섀도 DOM 안의 실제 요소를 구분하고, button.scss가 @carbon/styles를 가져오는 지점도 확인하세요.
3. 두 구현의 __tests__/에서 기본 요소, 비활성 상태, 링크를 검증하는 테스트를 읽고, 아래 명령으로 React 버튼 테스트만 실행하세요.
4. docs/guides/accessibility.md를 읽고, 이번 단위 테스트가 확인하는 내용과 별도로 필요한 키보드·스크린 리더 점검을 나누어 적으세요.

rg -n 'href|disabled|tabIndex' packages/react/src/components/Button/ButtonBase.tsx
rg -n 'href|disabled|tabIndex|render' packages/web-components/src/components/button/button.ts
yarn test --runTestsByPath packages/react/src/components/Button/__tests__/Button-test.js --runInBand

완료 기준: 지정한 React 테스트가 통과하고, 네 상태별로 두 구현이 만드는 요소와 속성을 근거 파일과 함께 비교한 표가 있습니다. href와 disabled를 함께 준 경우도 확인하고, 같은 모양이 같은 HTML 구조를 뜻하는지 설명하세요. 단위 테스트 통과와 전체 접근성 검증 완료는 구분해야 합니다.

기능 플래그가 JavaScript와 Sass에서 같은 결정을 하는지 검증하기

목표: 다음 세대 기능을 기존 코드와 함께 개발할 때, 동작과 스타일이 서로 다른 상태로 켜지는 문제를 이해합니다.

1. packages/feature-flags/feature-flags.yml에서 enable-v12-release와 하위 플래그를 찾으세요. 이어서 src/FeatureFlagScope.ts의 enabled()와 packages/feature-flags/index.scss의 enabled()를 비교하세요.
2. enable-v12-release와 등록된 enable-v12- 계열 플래그를 각각 켜고 끄는 네 조합의 예상 결과를 표로 적으세요. 다음으로 v12와 관계없는 플래그까지 자동으로 켜지는지 확인하세요.
3. packages/feature-flags/src/__tests__/feature-flags-test.js에서 예상 결과에 해당하는 검증을 찾고 아래 명령으로 실행하세요. 존재하지 않는 플래그를 조회하는 경우의 처리도 읽으세요.
4. docs/working-with-v12.md와 packages/react/src/components/FeatureFlags/index.tsx, packages/web-components/src/components/feature-flags/index.ts를 읽고 두 UI 구현이 이 규칙을 소비하는 경로를 연결하세요.

rg -n 'enable-v12-release|enable-v12-' packages/feature-flags/feature-flags.yml
yarn test --runTestsByPath packages/feature-flags/src/__tests__/feature-flags-test.js --runInBand

완료 기준: 지정한 테스트가 통과하고, 릴리스 플래그가 켜지면 등록된 v12 하위 플래그의 개별 값이 꺼져 있어도 활성으로 판정되는 이유를 설명합니다. JavaScript와 Sass 중 한쪽의 판정만 바뀌면 생길 화면 문제를 한 가지 제시하세요. 위 명령은 JavaScript 테스트이므로 Sass 구현까지 실행 검증했다고 기록하지 않습니다.