인사이트리포트

들어가며

shadcn/ui는 오픈 소스 컴포넌트 세트이다. 대부분의 전통적인 컴포넌트 라이브러리 작동 방식은 NPM에서 패키지를 설치하고 컴포넌트를 가져와 애플리케이션에서 사용하는 방식이다. 이러한 접근 방식은 디자인 시스템에 맞게 컴포넌트를 커스터마이징하거나 라이브러리에 포함되지 않은 컴포넌트가 필요할 때까지는 효과적이다. 라이브러리 컴포넌트를 래핑하거나, 스타일을 재정의하는 임시 해결책을 작성하거나, 호환되지 않는 API를 가진 서로 다른 라이브러리의 컴포넌트를 혼합하는 경우가 많다.

shadcn/ui는 바로 이러한 문제를 해결하고자 다음 원칙을 기반으로 구축되었다.

• 오픈 코드: 컴포넌트 코드의 최상위 계층은 수정이 가능하다.
• 구성(composition): 모든 컴포넌트는 공통적이고 구성 가능한 인터페이스를 사용하여 예측 가능하다.
• 아름다운 기본 스타일: 엄선된 기본 스타일로, 처음부터 훌륭한 디자인을 구현할 수 있다.
• AI 지원: LLM이 읽고 이해하고 개선할 수 있는 오픈 코드이다.

철 학

shadcn/ui의 핵심은 Headless UI 철학에 있다.

전통적인 UI 프레임워크(예: Bootstrap)는 미리 정의된 스타일과 테마를 강하게 적용한다. 이 접근은 빠른 프로토타이핑에는 유리하지만 장기적으로는 스타일 오버라이딩의 비용이 커진다.

shadcn/ui는 이런 문제를 해결하기 위해 Headless UI 철학을 따른다. 즉, 기능과 접근성은 제공하되 스타일은 최소화하여 개발자가 자신의 디자인 시스템을 자유롭게 적용할 수 있도록 한다.

필자가 과거 Bootstrap과 같은 UI 컴포넌트 제공 라이브러리를 사용할 때 가장 먼저 하는 일은 스타일 리셋용 CSS를 두어 사용하는 라이브러리의 CSS 클래스들의 기본 스타일들을 본인의 프로젝트의 디자인 가이드에 맞게 오버라이딩하는 작업이었다. 예를 들어, 버튼 컴포넌트에 적용되는 .btn 클래스를 오버라이딩해야 했다. 그리고 CSS 셀렉터 우선순위의 문제로 오버라이딩이 잘 되지 않을 때는 !important 키워드를 사용했어야 했다.

shadcn/ui의 컴포넌트는 위와 같은 문제를 근본적으로 해결한다. 처음부터 내 코드 안으로 가져오기 때문에 오히려 오버라이딩 부담이 없다.

모달을 예시로 들어보자. 모달 컴포넌트를 직접 구현할 경우 다음과 같은 기능을 일반적으로 제공해야 한다.

• 다른 콘텐츠 최상위에 화면 중앙에 표시
• 배경 흐림 처리
• 키보드 포커스가 모달 내부에만 머무름
• Esc 키 입력으로 모달을 닫을 수 있음
• 모달 헤더의 닫기 버튼, 풋터에 배치한 버튼으로 모달을 닫을 수 있음
• 스크린 리더 사용자를 위한 접근성 속성 설정 필요

다음은 shadcn/ui으로 모달 컴포넌트를 만들 수 있는 예제 코드이다.

다음은 이 코드로 만들어진 모달 UI의 스크린샷이다.

위 스크린샷은 모달 열기 버튼을 클릭하여 모달이 열린 상태이다. CSS 스타일이 전혀 적용되어 있지 않기 때문에 모달이 그냥 HTML 구조처럼만 보이고, 화면 중앙에 표시되거나 배경 흐림 처리 등은 적용되어 있지 않다. 그러나 모달 헤더의 닫기(x 모양) 버튼(스크린샷에서는 모달 풋터보다도 아래에 위치), 풋터의 확인 버튼, Esc 키 입력으로 모달을 닫을 수 있는 등 기본적인 모달의 동작을 제공하고 있다.

위 코드에 Tailwind CSS를 적절히 설정하면 그럴듯한 모양의 모달을 쉽게 완성할 수 있다.

다음은 Tailwind CSS를 적용한 예제 코드이다.

다음은 이 코드로 만들어진 모달 UI의 스크린샷이다.

주요 컴포넌트

shadcn/ui에서는 위와 같이 다수의 다양한 컴포넌트를 제공한다. 이 경우 기본적으로 필요한 UI 컴포넌트가 이미 준비되어 있기 때문에 초기 개발 속도를 크게 단축시킬 수 있다. 예를 들어, 로그인/회원가입, 설정 화면 등 대부분의 웹 애플리케이션에서 반복되는 UI 구조를 바로 구현 가능하다.

제공하는 컴포넌트는 스타일이 강하게 고정된 형태가 아니라 Tailwind 클래스 기반으로 쉽게 확장 및 커스터마이징할 수 있다.

Accordion, Tabs, Toast, Popover, Navigation Menu 같은 상호작용이 복잡한 컴포넌트도 바로 사용할 수 있다. 이런 컴포넌트를 직접 구현하려면 포커스 이동, 애니메이션 등 수십 줄의 로직이 필요하지만 shadcn/ui는 이미 구현을 해 두었다.

이 문서에서 모든 컴포넌트의 사용 방법을 나열하기 보다는 일반적으로 자주 구현이 필요한 로그인 폼 모달을 만든다고 가정하고 일부 컴포넌트의 사용 방법을 설명하도록 하겠다.

Input

Input 컴포넌트는 사용자로부터 텍스트 데이터를 입력 받는 기본 UI이다. 로그인 폼의 아이디, 비밀번호, 이메일, 전화번호, 숫자 입력 등 다양한 용도로 사용된다. shadcn/ui의 Input은 기본 HTML <input>을 감싸는 형태이므로 기본 브라우저 동작과 접근성을 유지하면서 Tailwind 스타일로 커스터마이징할 수 있다.

HTML의 수많은 attribute를 사용 가능하기 때문에 더 많은 props가 존재하지만 주로 사용되는 일부 props에 대해서만 설명하겠다.

주요 props

Input 컴포넌트에 사용자 입력 값을 처리하는 예제이다.

Button

Button 컴포넌트는 사용자 액션을 트리거(클릭)하는 핵심 요소다. 클릭 시 이벤트, 제출, 토글 등 다양한 동작을 담당한다.

주요 props

다음은 Button의 외형과 크기를 다양하게 설정하는 예제이다.

Dialog

이 컴포넌트 그 아래의 콘텐츠를 비활성화는 대화 상자 컴포넌트이다. 여러 하위 컴포넌트를 조합하여 사용한다.

Dialog

대화 상자의 루트 컨테이너이다. DialogContent, DialogTrigger를 하위 요소로 가질 수 있다.

주요 props

다음은 전반적인 Dialog 컴포넌트의 구성을 보여주는 예제이다. open/onOpenChange props를 사용하여 대화 상자의 열림/닫힘 상태를 외부 state로 제어하는 경우이다.

다음은 defaultOpen props를 사용하여 초기 렌더링 시 대화 상자를 열린 상태로 만들고, 비모달 대화 상자로 만든 예제이다.

DialogTrigger

대화 상자를 여는 트리거 역할로 보통 버튼이나 링크와 함께 사용된다.

주요 props

다음은 DialogTrigger 사용 예제이다. DialogTrigger는 Dialog 하위에 있다. asChild props를 설정하고 DialogTrigger 하위에 Button이 있어서 이 Button이 대화 상자를 여는 트리거 역할을 한다. 또한 DialogFooter 하위의 DialogTrigger 하위의 Button은 반대로 대화 상자를 닫는 트리거 역할을 한다.

DialogContent

대화 상자 내부에 표시되는 본문 컨테이너이다. DialogHeader, DialogFooter 를 하위 요소로 가질 수 있다. DialogHeader와 DialogFooter 사이에 본문을 자유롭게 구현하면 된다.

주요 props

대화 상자의 기본 동작이 우측 상단에 닫기 버튼을 표시한다. 그리고 Esc 키 입력 및 대화 상자의 외부 클릭 시에도 대화 상자가 닫힌다.

요구 사항에 따라서는 대화 상자의 우측 상단에 닫기 버튼을 표시하지 않고, Esc 키 입력이나 대화 상자 외부 클릭으로 매우 쉽게 대화 상자가 닫혀버리는 것을 원하지 않을 수도 있다. 아래의 코드는 이 요구사항을 충족하는 예제 코드이다.

DialogHeader

머리글 컨테이너이다. 하위 요소로 대화 상자 제목인 DialogTitle 컴포넌트와 보조 설명인 DialogDescription 컴포넌트를 가질 수 있다.

DialogFooter

대화 상자 하단에 버튼이나 액션을 배치할 때 사용한다.

DialogClose

대화 상자를 닫는 동작을 담당한다.

주요 props

다음은 DialogClose 하위에 Button을 배치하여 대화 상자의 닫기 버튼으로 사용한 예제이다.

Tailwind CSS와의 시너지

shadcn/ui의 강점 중 하나는 Tailwind CSS를 토대로 한 설계 철학을 반영했다는 점이다.

생산성 향상

전통적인 UI 개발에서는 별도의 CSS 파일에 클래스를 정의하고, HTML 요소에 CSS 클래스를 매핑하는 작업이 필요했다.

Tailwind CSS는 클래스 이름만으로 시각적 구조를 표현하는 유틸리티 우선 접근법을 제공한다. shadcn/ui 컴포넌트와 결합되어 별도의 CSS 파일 없이도 빠르게 레이아웃을 구성할 수 있다.

예를 들어, 대화 상자의 하단 부분의 버튼에 다음과 같은 Tailwind CSS 클래스를 추가하면 즉시 스타일링이 적용된다.

이 문서의 앞부분에 있는 스크린샷의 확인 버튼과 비교했을 때, 배경색, 글자색, 둥근 정도가 변경되었음을 확인할 수 있다.

일관성 유지

프로젝트의 각 개발자가 같은 컴포넌트 또는 서로 다른 컴포넌트의 색상을 Tailwind CSS로 다음과 같이 서로 다르게 지정했다고 생각해보자.

같은 파란색 계열이지만 조금 다른 색상을 설정하면 다음 스크린샷과 같이 UI 일관성이 무너지게 된다.

Tailwind CSS는 프로젝트 전체의 스타일의 기초를 다음의 tailwind.config.js 파일에서 통합적으로 관리한다. 이 파일에서 색상, 폰트, 간격 등을 정의하여 사용하면 모든 컴포넌트가 동일한 스타일로 표현이 가능해 진다.

위에서 정의한 값을 다음과 같이 사용하여 한 번의 설정으로 다양한 컴포넌트에 적용하면 일관된 스타일을 유지할 수 있게 된다. (정의된 값을 바탕으로 bg-brand, bg-brand-dark CSS 클래스가 자동으로 생성된다.)

커스터마이징 자유도 향상

shadcn/ui는 Headless UI 철학에 기반하므로, 기능은 제공하지만 스타일은 강제하지 않는다. 이 구조 덕분에 Tailwind CSS로 언제든지 스타일을 재정의하고 완전한 커스터마이징이 가능한다.

이 문서의 앞부분에 있는 대화 상자 예제 코드와 같이 대화 상자를 구성하는 각 컴포넌트인 DialogContent, DialogTitle, DialogFooter, Button 등에 Tailwind CSS 클래스를 적용하여 대화 상자의 UI의 다양한 부분을 커스터마이징 가능하다.

AI Ready

shadcn/ui는 AI Ready하다고 알려져 있는데 그 이유를 살펴보자.

선언적이고 일관된 인터페이스

모든 컴포넌트가 일관적 props 구조와 네이밍 규칙을 따른다. 예를 들어, asChild 같은 props는 여러 컴포넌트에서 공통적으로 사용된다. 이는 AI가 코드 자동 생성 시 패턴을 쉽게 학습할 수 있도록 도와준다. 사실 이 문서에 포함되어 있는 예제 코드의 상당수는 AI에게 작성을 요청하고 생성된 코드를 직접 테스트를 하여 동작을 검증한 후 이 문서에 추가하였다.

예를 들어, “로그인 폼 대화 상자를 만들어줘”라고 요청하면 AI는 구조적으로 명확하게 분리된 Label, Input, Button, Dialog 컴포넌트를 조합해 코드를 생성할 수 있다.

구조화된 컴포넌트라서 “대화 상자의 제목을 수정해줘”라고 요청하면 AI는 Dialog 컴포넌트의 하위 컴포넌트 중 DialogTitle 컴포넌트의 글자를 변경해야 한다는 것을 쉽게 알려준다.

“Esc 키 입력으로 대화 상자가 닫히는 것을 막아줘”라고 요청하면 AI는 DialogContent 컴포넌트가 onEscapeKeyDown props를 제공함을 알아내고 onEscapeKeyDown  핸들러 함수에서 이벤트 전파를 막는 코드를 생성해 준다.

Tailwind CSS 기반 스타일링

스타일은 Tailwind의 원자적 클래스 기반으로 작성되므로, AI가 제안할 때 단순한 문자열 조합으로 새로운 스타일을 만들 수 있다.

예를 들어, “버튼 색상을 파란색으로 바꿔줘”라고 요청하면 AI는 Tailwind 클래스를 수정하여 다음과 같이 코드를 생성할 수 있다.

shadcn/ui 적용 사례

Taxonomy 사이트: https://tx.shadcn.com

소스 리포지토리: https://github.com/shadcn/taxonomy

shadcn 프로젝트가 제공하는 블로그, 문서 사이트, 그리고 인증 및 구독 기능 등을 포함하는 오픈소스 웹 애플리케이션의 레퍼런스 예제이다. Taxonomy는 shadcn/ui 컴포넌트를 실제 프로젝트에서 어떻게 활용할 수 있는지 보여주는 실용적인 예시로 활용될 수 있다.

에스코어(S-Core)에서도 대기업 고객의 차세대 홈페이지 구축 프로젝트에서 shadcn/ui를 도입하여 높은 유연성과 AI 친화적인 구조 덕분에 UI 일관성 확보와 빠른 프로토타이핑이 가능하였다.

마치며

실무에서 shadcn/ui를 사용한다면 다음과 같은 이점이 있다.

• 디자인 일관성 확보와 UI 품질을 균일하게 유지할 수 있다.
• 불필요한 구현 비용을 줄이고 개발 생산성을 향상시킬 수 있다.
• 필요에 따라 컴포넌트를 확장 및 수정하거나 통합해 장기적인 프로젝트에 적용 가능하다.
• 코드 구조가 명료하여, AI 기반의 코드 생성 도구와 잘 맞아 빠른 프로토타이핑을 가능하게 한다.

따라서 새로운 프로젝트를 시작하거나 기존 프로젝트의 UI를 리팩토링할 때, shadcn/ui를 도입해보는 것을 권장하는 바이다.