chakra-ui/chakra-ui 딥다이브
— "스타일 props 그대로, 엔진은 통째로 교체" React 컴포넌트 시스템

1한 줄 정체

Chakra UI를 한 문장으로 정의하면: "토큰(색·간격·폰트) 기반 디자인 시스템을, CSS 파일 없이 JSX props로 바로 조립하게 해주는 React 컴포넌트 라이브러리"다. <Box p="4" bg="gray.100">처럼 여백·색을 props로 쓰면, 내부 엔진이 이를 실제 CSS로 변환해 페이지에 주입한다.

중요한 건 v2와 v3가 겉으로는 비슷해 보이지만 속은 완전히 다른 프로젝트라는 점이다. v2까지는 Emotion(런타임 CSS-in-JS 라이브러리)의 styled()·ThemeProvider·css prop을 그대로 쓰는 얇은 래퍼였다. v3는 소스 코드 packages/react/src/styled-system/ 폴더 전체가 Panda CSS(정적 CSS-in-JS 프리셋 도구)의 런타임 엔진을 포크해 온 것이고, 컴포넌트의 상태 로직(열림/닫힘, 포커스, 키보드 내비게이션)은 Ark UI라는 별도 헤드리스 라이브러리에 위임한다. 즉 Chakra팀이 스타일 엔진과 상태 머신을 직접 만들지 않고, 검증된 두 오픈소스(Panda·Ark)를 자기 컴포넌트 API 뒤에 이식한 것이다.

2왜 지금 뜨는가

Chakra UI는 2019년부터 있던 오래된 프로젝트지만, v3(2024년 말 출시) 이후 다시 화제가 된 데는 세 가지 최근 흐름이 겹쳐 있다.

① AI 코딩 도구가 다루기 좋은 "예측 가능한 props 문법"

size="lg", colorPalette="teal", variant="outline"처럼 정해진 값 집합만 받는 props는 LLM(대형 언어 모델)이 코드를 생성할 때 틀리기 어려운 구조다. 실제로 저장소 안에는 apps/mcp라는 공식 MCP(Model Context Protocol) 서버가 들어 있고, packages/cli/src/commands/component.ts 같은 CLI 명령이 AI 에이전트가 컴포넌트를 조회·생성하도록 돕는다. "AI가 UI를 짜는 시대"에 맞춰 도구 자체를 정비한 셈이다.

② v2→v3 대규모 마이그레이션 수요

기존 v2 사용자 다수가 아직 이전하지 못한 채 남아 있어, 공식 codemod(npx @chakra-ui/codemod upgrade)와 마이그레이션 가이드 검색량이 꾸준하다. MCP 서버 안에도 v2-to-v3-migration.ts라는 전용 도구가 있을 정도로, "이전 작업 자체"가 하나의 큰 사용 사례가 됐다.

③ 체감 가능한 성능·번들 크기 개선

공식 블로그(apps/www/content/blog/01-chakra-v2-vs-v3-a-detailed-comparison.mdx)는 v3가 재조정(reconciliation) 성능 4배, 리렌더 성능 1.6배 개선됐다고 밝힌다. 설치 의존성도 v2의 4개 패키지(@chakra-ui/react+@emotion/react+@emotion/styled+framer-motion)에서 v3는 2개(@chakra-ui/react+@emotion/react)로 줄었다. "무거운 UI 라이브러리"라는 인식을 벗으려는 시도다.

3무엇을 해결하나

프론트엔드 개발자가 새 프로젝트를 시작할 때 늘 반복하는 세 가지 숙제가 있다. Chakra UI는 이 셋을 한 번에 해결하려는 라이브러리다.

문제 ① — 디자인 토큰을 CSS 변수로 일관되게 뿌리기

"이 프로젝트의 파랑은 정확히 몇 번 색인가", "간격은 4px 단위인가 8px 단위인가"를 팀 전체가 매번 다시 정의하는 대신, Chakra는 packages/react/src/theme/tokens/ 아래 색·간격·폰트·그림자·둥근 모서리 등 20여 종의 토큰을 미리 정의해 CSS 변수(--chakra-colors-...)로 뿌린다. bg="colorPalette.solid"처럼 쓰면 라이트/다크 모드에 따라 알아서 값이 바뀐다.

문제 ② — 접근성(키보드·스크린리더)을 컴포넌트마다 다시 구현하지 않기

아코디언·콤보박스·다이얼로그 같은 컴포넌트는 WAI-ARIA(웹 접근성 표준) 패턴을 정확히 지켜야 스크린리더 사용자·키보드 사용자가 문제없이 쓸 수 있다. 이 로직을 웹앱마다 새로 짜는 건 비효율적이고 버그가 나기 쉽다. Chakra v3는 이 부분을 통째로 Ark UI에 맡겨, "행동은 검증된 라이브러리, 겉모습은 우리 팀 취향"으로 분업한다.

문제 ③ — 팀마다 다른 디자인을 "테마 하나"로 관리하기

버튼 색, 카드 그림자, 기본 폰트 같은 걸 컴포넌트 파일 하나하나 뒤져 고치는 대신, createSystem(defaultConfig, myConfig) 한 곳에서 토큰·레시피(컴포넌트별 스타일 규칙)를 병합해 프로젝트 전체 디자인을 한 번에 바꿀 수 있게 한다.

4전체 구조

저장소는 pnpm 워크스페이스(pnpm-workspace.yaml에 packages/**·apps/**·sandbox/** 등록, packageManager: "pnpm@11.10.0")로 묶인 모노레포다. Turborepo는 쓰지 않는다 — 루트 package.json의 build 스크립트는 pnpm --filter=./packages/* build로 pnpm 자체의 필터링 기능만 쓴다(9번 섹션에서 이 부분의 흔한 오해를 다룬다).

이 구조가 보여주는 분업은 명확하다. packages/react가 라이브러리 본체이고, cli·codemod는 그 본체를 "쓰기 쉽게/이전하기 쉽게" 돕는 도구, panda-preset은 "Panda CSS를 이미 쓰는 팀이 Chakra 디자인만 가져다 쓰게" 하는 다리다. apps/mcp는 이 라이브러리가 최근 AI 에이전트 생태계에 맞춰 스스로를 노출하는 창구다.

5핵심 설계·동작 원리

① 진실: Emotion을 "완전히" 버리지는 않았다 — 저수준만 남기고 포크했다

많은 요약 글이 "v3는 Emotion을 버렸다"고 단순화하지만, 실제 소스는 더 정교하다. packages/react/package.json의 dependencies를 보면 @emotion/is-prop-valid·@emotion/serialize·@emotion/use-insertion-effect-with-fallbacks·@emotion/utils가 여전히 들어 있다. 다만 사용자가 직접 설치해야 하던 @emotion/styled는 완전히 제거됐고, @emotion/react는 여전히 peerDependencies에 남아 있다(스타일 삽입에 필요한 <style> 캐시 메커니즘 때문).

결정적 증거는 packages/react/src/styled-system/factory.tsx 파일 맨 위 주석이다:

// Forked from https://github.com/emotion-js/emotion/blob/main/packages/styled/src/base.js
// but optimized for Chakra UI. All credits to the original authors.
// This also serves a bridge to React 19's style tag hoisting features.

즉 Chakra 팀은 @emotion/styled의 내부 구현(base.js)을 통째로 복사해 저장소 안에 두고 직접 유지보수하기로 했다. serializeStyles(Emotion의 CSS 객체 직렬화 함수)·registerStyles·insertStyles(Emotion의 스타일시트 삽입 함수) 같은 저수준 유틸리티만 그대로 쓰고, 상위의 styled() API·번들·의존성 계약은 자기 것으로 바꿨다. "Emotion 런타임 제거"의 진짜 의미는 "사용자가 설치해야 하는 무거운 패키지를 없애고, 필요한 저수준 엔진만 골라 내재화했다"에 가깝다.

② 토큰 → 시맨틱 토큰 → 레시피, 3단 스타일 파이프라인

packages/react/src/theme/ 폴더는 세 층으로 나뉜다.

• 토큰(tokens) — theme/tokens/colors.ts 등. "gray.500은 이 16진수 색"처럼 원시 값 하나하나를 정의.
• 시맨틱 토큰(semantic tokens) — theme/semantic-tokens/colors.ts. bg.subtle처럼 의미로 이름 붙이고, 라이트/다크 모드별 실제 값을 _light/_dark 조건으로 매핑. 실제 코드에서 bg: { DEFAULT: { value: { _light: "{colors.white}", _dark: "{colors.black}" } } }처럼 정의된 걸 확인할 수 있다.
• 레시피(recipes) — theme/recipes/button.ts 등 65개 파일. defineRecipe({ base, variants, defaultVariants }) 형태로 컴포넌트별 스타일 규칙을 선언. 버튼 레시피의 variant.solid는 bg: "colorPalette.solid"처럼 토큰을 참조한다.

이 3단 구조 덕분에 colorPalette="teal" 하나만 바꾸면, 그 컴포넌트 안의 colorPalette.solid·colorPalette.fg 같은 참조가 전부 teal 계열로 자동 치환된다 — 레시피 코드를 건드릴 필요가 없다.

③ Ark UI 결합 패턴 — "행동은 Ark, 겉모습은 Chakra"

packages/react/src/components/accordion/accordion.tsx를 열어보면 패턴이 선명하다:

import { Accordion as ArkAccordion } from "@ark-ui/react/accordion"
import { createSlotRecipeContext } from "../../styled-system"

const { withProvider, withContext } = createSlotRecipeContext({ key: "accordion" })

export const AccordionRoot = withProvider(ArkAccordion.Root, "root", { forwardAsChild: true })
export const AccordionItem = withContext(ArkAccordion.Item, "item", { forwardAsChild: true })

ArkAccordion.Root는 Ark UI가 만든, 스타일이 전혀 없는 순수 동작 컴포넌트다(열림 상태 관리, 키보드 화살표 이동, ARIA 속성 부여). withProvider는 createSlotRecipeContext가 만든 헬퍼로, 이 Ark 컴포넌트를 감싸서(wrap) "accordion" 슬롯 레시피의 스타일 클래스를 자동으로 주입한다. 116개 컴포넌트 폴더 대부분이 이 withProvider/withContext 패턴을 반복한다 — "헤드리스 라이브러리 + 자체 스타일 레이어"라는 조합을 대규모로 실증하는 좋은 예다.

④ 시스템 병합(createSystem) — 프리셋과 커스텀 테마를 합치는 법

packages/react/src/styled-system/system.ts의 createSystem(...configs)는 mergeConfigs(...configs)를 호출하고, merge-config.ts의 mergeConfigs는 mergeWith(깊은 병합)로 여러 설정 객체를 하나로 합친다. 그 과정에서 토큰 구조를 정규화하는 특수 로직도 있다 — 예를 들어 { value: "...", 500: {...} }처럼 값과 하위 토큰이 뒤섞인 경우 value를 DEFAULT.value로 자동 이동시킨다. 사용자는 createSystem(defaultConfig, myCustomConfig) 한 줄로 "기본 프리셋 + 내 커스터마이징"을 안전하게 합칠 수 있다.

⑤ color-mix — JS 색상 계산 라이브러리 제거

v2는 색상 투명도 조절(예: 파란색을 16% 투명하게)을 위해 theme-tools 패키지의 JS 함수(transparentize)로 RGBA 값을 미리 계산했다. v3는 bg: "blue.200/16"처럼 슬래시 문법을 쓰면 styled-system/color-mix.ts가 이를 CSS 네이티브 함수 color-mix() 호출로 변환한다(color-mix(in srgb, var(--chakra-colors-blue-200), transparent 16%)). 계산을 JS에서 브라우저 CSS 엔진으로 넘긴 것 — "런타임 JS 계산을 줄이고 브라우저 네이티브 기능에 위임"하는 v3 전반의 방향과 일치한다.

6기술 스택·의존성

7설치·요구사항

8실제 사용 흐름

npm install @chakra-ui/react @emotion/react
npx @chakra-ui/cli snippet add

import { Provider } from "@/components/ui/provider"

export default function App({ children }) {
  return <Provider>{children}</Provider>
}

import { Button, HStack } from "@chakra-ui/react"

function Demo() {
  return (
    <HStack gap="4">
      <Button colorPalette="teal" size="lg">저장</Button>
      <Button colorPalette="red" variant="outline">삭제</Button>
    </HStack>
  )
}

import { Accordion } from "@chakra-ui/react"

<Accordion.Root collapsible>
  <Accordion.Item value="a">
    <Accordion.ItemTrigger>섹션 제목</Accordion.ItemTrigger>
    <Accordion.ItemContent>내용</Accordion.ItemContent>
  </Accordion.Item>
</Accordion.Root>

import { createSystem, defaultConfig } from "@chakra-ui/react"

export const system = createSystem(defaultConfig, {
  theme: {
    tokens: {
      fonts: {
        heading: { value: "'Figtree', sans-serif" },
      },
    },
  },
})

9함정·오해 방지

함정 ① — "일괄 codemod면 다 끝난다"는 착각

npx @chakra-ui/codemod upgrade는 컴포넌트 이름 변경·prop 변경·임포트 경로 변경까지 자동화하지만, 테마 커스터마이징 로직(extendTheme → createSystem)이나 색상 모드 로직(useColorMode 제거) 같은 건 수동 리팩터링이 필요하다. 공식 가이드도 "codemod부터 시작하되, 수동 단계가 이어진다"고 명시한다. codemod 결과를 그대로 배포하지 말고, --dry 플래그로 먼저 미리보기를 하는 게 안전하다.

함정 ② — ColorModeProvider·useColorMode가 사라졌다는 걸 모르고 찾아 헤매기

v2의 ColorModeProvider·useColorMode·useColorModeValue·LightMode/DarkMode 컴포넌트는 v3에 전혀 존재하지 않는다(apps/www/content/blog/01-...mdx의 "Removed Features" 절에서 확인). 대신 next-themes 라이브러리에 위임하고, Chakra는 className="light"/"dark"를 강제로 붙이는 정도만 돕는다. v2 문서를 기억하고 useColorMode를 임포트하려 하면 즉시 에러가 난다.

함정 ③ — styleConfig/multiStyleConfig 문법을 계속 찾다가 시간 낭비

v2의 theme.components.Button.baseStyle 같은 styleConfig 개념은 완전히 없어졌다. v3는 이를 defineRecipe/defineSlotRecipe(5번 섹션)로 교체했다 — 문법 구조 자체가 다르므로 옛 테마 파일을 그대로 복붙하면 타입 에러가 난다.

함정 ④ — "Turborepo로 빌드한다"는 잘못된 가정

많은 대형 모노레포가 Turborepo나 Nx를 쓰기 때문에 Chakra UI도 그럴 거라 추측하기 쉽지만, 실제 저장소에는 turbo.json이 없다. 빌드는 pnpm --filter=./packages/* build처럼 pnpm 자체 워크스페이스 필터로 처리된다. 로컬에서 레포를 클론해 빌드해보려 할 때 "turbo build" 같은 명령을 찾다가 헤매지 않도록 주의.

함정 ⑤ — @emotion/styled를 실수로 다시 설치하기

v2 시절 프로젝트를 이전하면서 package.json에 남아 있는 @emotion/styled·framer-motion을 지우지 않으면, 실제로는 안 쓰이는 무거운 의존성이 번들에 계속 남는다. 마이그레이션 가이드가 명시적으로 npm uninstall @emotion/styled framer-motion을 첫 단계로 두는 이유다.

10대안 비교

11정리 — 누가 쓰면 좋은가

Chakra UI v3는 "CSS 파일을 거의 안 쓰고 JSX props만으로 일관된 디자인 시스템을 굴리고 싶은 팀", 그리고 "아코디언·콤보박스 같은 복잡한 접근성 로직을 직접 짜고 싶지 않은 팀"에 잘 맞는다. 내부적으로는 Panda CSS 엔진을 포크해 스타일을, Ark UI(Zag.js)를 가져와 상태 로직을 각각 전문 도구에 위임한 조합이라, "바퀴를 다시 발명하지 않는" 설계 철학을 배우기에도 좋은 사례다.

반대로 "컴포넌트 소스 코드 자체를 내 저장소에 두고 마음대로 뜯어고치고 싶다""Material Design 가이드라인을 그대로 따라야 한다"면 MUI 쪽이 더 맞을 수 있다. v2에서 넘어오는 팀이라면 공식 codemod로 시작하되, Provider·테마·색상 모드는 반드시 수동으로 대조하며 이전해야 한다(9번 섹션).