이준현의 블로그
2023.10.05·글

Chakra UI 레퍼런스를 통째로 씹어먹은 이야기

Chakra UIReactCSS-in-JSEUTCHA
Chakra UI

EUTCHA 프로젝트를 시작하면서 UI 라이브러리로 Chakra UI를 선택했다. React를 배운 지 2주밖에 안 된 시점이었는데 "어차피 쓸 거면 제대로 알고 쓰자"는 생각으로공식 문서 레퍼런스를 거의 외우다시피 공부했다.돌이켜보면 이때 잡은 기초가 이후 프로젝트에서도 계속 써먹는 밑바탕이 됐다.

왜 Chakra UI였나

당시 선택지는 MUI, Ant Design, Chakra UI 정도였다. MUI는 Material Design에 강하게 바인딩되어 있어서 커스터마이징이 번거로웠고 Ant Design은 디자인 톤이 프로젝트와 맞지 않았다.

Chakra UI를 고른 이유는 명확했다.

  • Style Props — CSS를 별도 파일 없이 컴포넌트에 직접 작성. React적인 사고와 잘 맞았다.
  • 접근성 기본 내장 — 모든 컴포넌트가 WAI-ARIA 표준을 따른다.
  • Composition 우선 — 작은 컴포넌트를 조합해서 큰 컴포넌트를 만드는 React 패턴과 철학이 같다.
  • 문서가 좋다 — 예제 코드가 풍부하고 각 prop의 설명이 상세하다.

공식 문서 공부법 — 전부 읽고, 전부 쳐보기

공부 방법은 단순했다. Chakra UI 공식 사이트의 컴포넌트 레퍼런스를처음부터 끝까지 전부 읽고 예제 코드를 전부 직접 쳐봤다.

Layout 컴포넌트(Box, Flex, Grid, Stack, Container)부터 시작해서 Form 컴포넌트(Input, Select, Checkbox, Radio), Feedback 컴포넌트(Toast, Alert, Skeleton), Overlay 컴포넌트(Modal, Drawer, Popover, Tooltip)까지 — 말 그대로 전 카테고리를 훑었다.

시간은 오래 걸렸지만 이렇게 하니까 "이런 UI를 만들려면 어떤 컴포넌트를 쓰면 되지?"라는 질문에 바로 답이 나왔다. 검색할 필요가 없어지니 구현 속도가 확 올랐다.

Style Props 시스템 이해하기

Chakra UI의 핵심은 Style Props다. CSS 속성을 축약형 prop으로 컴포넌트에 직접 전달한다.

// 기존 CSS 방식
<div style={{ marginTop: '16px', padding: '8px', backgroundColor: '#eee' }}>

// Chakra UI Style Props
<Box mt={4} p={2} bg="gray.100">
  {/* mt={4}는 margin-top: 1rem (4 * 0.25rem) */}
</Box>

처음에는 mt, px, bg 같은 축약어가 익숙하지 않았는데 며칠 지나니 오히려 일반 CSS보다 빠르게 작성할 수 있었다. 숫자 기반 spacing 시스템(4 = 1rem, 8 = 2rem)도 일관된 간격을 유지하는 데 큰 몫을 했다.

특히 Responsive Style이 인상적이었다. 미디어 쿼리를 직접 작성하는 대신, 배열이나 객체로 반응형 값을 지정할 수 있다.

// 배열 문법: [모바일, 태블릿, 데스크탑]
<Box fontSize={['sm', 'md', 'lg']} p={[2, 4, 8]}>
  반응형 텍스트
</Box>

// 객체 문법
<Flex direction={{ base: 'column', md: 'row' }}>
  <Box flex={1}>사이드바</Box>
  <Box flex={2}>메인 콘텐츠</Box>
</Flex>

EUTCHA 프로젝트가 모바일 중심 디자인(Max-width 1024px)이었는데 이 반응형 문법 덕분에 미디어 쿼리를 하나도 직접 작성하지 않고도 전체 반응형을 구현했다.

테마 커스터마이징

Chakra UI 테마 커스터마이징
Chakra UI 테마 커스터마이징 시스템

EUTCHA에서는 왓챠(Watcha)의 컬러셋을 레퍼런스로 활용했는데 Chakra UI의 extendTheme으로 깔끔하게 적용했다.

const theme = extendTheme({
  colors: {
    brand: {
      50: '#fff0f0',
      100: '#ffd6d6',
      500: '#ff0558',  // 왓챠 메인 컬러
      600: '#e6004e',
      900: '#800029',
    },
  },
  fonts: {
    heading: "'Noto Sans KR', sans-serif",
    body: "'Noto Sans KR', sans-serif",
  },
});

brand로 커스텀 컬러를 정의하면 colorScheme="brand"로 버튼, 뱃지, 체크박스 등 모든 컴포넌트에 일괄 적용된다. 50~900까지의 색상 스케일이 자동으로 hover, active, disabled 상태에 매핑되는 구조가 특히 편했다.

Composition 패턴 — 작은 것을 조합하기

Chakra UI를 쓰면서 React의 Composition 패턴을 자연스럽게 체득했다. Chakra UI의 컴포넌트들은 하나의 거대한 컴포넌트가 아니라, 작은 조각을 조합해서 원하는 UI를 만드는 방식이다.

// Modal을 Composition으로 구성
<Modal isOpen={isOpen} onClose={onClose}>
  <ModalOverlay />
  <ModalContent>
    <ModalHeader>영화 상세</ModalHeader>
    <ModalCloseButton />
    <ModalBody>
      {/* 내용 */}
    </ModalBody>
    <ModalFooter>
      <Button onClick={onClose}>닫기</Button>
    </ModalFooter>
  </ModalContent>
</Modal>

이 패턴에 익숙해지니 나중에 다른 라이브러리(Radix UI, shadcn/ui 등)를 접해도 "아, Compound Component 패턴이구나" 하고 바로 이해했다. Chakra UI에서 배운 Composition 사고방식이 가장 큰 수확이었다.

실전에서 특히 많이 쓴 컴포넌트들

EUTCHA에서 실제로 가장 많이 사용한 컴포넌트들을 정리하면:

  • Flex / Stack — 레이아웃의 90%를 이 둘로 해결했다. VStack, HStack으로 방향별 정렬이 한 줄이면 끝난다.
  • Skeleton — 영화 데이터 로딩 중 UI. isLoaded prop 하나로 로딩/완료 전환이 자동이다.
  • useDisclosure — 모달, 드로어의 open/close 상태를 관리하는 커스텀 훅. isOpen, onOpen, onClose를 한 번에 제공한다.
  • useToast — API 에러나 성공 알림을 한 줄로 표시. 위치, 지속 시간, 상태(success/error/warning) 설정이 간편하다.
  • Image — fallback 이미지 지원이 내장되어 있어서 TMDB 포스터 이미지 로딩 실패 시 대체 이미지를 쉽게 설정했다.

Emotion과의 관계

Chakra UI 내부는 Emotion(CSS-in-JS 라이브러리)으로 동작한다. 대부분의 스타일링은 Style Props로 충분하지만 가끔 Chakra UI가 제공하지 않는 세밀한 스타일이 필요할 때 Emotion의 css prop을 직접 썼다.

이 과정에서 CSS-in-JS의 동작 원리(런타임 스타일 생성, className 해싱 등)를 자연스럽게 익혔다. 나중에 Tailwind CSS로 넘어갔을 때 "런타임 vs 빌드타임 CSS"의 차이를 체감한 것도 이때 Emotion을 직접 다뤄본 덕분이다.

이후에 미친 영향

Chakra UI 문서를 통째로 공부한 경험은 예상보다 오래 써먹었다.

  • 컴포넌트 설계 감각 — "이 컴포넌트에 어떤 prop이 있어야 하지?"를 고민할 때 Chakra UI의 API 설계가 레퍼런스가 됐다.
  • 디자인 토큰 개념 — spacing, colors, typography를 토큰으로 관리하는 사고방식을 여기서 처음 접했다. 이후 Tailwind CSS의 설계 철학을 이해하는 데 직접적으로 도움이 됐다.
  • 공식 문서 읽는 습관 — "블로그 글 검색하지 말고 공식 문서부터 읽자"는 습관이 이때 잡혔다. 결국 가장 정확하고 최신인 정보는 공식 문서에 있다.
  • Compound Component 패턴 — Chakra UI에서 체득한 Composition 패턴을 이후 직접 컴포넌트를 설계할 때도 적용했다.

정리하며

라이브러리 하나를 "대충 필요한 것만 찾아 쓰기"와 "레퍼런스를 통째로 소화하기"의 차이는 생각보다 크다. 전자는 매번 검색에 시간을 쓴다. 후자는 머릿속에 지도가 그려져 있으니 바로 구현으로 간다.

모든 라이브러리를 이렇게 공부할 수는 없지만, 프로젝트의 핵심 도구 하나쯤은 공식 문서를 전부 읽어볼 가치가 있다. EUTCHA 때 Chakra UI에 투자한 시간이 이후의 개발 생산성으로 몇 배나 돌아왔다고 확신한다.

목록으로 돌아가기