shadcn/ui 테마 개발 시작하기

shadcn/ui는 타입 안정성과 유연한 커스터마이징을 지원하는 현대적인 컴포넌트 라이브러리입니다. 이 가이드에서는 테마 개발의 전 과정을 실습 기반으로 단계별로 설명하며, 실제 프로젝트에 적용 가능한 구조를 제시합니다.

1. 환경 준비 및 프로젝트 구성

테마 개발을 시작하려면 공식 저장소를 로컬에 복제하세요:

git clone https://gitcode.com/gh_mirrors/ui/ui.jln.dev
cd ui.jln.dev
npm install

2. 테마 설정 파일 이해

기본 설정은 src/shared/theme-config.ts에서 관리됩니다. 이 파일은 Zod 스키마를 사용해 색상, 폰트, 간격 등 테마 속성의 타입을 강제합니다. 예시:

import { z } from 'zod';

export const themeSchema = z.object({
  primary: z.string().regex(/^#?([0-9a-f]{6}|[0-9a-f]{3})$/i),
  secondary: z.string().optional(),
  accent: z.string().optional(),
  radius: z.number().min(0).max(100),
});

3. 동적 테마 생성

핵심 함수인 createThemeConfig는 주 색상을 입력하면 자동으로 보조 색상과 다크모드를 생성합니다. 색상 조합은 HSL 기반으로 처리되며, 다음 예시처럼 변환됩니다:

function createThemeConfig(primaryHue: number) {
  const baseHsl = { h: primaryHue, s: 75, l: 40 };
  const secondaryHsl = { h: (primaryHue + 120) % 360, s: 70, l: 50 };
  return {
    light: { primary: hslToHex(baseHsl), secondary: hslToHex(secondaryHsl) },
    dark: { primary: hslToHex({ ...baseHsl, l: 20 }), secondary: hslToHex({ ...secondaryHsl, l: 30 }) }
  };
}

4. 색상 조화 시스템 활용

색상의 조화는 buildColorHarmony 함수에서 구현됩니다. 지원되는 패턴은 다음과 같습니다:

• 보색: 대칭 색상 (예: 0°와 180°)
• 삼각형: 120도 간격 (예: 0°, 120°, 240°)
• 유사색: 인접 색상 (예: 0°, 30°, 60°)

5. 차트 및 데이터 시각화 테마 통합

차트용 테마는 buildChartTheme 함수를 통해 생성됩니다. 이 함수는 반복 가능한 색상 그룹을 만들어, 그래프, 막대, 선 등 다양한 요소에 일관된 색상을 적용합니다:

const chartColors = buildChartTheme('#3b82f6', 5); // 5개의 계단 색상 반환

6. 테스트 및 적용 방법

테마의 시각적 효과를 확인하려면 src/client/components/examples/pages/ 폴더 내의 예제 페이지를 열어보세요. 각 컴포넌트가 어떻게 렌더링되는지 직접 확인할 수 있습니다.

실제 프로젝트에 적용하려면 theme-provider.tsx에서 ThemeProvider 컴포넌트에 생성한 테마 객체를 전달하세요:

<ThemeProvider theme={myCustomTheme} defaultTheme="light">
  <App />
</ThemeProvider>

7. 최적화 및 배포 준비

개발 완료 후, 테마를 dist/ 폴더에 빌드하고, 필요한 경우 package.json에 main 필드를 설정하여 공개 모듈로 사용할 수 있도록 합니다.