ERP-node/docs/shadcn-ui_디자인_시스템_가이드.md

# shadcn/ui 디자인 시스템 적용 가이드

> 본 문서는 프로젝트에 shadcn/ui 디자인 시스템을 적용하기 위한 가이드입니다.
> 참고: [shadcn/ui 공식 사이트](https://ui.shadcn.com/)

## 📋 목차
1. [디자인 철학](#디자인-철학)
2. [색상 시스템](#색상-시스템)
3. [타이포그래피](#타이포그래피)
4. [컴포넌트 디자인 패턴](#컴포넌트-디자인-패턴)
5. [스페이싱 시스템](#스페이싱-시스템)
6. [애니메이션](#애니메이션-및-트랜지션)
7. [반응형 디자인](#반응형-디자인)
8. [접근성](#접근성-accessibility)
9. [적용 방법](#적용-방법)

---

## 디자인 철학

### 핵심 원칙
- **Beautifully designed components**: 아름답고 모던한 UI 컴포넌트 사용
- **Customizable & Extendable**: 커스터마이징 가능하고 확장 가능한 구조
- **Open Source & Open Code**: 오픈 소스 정신에 따른 투명한 코드

### 디자인 특징
- ✨ 미니멀하고 모던한 인터페이스
- 🎨 CSS 변수 기반의 테마 시스템
- 🌓 다크/라이트 모드 지원
- ♿ 접근성 우선 설계
- 📱 모바일 우선 반응형 디자인

---

## 색상 시스템

### CSS 변수 기반 테마

프로젝트의 모든 색상은 CSS 변수로 관리하며, HSL 색상 포맷을 사용합니다.

#### 라이트 모드
```css
:root {
    /* 배경 및 전경색 */
    --background: 0 0% 100%;           /* 흰색 배경 */
    --foreground: 222.2 84% 4.9%;     /* 거의 검은색 텍스트 */
    
    /* 카드 */
    --card: 0 0% 100%;                /* 카드 배경 */
    --card-foreground: 222.2 84% 4.9%; /* 카드 텍스트 */
    
    /* 팝오버 */
    --popover: 0 0% 100%;
    --popover-foreground: 222.2 84% 4.9%;
    
    /* 주요 색상 */
    --primary: 222.2 47.4% 11.2%;     /* 진한 파란색 */
    --primary-foreground: 210 40% 98%; /* 주요 버튼 텍스트 */
    
    /* 보조 색상 */
    --secondary: 210 40% 96.1%;       /* 연한 회색 */
    --secondary-foreground: 222.2 47.4% 11.2%;
    
    /* 음소거 색상 */
    --muted: 210 40% 96.1%;           /* 비활성 배경 */
    --muted-foreground: 215.4 16.3% 46.9%; /* 비활성 텍스트 */
    
    /* 강조 색상 */
    --accent: 210 40% 96.1%;
    --accent-foreground: 222.2 47.4% 11.2%;
    
    /* 위험 색상 */
    --destructive: 0 84.2% 60.2%;     /* 빨간색 */
    --destructive-foreground: 210 40% 98%;
    
    /* 테두리 및 입력 */
    --border: 214.3 31.8% 91.4%;      /* 연한 회색 테두리 */
    --input: 214.3 31.8% 91.4%;       /* 입력 필드 테두리 */
    --ring: 222.2 84% 4.9%;           /* 포커스 링 */
    
    /* 모서리 둥글기 */
    --radius: 0.5rem;                  /* 8px */
}
```

#### 다크 모드
```css
.dark {
    --background: 222.2 84% 4.9%;     /* 거의 검은색 */
    --foreground: 210 40% 98%;        /* 흰색 텍스트 */
    
    --card: 222.2 84% 4.9%;
    --card-foreground: 210 40% 98%;
    
    --primary: 210 40% 98%;           /* 밝은 색상 */
    --primary-foreground: 222.2 47.4% 11.2%;
    
    --secondary: 217.2 32.6% 17.5%;   /* 어두운 회색 */
    --secondary-foreground: 210 40% 98%;
    
    --accent: 217.2 32.6% 17.5%;
    --accent-foreground: 210 40% 98%;
    
    --border: 217.2 32.6% 17.5%;
    --input: 217.2 32.6% 17.5%;
}
```

### 색상 사용 방법
```css
/* HSL 함수를 사용하여 CSS 변수 적용 */
.element {
    background: hsl(var(--primary));
    color: hsl(var(--primary-foreground));
}

/* 투명도 추가 */
.element-transparent {
    background: hsl(var(--primary) / 0.5); /* 50% 투명도 */
}
```

---

## 타이포그래피

### 폰트 패밀리
```css
body {
    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, 
                 "Helvetica Neue", Arial, sans-serif;
    font-feature-settings: "rlig" 1, "calt" 1;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
}
```

### 텍스트 크기 스케일
| 클래스 | 크기 | 줄 높이 | 사용처 |
|--------|------|---------|--------|
| `.text-xs` | 0.75rem (12px) | 1rem | 작은 설명, 캡션 |
| `.text-sm` | 0.875rem (14px) | 1.25rem | 본문 보조 텍스트 |
| `.text-base` | 1rem (16px) | 1.5rem | 기본 본문 |
| `.text-lg` | 1.125rem (18px) | 1.75rem | 큰 본문 |
| `.text-xl` | 1.25rem (20px) | 1.75rem | 소제목 |
| `.text-2xl` | 1.5rem (24px) | 2rem | 중제목 |
| `.text-3xl` | 1.875rem (30px) | 2.25rem | 큰 제목 |
| `.text-4xl` | 2.25rem (36px) | 2.5rem | 메인 제목 |

### 폰트 가중치
```css
.font-normal { font-weight: 400; }    /* 일반 텍스트 */
.font-medium { font-weight: 500; }    /* 약간 굵은 텍스트 */
.font-semibold { font-weight: 600; }  /* 중간 굵기 제목 */
.font-bold { font-weight: 700; }      /* 굵은 제목 */
```

---

## 컴포넌트 디자인 패턴

### 1. 카드 (Card)

#### 기본 카드 스타일
```css
.card {
    background: hsl(var(--card));
    color: hsl(var(--card-foreground));
    border-radius: var(--radius);
    border: 1px solid hsl(var(--border));
    padding: 1.5rem;
    box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
    transition: all 0.2s ease-in-out;
}

.card:hover {
    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}
```

#### 사용 예시
```html
<div class="card">
    <h3 class="text-lg font-semibold">카드 제목</h3>
    <p class="text-sm text-muted-foreground">카드 설명 텍스트</p>
</div>
```

### 2. 버튼 (Button)

#### 버튼 기본 스타일
```css
.btn {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    border-radius: var(--radius);
    font-size: 0.875rem;
    font-weight: 500;
    transition: all 0.15s ease-in-out;
    cursor: pointer;
    outline: none;
    border: none;
}
```

#### 버튼 변형
```css
/* Primary 버튼 */
.btn-primary {
    background: hsl(var(--primary));
    color: hsl(var(--primary-foreground));
    padding: 0.5rem 1rem;
}

.btn-primary:hover {
    background: hsl(var(--primary) / 0.9);
}

/* Secondary 버튼 */
.btn-secondary {
    background: hsl(var(--secondary));
    color: hsl(var(--secondary-foreground));
    padding: 0.5rem 1rem;
}

/* Outline 버튼 */
.btn-outline {
    border: 1px solid hsl(var(--border));
    background: transparent;
    padding: 0.5rem 1rem;
}

/* Ghost 버튼 */
.btn-ghost {
    background: transparent;
    color: hsl(var(--foreground));
    padding: 0.5rem 1rem;
}

.btn-ghost:hover {
    background: hsl(var(--accent));
}
```

#### 버튼 크기
```css
.btn-sm { 
    height: 2rem; 
    padding: 0 0.75rem; 
    font-size: 0.75rem; 
}

.btn-md { 
    height: 2.5rem; 
    padding: 0 1rem; 
}

.btn-lg { 
    height: 3rem; 
    padding: 0 2rem; 
    font-size: 1rem; 
}
```

#### 사용 예시
```html
<button class="btn btn-primary btn-md">저장</button>
<button class="btn btn-secondary btn-md">취소</button>
<button class="btn btn-outline btn-sm">편집</button>
<button class="btn btn-ghost">더보기</button>
```

### 3. 입력 필드 (Input)

#### 입력 필드 스타일
```css
.input {
    display: flex;
    height: 2.5rem;
    width: 100%;
    border-radius: var(--radius);
    border: 1px solid hsl(var(--input));
    background: hsl(var(--background));
    padding: 0.5rem 0.75rem;
    font-size: 0.875rem;
    transition: all 0.15s ease-in-out;
}

.input:focus {
    outline: none;
    border-color: hsl(var(--ring));
    box-shadow: 0 0 0 3px hsl(var(--ring) / 0.1);
}

.input:disabled {
    cursor: not-allowed;
    opacity: 0.5;
}

.input::placeholder {
    color: hsl(var(--muted-foreground));
}
```

#### 사용 예시
```html
<input type="text" class="input" placeholder="이름을 입력하세요">
<input type="email" class="input" placeholder="이메일" disabled>
```

### 4. 폼 그룹 (Form Group)

#### 폼 그룹 스타일
```css
.form-group {
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
    margin-bottom: 1rem;
}

.form-label {
    font-size: 0.875rem;
    font-weight: 500;
    color: hsl(var(--foreground));
}

.form-description {
    font-size: 0.75rem;
    color: hsl(var(--muted-foreground));
}

.form-error {
    font-size: 0.75rem;
    color: hsl(var(--destructive));
}
```

#### 사용 예시
```html
<div class="form-group">
    <label class="form-label">이메일</label>
    <input type="email" class="input" placeholder="your@email.com">
    <span class="form-description">로그인에 사용할 이메일 주소입니다.</span>
</div>

<div class="form-group">
    <label class="form-label">비밀번호</label>
    <input type="password" class="input">
    <span class="form-error">비밀번호는 8자 이상이어야 합니다.</span>
</div>
```

---

## 스페이싱 시스템

### 간격 유틸리티 클래스
| 클래스 | 크기 | 픽셀 | 사용처 |
|--------|------|------|--------|
| `.space-xs` | 0.25rem | 4px | 매우 작은 간격 |
| `.space-sm` | 0.5rem | 8px | 작은 간격 |
| `.space-md` | 0.75rem | 12px | 중간 간격 |
| `.space-lg` | 1rem | 16px | 기본 간격 |
| `.space-xl` | 1.5rem | 24px | 큰 간격 |
| `.space-2xl` | 2rem | 32px | 매우 큰 간격 |
| `.space-3xl` | 3rem | 48px | 초대형 간격 |

```css
.space-xs { gap: 0.25rem; }
.space-sm { gap: 0.5rem; }
.space-md { gap: 0.75rem; }
.space-lg { gap: 1rem; }
.space-xl { gap: 1.5rem; }
.space-2xl { gap: 2rem; }
.space-3xl { gap: 3rem; }
```

### Border Radius (모서리 둥글기)
```css
.rounded-none { border-radius: 0; }
.rounded-sm { border-radius: 0.25rem; }   /* 4px */
.rounded { border-radius: var(--radius); }  /* 8px (기본값) */
.rounded-md { border-radius: 0.5rem; }     /* 8px */
.rounded-lg { border-radius: 0.75rem; }    /* 12px */
.rounded-xl { border-radius: 1rem; }       /* 16px */
.rounded-full { border-radius: 9999px; }   /* 완전한 원형 */
```

---

## 애니메이션 및 트랜지션

### 기본 트랜지션
```css
.transition-all {
    transition-property: all;
    transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
    transition-duration: 150ms;
}

.transition-colors {
    transition-property: color, background-color, border-color;
    transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
    transition-duration: 150ms;
}
```

### 페이드 인 애니메이션
```css
@keyframes fadeIn {
    from { 
        opacity: 0; 
        transform: translateY(4px); 
    }
    to { 
        opacity: 1; 
        transform: translateY(0); 
    }
}

.animate-in {
    animation: fadeIn 200ms ease-out;
}
```

### 사용 예시
```html
<div class="card transition-all">Hover me</div>
<div class="animate-in">Fade in content</div>
```

---

## 섀도우 시스템

### 그림자 레벨
```css
.shadow-none { box-shadow: none; }
.shadow-sm { box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05); }
.shadow { box-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06); }
.shadow-md { box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06); }
.shadow-lg { box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05); }
.shadow-xl { box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04); }
```

### 사용 가이드
- **shadow-sm**: 미묘한 깊이가 필요한 카드
- **shadow**: 일반적인 카드 및 요소
- **shadow-md**: 드롭다운, 메뉴
- **shadow-lg**: 모달, 대화상자
- **shadow-xl**: 팝업, 알림

---

## 레이아웃 패턴

### Flexbox 유틸리티
```css
.flex { display: flex; }
.flex-col { flex-direction: column; }
.items-center { align-items: center; }
.items-start { align-items: flex-start; }
.items-end { align-items: flex-end; }
.justify-center { justify-content: center; }
.justify-between { justify-content: space-between; }
.justify-end { justify-content: flex-end; }

.gap-2 { gap: 0.5rem; }
.gap-4 { gap: 1rem; }
.gap-6 { gap: 1.5rem; }
```

### Grid 유틸리티
```css
.grid { display: grid; }
.grid-cols-2 { grid-template-columns: repeat(2, minmax(0, 1fr)); }
.grid-cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
.grid-cols-4 { grid-template-columns: repeat(4, minmax(0, 1fr)); }
```

### 사용 예시
```html
<!-- Flexbox 레이아웃 -->
<div class="flex items-center justify-between gap-4">
    <span>제목</span>
    <button class="btn btn-primary">저장</button>
</div>

<!-- Grid 레이아웃 -->
<div class="grid grid-cols-3 gap-4">
    <div class="card">카드 1</div>
    <div class="card">카드 2</div>
    <div class="card">카드 3</div>
</div>
```

---

## 반응형 디자인

### 브레이크포인트
```css
/* Mobile First 접근 방식 */
@media (min-width: 640px) {  /* sm: 태블릿 세로 */
    /* 스타일 */
}

@media (min-width: 768px) {  /* md: 태블릿 가로 */
    /* 스타일 */
}

@media (min-width: 1024px) { /* lg: 노트북 */
    /* 스타일 */
}

@media (min-width: 1280px) { /* xl: 데스크톱 */
    /* 스타일 */
}

@media (min-width: 1536px) { /* 2xl: 대형 데스크톱 */
    /* 스타일 */
}
```

### 반응형 그리드 예시
```css
.responsive-grid {
    display: grid;
    grid-template-columns: 1fr;
    gap: 1rem;
}

@media (min-width: 640px) {
    .responsive-grid {
        grid-template-columns: repeat(2, 1fr);
    }
}

@media (min-width: 1024px) {
    .responsive-grid {
        grid-template-columns: repeat(3, 1fr);
    }
}

@media (min-width: 1280px) {
    .responsive-grid {
        grid-template-columns: repeat(4, 1fr);
    }
}
```

---

## 접근성 (Accessibility)

### 포커스 관리
```css
*:focus-visible {
    outline: 2px solid hsl(var(--ring));
    outline-offset: 2px;
}
```

### 스크린 리더 전용 텍스트
```css
.sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border-width: 0;
}
```

### 접근성 체크리스트
- ✅ 모든 인터랙티브 요소는 키보드로 접근 가능
- ✅ 포커스 상태가 명확하게 표시됨
- ✅ 색상 대비가 WCAG AA 기준 이상
- ✅ 적절한 ARIA 레이블 사용
- ✅ 의미있는 HTML 요소 사용 (semantic HTML)

---

## 상태 표시

### 상태별 스타일
```css
.state-loading {
    opacity: 0.6;
    cursor: wait;
}

.state-success {
    color: hsl(142.1 76.2% 36.3%);  /* 녹색 */
}

.state-error {
    color: hsl(var(--destructive));  /* 빨간색 */
}

.state-warning {
    color: hsl(48 96% 53%);  /* 노란색 */
}
```

---

## 적용 방법

### 1. CSS 변수 설정
`css/common.css` 파일에 CSS 변수를 추가합니다:

```css
:root {
    /* 위에서 정의한 CSS 변수들 추가 */
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    /* ... 나머지 변수들 */
}
```

### 2. 컴포넌트 스타일 추가
`css/components.css` 파일에 컴포넌트 스타일을 추가합니다:

```css
/* 버튼, 카드, 입력 필드 등 컴포넌트 스타일 */
```

### 3. HTML에서 사용
```html
<!DOCTYPE html>
<html lang="ko">
<head>
    <link rel="stylesheet" href="css/common.css">
    <link rel="stylesheet" href="css/components.css">
</head>
<body>
    <div class="card">
        <h2 class="text-2xl font-bold">제목</h2>
        <p class="text-sm text-muted-foreground">설명</p>
        <button class="btn btn-primary">저장</button>
    </div>
</body>
</html>
```

---

## 사용 원칙

### ✅ DO (권장사항)
- CSS 변수를 사용하여 색상 관리
- 일관된 스페이싱과 border-radius 사용
- 접근성을 고려한 마크업
- 모바일 우선 반응형 디자인
- 의미있는 클래스명 사용

### ❌ DON'T (피해야 할 것)
- 인라인 스타일 사용
- 하드코딩된 색상값
- 불필요한 `!important` 사용
- 키보드 접근이 불가능한 요소
- 색상에만 의존한 정보 전달

---

## 예제 컴포넌트

### 로그인 폼
```html
<div class="card" style="max-width: 400px; margin: 2rem auto;">
    <h2 class="text-2xl font-bold mb-6">로그인</h2>
    
    <div class="form-group">
        <label class="form-label">이메일</label>
        <input type="email" class="input" placeholder="your@email.com">
    </div>
    
    <div class="form-group">
        <label class="form-label">비밀번호</label>
        <input type="password" class="input" placeholder="••••••••">
    </div>
    
    <div class="flex gap-2">
        <button class="btn btn-primary flex-1">로그인</button>
        <button class="btn btn-outline">취소</button>
    </div>
</div>
```

### 대시보드 카드 그리드
```html
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
    <div class="card">
        <h3 class="text-lg font-semibold">총 매출</h3>
        <p class="text-3xl font-bold mt-2">₩12,345,678</p>
        <span class="text-sm state-success">+12.5% 전월 대비</span>
    </div>
    
    <div class="card">
        <h3 class="text-lg font-semibold">신규 고객</h3>
        <p class="text-3xl font-bold mt-2">234</p>
        <span class="text-sm state-error">-5.2% 전월 대비</span>
    </div>
    
    <div class="card">
        <h3 class="text-lg font-semibold">주문 건수</h3>
        <p class="text-3xl font-bold mt-2">1,234</p>
        <span class="text-sm state-success">+8.1% 전월 대비</span>
    </div>
</div>
```

---

## 참고 자료

- [shadcn/ui 공식 사이트](https://ui.shadcn.com/)
- [Tailwind CSS 문서](https://tailwindcss.com/docs)
- [WCAG 접근성 가이드](https://www.w3.org/WAI/WCAG21/quickref/)

---

## 변경 이력

| 날짜 | 버전 | 변경 내용 |
|------|------|-----------|
| 2025-10-26 | 1.0 | 초기 문서 작성 |