shadcn/ui 방식의 KRDS React 컴포넌트 - 왜 npm 패키지가 아닌가

"왜 npm 패키지로 안 만들었어요?"

HANUI를 소개하면 가장 많이 받는 질문이에요. Tailwind CSS, Radix UI 기반으로 만든 KRDS React 컴포넌트 라이브러리인데, shadcn/ui처럼 소스 코드를 복사하는 방식이거든요. 오늘은 이 기술적인 결정에 대해 얘기해볼게요.

shadcn/ui가 뭔데

shadcn/ui를 모르는 분들을 위해 간단히 설명하면, 컴포넌트를 npm 패키지로 설치하는 게 아니라 소스 코드를 직접 복사하는 방식이에요.

처음엔 "이게 뭔 구시대적인 방법이야" 했는데, 써보니까 장점이 확실하더라고요.

왜 이 방식을 택했나

1. 수정이 자유로움

공공 SI 하다 보면 디자인팀에서 "여기 버튼 색상만 살짝 바꿔주세요" 같은 요청이 와요. npm 패키지면 override 해야 하고, !important 남발하게 되고... 코드가 지저분해져요.

복사 방식이면? 그냥 파일 열어서 수정하면 돼요. 내 코드니까.

2. 폐쇄망 대응

공공기관 프로젝트, 폐쇄망 많잖아요. npm 설치가 안 되는 환경에서 패키지 의존성 관리하는 거 해본 사람은 알 거예요. 지옥이에요.

HANUI는 CLI로 한 번 복사해두면 그 다음부터는 인터넷 필요 없어요.

3. 버전 충돌 없음

React 18이니 17이니, peerDependencies가 어쩌니... 이런 거 신경 안 써도 돼요. 그냥 복사된 코드가 있을 뿐이니까.

기술 스택

Tailwind CSS를 선택한 이유

SCSS로 만드는 것도 고려했어요. 근데 2024년 기준으로 Tailwind가 압도적이더라고요.

• 번들 사이즈 최적화 (사용한 클래스만 포함)
• 디자인 토큰 관리가 편함
• 커스터마이징이 쉬움

KRDS 색상, 간격, 타이포그래피를 전부 Tailwind 설정 파일로 관리해요.

Radix UI를 쓰는 이유

접근성이에요. Dialog, Dropdown, Tooltip 같은 컴포넌트들, 직접 만들면 키보드 네비게이션이랑 스크린 리더 대응하는 게 보통 일이 아니에요.

Radix UI는 스타일 없이 동작만 제공하는 headless 컴포넌트예요. 접근성은 Radix가 알아서 해주고, 우리는 KRDS 스타일만 입히면 돼요.

CLI 구조

init이 하는 일

실행하면:

1. tailwind.config.js에 HANUI 프리셋 추가
2. styles/variables.css 생성 (KRDS 디자인 토큰)
3. lib/utils.ts 생성 (cn 유틸리티)

이게 끝이에요. 기존 프로젝트 설정 건드리지 않아요.

add가 하는 일

실행하면:

1. Button 컴포넌트 코드를 components/ui/button.tsx에 복사
2. 필요한 의존성 확인 (없으면 설치 안내)

레지스트리에서 컴포넌트 정보를 가져와서 복사하는 구조예요.

실제 사용 예시

접근성? 이미 들어가 있어요. ARIA 속성, 키보드 네비게이션, 포커스 관리 전부요.

마무리

정리하면:

• 왜 복사 방식인가: 수정 자유도, 폐쇄망 대응, 버전 충돌 방지
• 기술 스택: React + Tailwind + Radix UI
• CLI: init으로 설정, add로 컴포넌트 복사