ant-design/ant-design 딥다이브
— "디자인 토큰 3단 변환"으로 배우는 대규모 CSS-in-JS 아키텍처

1프로젝트 한 줄 정체

Ant Design은 두 겹으로 이루어져 있다. 겉으로 보이는 것은 <Button>, <Table>, <DatePicker> 같은 즉시 쓸 수 있는 완성형 컴포넌트 약 80개다. 그 밑을 받치는 것은 디자인 토큰(Design Token) 시스템으로, 색상·간격·둥근 정도 같은 값 하나하나를 "토큰"으로 관리하고 @ant-design/cssinjs라는 런타임 CSS-in-JS 엔진으로 실제 스타일을 생성한다.

단순한 컴포넌트 모음이 아니라 "디자인 언어(Design Language) + 구현체"라는 게 antd의 원래 정체성이다. 실제로 리포지토리 이름의 기원도 "Ant Design"이라는 디자인 스펙 문서였고, 이 저장소는 그 스펙을 React로 구현한 reference implementation이다. 그래서 컴포넌트 API뿐 아니라 테마·다크모드·RTL(오른쪽에서 왼쪽 언어)·SSR·국제화까지 한 몸에 갖췄다.

2왜 지금 앤트디자인인가

React UI 라이브러리는 매년 새로 뜨고 진다. 그런데 antd는 2015년부터 지금까지 계속 실서비스에 쓰이며 살아남았고, 2026년 현재도 활발히 메이저 버전을 올리는(v6) 몇 안 되는 "레퍼런스급" 라이브러리다. 지금 다시 주목할 이유를 셋으로 정리하면:

① v6 — "CSS 변수 시대"로 정식 전환

2026년 기준 최신 정식 버전인 v6는 기술적으로 큰 전환점이다. CSS 변수(Custom Properties) 사용이 기본값이 되었고, 그 대신 더 이상 IE(인터넷 익스플로러)를 지원하지 않는다. React 17 이하 지원도 끊겼다(React 18+ 필수). "레거시를 다 버리고 현대 브라우저 표준에 올라탄" 결단이 이 시점에 나왔다는 것 자체가 주목할 이유다.

② "토큰 하나로 라이트/다크/컴팩트를 동시에" — 테마 엔진의 정석

antd의 ConfigProvider 테마 시스템은 "토큰 몇 개만 바꾸면 전체가 다시 칠해진다"는 것을 실제로 대규모 프로덕션 스케일에서 증명한 사례다. 최근 디자인 시스템 업계 전반이 토큰 기반 테마화(Design Tokens, W3C 표준화 논의 포함)로 수렴하는 흐름에서, antd의 seed→map→alias 파이프라인은 실전 구현 참고서 역할을 한다.

③ AI 코딩 에이전트에 발 빠르게 대응

저장소에는 AGENTS.md·CLAUDE.md는 물론 .claude/skills, .cursor/skills, public/.well-known/agent-skills 같은 AI 코딩 에이전트용 규칙·스킬 디렉터리가 이미 마련돼 있다. 여기에 대화형 AI UI 구성요소를 제공하는 자매 프로젝트 @ant-design/x도 의존성에 포함돼 있어, "AI 에이전트가 직접 코드를 짜고 리뷰하는 시대"에 맞춰 문서·규범을 정비하는 실험을 관찰할 수 있다.

3무엇을 해결하는 라이브러리인가

기업용(엔터프라이즈) 웹 서비스 — 관리자 페이지, 백오피스, 대시보드, 내부 도구 — 를 만들 때 개발팀은 매번 같은 문제에 부딪힌다. "버튼 색은? 폼 검증 메시지는 어디에? 테이블 정렬 아이콘은?" 이런 자잘한 결정을 프로젝트마다 새로 내리면 시간이 새고, 제품마다 UI가 제각각이 된다.

antd는 이 문제를 "이미 검증된 완성형 컴포넌트 + 일관된 디자인 토큰"으로 해결한다. 개발자는 <Table columns={...} dataSource={...} /> 한 줄로 정렬·필터·페이지네이션이 되는 테이블을 얻고, 디자이너는 토큰 몇 개만 조정해 회사 브랜드에 맞는 색·둥근 정도를 전체 서비스에 일괄 적용한다. "매번 새로 그리기"에서 "토큰만 바꾸기"로 작업 단위를 바꿔준 것이 핵심 가치다.

여기에 국제화(74개 언어 로케일 파일), 접근성(RTL 레이아웃 지원), 서버사이드 렌더링(SSR) 스타일 추출까지 기본 제공되므로, 글로벌 서비스나 사내 다국어 백오피스를 만들 때 "이 부분은 antd가 이미 풀어놨다"고 믿고 넘어갈 수 있는 영역이 넓다.

4전체 구조 한눈에 보기

antd 저장소의 뼈대는 "각 컴포넌트가 자신의 스타일을 테마 엔진에게서 받아온다"는 구조다. 컴포넌트 자체(로직·마크업)와 스타일(토큰 기반 CSS-in-JS)이 물리적으로 분리돼 있고, 그 사이를 theme/ 디렉터리의 토큰 파이프라인이 연결한다.

이 구조가 주는 이득은 명확하다. 토큰 계층(1)과 스타일 생성 계층(2)이 나뉘어 있어서, 새 테마를 추가할 때 컴포넌트 코드를 단 한 줄도 건드리지 않고 algorithm 함수만 바꿔 끼우면 된다. 실제로 antd는 defaultAlgorithm·darkAlgorithm·compactAlgorithm 세 가지를 기본 제공하며, 이들을 배열로 조합해 "다크 + 컴팩트"처럼 겹쳐 쓸 수도 있다.

5핵심 설계·동작 원리 — 디자인 토큰 3단 변환

이 섹션이 이 문서에서 가장 두꺼운 이유는, 이 3단 변환이 antd 전체를 관통하는 단 하나의 설계 원리이기 때문이다. 컴포넌트가 80개든 800개든, 이 파이프라인만 이해하면 "어디를 고치면 무엇이 바뀌는지" 예측할 수 있다. 실제 소스(components/theme/)를 따라가며 단계별로 뜯어본다.

① Seed Token — "디자이너가 정하는 씨앗 값"

가장 위층은 components/theme/themes/seed.ts에 정의된 SeedToken이다. colorPrimary(주 색상), fontSize(기본 글자 크기), borderRadius(둥근 정도), colorError 같은 30여 개의 "원시 값"만 담고 있다. 이것이 테마 커스터마이징의 유일한 입구다 — 나머지는 전부 이 씨앗에서 계산돼 나온다.

// components/theme/themes/seed.ts (요지)
export const defaultPresetColors: PresetColorType = {
  blue: '#1677ff', purple: '#722ed1', cyan: '#13c2c2',
  green: '#52c41a', magenta: '#eb2f96', red: '#f5222d', /* ... */
};
const seedToken: SeedToken = {
  ...defaultPresetColors,
  colorPrimary: '#1677ff',
  colorError: '#ff4d4f',
  fontSize: 14,
  borderRadius: 6,
  // ...
};

② Map Token — algorithm 함수가 씨앗을 팔레트로 "파생"시킨다

두 번째 층은 derivative(seedToken) 함수, 즉 algorithm이다. components/theme/themes/default/index.ts를 보면 colorPrimary 하나에서 @ant-design/colors의 generate()를 이용해 10단계 색상 팔레트(blue-1 ~ blue-10)를 만들고, 글꼴 크기·여백·컨트롤 높이 체계까지 함께 계산한다. 결과가 MapToken이다.

// components/theme/themes/default/index.ts (요지)
export default function derivative(token: SeedToken): MapToken {
  const colorPalettes = /* colorPrimary → blue-1..blue-10 등 팔레트 생성 */;
  return {
    ...token,
    ...colorPalettes,
    ...genColorMapToken(token, { generateColorPalettes, generateNeutralColorPalettes }),
    ...genFontMapToken(token.fontSize),   // fontSizeSM/LG/XL... 자동 생성
    ...genSizeMapToken(token),             // sizeXXS ~ sizeXXL 자동 생성
    ...genControlHeight(token),
    ...genCommonMapToken(token),
  };
}

antd는 이 algorithm 함수를 3종 기본 제공한다. defaultAlgorithm(밝은 테마), darkAlgorithm(어두운 팔레트로 파생), compactAlgorithm(같은 색은 유지하되 크기·여백만 줄인 파생). ConfigProvider에 algorithm: [theme.darkAlgorithm, theme.compactAlgorithm]처럼 배열로 넘기면 두 변환이 순서대로 겹쳐 적용된다.

③ Alias Token — "개발자가 실제로 쓰는 이름"으로 재포장

마지막 층은 components/theme/util/alias.ts의 formatToken()이다. colorFillContent, colorTextDisabled, controlItemBgHover처럼 "이 값이 어디 쓰이는지" 이름에 드러나는 별칭을 MapToken 값에서 다시 계산해 붙인다. 예를 들어 colorTextDisabled는 colorTextQuaternary를 그대로 가리키는 별칭이다 — 실제 색상 계산은 이미 끝났고, 이 층은 "의미 있는 이름표"만 다는 단계다.

// components/theme/util/alias.ts (요지 발췌)
const aliasToken: AliasToken = {
  ...mergedToken,
  colorTextDisabled: mergedToken.colorTextQuaternary,
  colorTextHeading: mergedToken.colorText,
  controlItemBgHover: mergedToken.colorFillTertiary,
  controlItemBgActive: mergedToken.colorPrimaryBg,
  lineWidthFocus: mergedToken.lineWidth * 3,
  // override(사용자가 ConfigProvider로 넘긴 커스텀 값)가 최종적으로 이 위에 덮어써진다
  ...overrideTokens,
};

④ genStyleHooks — 토큰을 실제 CSS 객체로 굽는 마지막 공정

컴포넌트 각각의 style/index.ts는 위에서 완성된 AliasToken을 받아 genStyleHooks('Button', token => [...]) 형태로 스타일을 등록한다. genStyleHooks·genComponentStyleHook·genSubStyleComponent는 antd가 자체 구현한 것이 아니라 공식 유틸 패키지 @ant-design/cssinjs-utils에서 가져와, 컴포넌트별 프리픽스·CSP nonce·해시 처리를 표준화한다.

// components/button/style/index.ts (요지)
export default genStyleHooks(
  'Button',
  (token) => {
    const buttonToken = prepareToken(token);
    return [
      genSharedButtonStyle(buttonToken),
      genSizeBaseButtonStyle(buttonToken),
      genVariantStyle(buttonToken),
      genGroupStyle(buttonToken),
    ];
  },
);

이 함수가 반환한 CSS 객체는 내부적으로 @ant-design/cssinjs의 useStyleRegister가 해시로 캐싱한다. 즉 같은 토큰 조합으로 같은 컴포넌트를 100번 렌더링해도 스타일 계산과 <style> 태그 삽입은 최초 1회만 일어난다 — "런타임 CSS-in-JS는 무조건 느리다"는 통념을 정면으로 반박하는 캐싱 전략이다.

⑤ ConfigProvider — 토큰 설정을 트리 전체에 주입

이 모든 것을 코드 한 곳에서 켜는 진입점이 <ConfigProvider theme={...}>다. 내부적으로 algorithm을 createTheme()으로 감싸고, 사용자가 넘긴 token·components(컴포넌트별 오버라이드)를 DesignTokenContext.Provider로 하위 트리 전체에 뿌린다. 중첩된 ConfigProvider는 부모 테마를 이어받아 부분만 덮어쓸 수 있다.

import { ConfigProvider, theme } from 'antd';

function App() {
  return (
    <ConfigProvider
      theme={{
        algorithm: theme.darkAlgorithm,     // 다크 모드
        token: { colorPrimary: '#00b96b' }, // 브랜드 색만 교체
        components: { Button: { borderRadius: 2 } }, // 버튼만 각지게
      }}
    >
      <YourApp />
    </ConfigProvider>
  );
}

⑥ v6의 두 가지 렌더링 모드 — CSS 변수 vs 완전 정적(zero-runtime)

v6부터 antd는 기본적으로 CSS 변수 모드(cssVar)를 켠다. 스타일 규칙 자체는 미리 계산해 캐싱하되, 실제 색상 값은 var(--ant-color-primary) 같은 CSS 변수로 참조한다. 그래서 테마를 바꿀 때 전체 스타일시트를 다시 만드는 게 아니라 CSS 변수 값만 갱신하면 되어 훨씬 가볍다.

여기서 한 걸음 더 나아간 것이 zeroRuntime: true 옵션이다(6.0.0 신설). 이걸 켜면 런타임에는 아예 스타일을 생성하지 않고, 미리 빌드된 antd/dist/antd.css를 수동으로 불러와 쓰는 "완전 정적" 모드가 된다. 컴포넌트가 많은 대형 페이지에서 CSS-in-JS의 초기 계산 비용 자체를 없애고 싶을 때 쓰는 탈출구다.

⑦ SSR과 스타일 추출 — 서버에서 미리 계산해 넘기기

서버사이드 렌더링에서는 @ant-design/cssinjs의 createCache() + <StyleProvider cache={cache}>로 렌더링 도중 생성된 스타일을 모아, extractStyle(cache)로 문자열을 뽑아 HTML <head>에 직접 삽입한다. 완전 정적 배포용으로는 @ant-design/static-style-extract의 extractStyle()로 런타임 없이 미리 CSS 파일을 뽑아내는 것도 가능하다 — 이게 위 ⑥의 zeroRuntime 모드와 짝을 이루는 도구다.

6기술 스택과 의존성 지도

antd는 "자체 저수준 컴포넌트(headless) 패키지군 위에 완성형 컴포넌트를 얹는" 2층 생태계를 갖고 있다. 실제 package.json의 dependencies 47개 중 절반 가까이가 @rc-component/* 스코프 패키지다.

버전의 진실원(source of truth)은 package.json뿐이다

antd는 자기 버전을 코드에서 components/version/version.ts로 export하는데, 이 파일은 저장소에 커밋돼 있지 않다(.gitignore에 등록). scripts/generate-version.ts가 빌드 시점에 package.json의 version 필드를 읽어 이 파일을 그때그때 생성한다. 즉 "버전의 진짜 출처"는 항상 package.json 하나뿐이다.

7설치와 요구사항

# 설치 (npm / yarn / pnpm 모두 지원)
npm install antd
# 아이콘을 쓴다면 반드시 짝이 맞는 메이저 버전으로 함께 설치
npm install @ant-design/icons@6

8실제 사용 흐름 — 코드로 보는 하루

import { ConfigProvider } from 'antd';
import koKR from 'antd/locale/ko_KR';

export default function Root() {
  return (
    <ConfigProvider
      locale={koKR}
      theme={{ token: { colorPrimary: '#1677ff', borderRadius: 8 } }}
    >
      <App />
    </ConfigProvider>
  );
}

import { Button, Form, Input, Table } from 'antd';

function UserSearch() {
  const [form] = Form.useForm();
  const columns = [
    { title: '이름', dataIndex: 'name' },
    { title: '이메일', dataIndex: 'email' },
  ];
  return (
    <>
      <Form form={form} layout="inline" onFinish={(v) => search(v)}>
        <Form.Item name="keyword" rules={[{ required: true }]}>
          <Input placeholder="이름으로 검색" />
        </Form.Item>
        <Button type="primary" htmlType="submit">검색</Button>
      </Form>
      <Table columns={columns} dataSource={users} rowKey="id" />
    </>
  );
}

import { ConfigProvider, theme } from 'antd';

function ThemedApp() {
  const [isDark, setIsDark] = useState(false);
  return (
    <ConfigProvider
      theme={{ algorithm: isDark ? theme.darkAlgorithm : theme.defaultAlgorithm }}
    >
      <App />
    </ConfigProvider>
  );
}

9함정과 오해 바로잡기

10대안 비교 — MUI·Chakra·Mantine·shadcn/ui

11정리 — 누가 쓰면 좋은가

Ant Design은 "빠르게, 일관되게, 많은 기능을 갖춘 화면을 만들어야 하는" 팀에게 가장 어울린다. 특히 관리자 페이지·내부 도구·데이터 중심 대시보드처럼 디자인에 쓸 시간보다 기능 구현에 쓸 시간이 훨씬 중요한 프로젝트에서 강점이 극대화된다. 반대로 브랜드 아이덴티티가 강한 소비자용 서비스, 완전히 독자적인 시각 언어가 필요한 프로덕트에는 커스터마이징 부담이 상대적으로 크게 느껴질 수 있다.

그리고 antd를 쓰지 않더라도, 5장에서 다룬 seed→map→alias 토큰 파이프라인과 genStyleHooks 캐싱 전략은 어떤 규모의 디자인 시스템을 만들든 참고할 가치가 있는 설계다. "토큰 몇 개로 전체 테마를 바꾸는 시스템을 어떻게 짜는가"라는 질문에 실제 프로덕션 코드로 답을 볼 수 있는 몇 안 되는 저장소다.

12직접 해볼 수 있는 실습 과제

경로와 명령은 모두 ant-design 저장소 루트를 기준으로 한다. 첫 과제는 소스만 읽어도 수행할 수 있다. 테스트를 추가하는 나머지 과제는 의존성이 준비된 별도 작업 사본에서 진행한다. npm test는 사전 단계에서 scripts/generate-version.ts를 실행해 버전 파일을 생성하므로, 읽기 전용 원본에서 실행하지 않는다.

rg -n 'Button' components/button/index.tsx
rg -n 'handleClick|innerLoading|mergedDisabled|useStyle' components/button/Button.tsx
rg -n 'genStyleHooks|prepareToken' components/button/style/index.ts

<Form.Item
  name="username"
  label="이름"
  rules={[{ required: true, message: '이름을 입력하세요' }]}
>
  <Input />
</Form.Item>

npm test -- components/form/__tests__/index.test.tsx --runInBand -t '필수 입력과 초기화'

it('토큰 변환을 비교한다', () => {
  const config = { token: { colorPrimary: '#00b96b' } };
  const normal = theme.getDesignToken(config);
  const compact = theme.getDesignToken({
    ...config,
    algorithm: theme.compactAlgorithm,
  });
  const darkCompact = theme.getDesignToken({
    ...config,
    algorithm: [theme.darkAlgorithm, theme.compactAlgorithm],
  });

  expect(normal.colorPrimary).toBe('#00b96b');
  expect(compact.controlHeight).toBeLessThan(normal.controlHeight);
  expect(darkCompact.colorBgContainer).not.toBe(compact.colorBgContainer);
  expect(normal.colorTextDisabled).toBe(normal.colorTextQuaternary);
});

npm test -- components/theme/__tests__/token.test.tsx --runInBand -t '토큰 변환을 비교한다'

npm test -- components/config-provider/__tests__/theme.test.tsx --runInBand -t '중첩 테마의 범위'

13관련 기술 심화 학습 로드맵

처음부터 모든 컴포넌트를 읽기보다 버튼과 폼을 기준점으로 삼는다. 매주 읽은 파일의 역할을 이전 주의 결과물에 연결하면, 파일 목록이 실제 동작 경로로 바뀐다.

마지막 주에는 docs/react/customize-theme.en-US.md와 docs/react/contributing.en-US.md를 읽으며 자신의 설명을 대조한다. 토큰 계산 테스트, 컴포넌트 동작 테스트, 실제 화면 확인이 각각 무엇을 검증하는지 나눠 적으면 다음 컴포넌트를 공부할 때도 같은 절차를 재사용할 수 있다.

14핵심 키워드 사전