# 디자인 시스템 관리 가이드

## 개요

SAM MES의 모든 UI 컴포넌트는 아토믹 디자인 원칙에 따라 구성되어 있으며, "디자인시스템" 페이지를 통해 중앙에서 관리할 수 있습니다.

## 접근 방법

1. **SystemAdmin** 계정으로 로그인
2. 좌측 메뉴에서 **기준정보 관리** 클릭
3. 하위 메뉴에서 **디자인시스템** 클릭

## 아토믹 디자인 계층 구조

### 1. Atoms (원자) - 6개
더 이상 쪼갤 수 없는 기본 컴포넌트

- **Button** (`/components/ui/button.tsx`)
  - Variants: default, destructive, outline, secondary, ghost, link
  - 사용처: 모든 페이지의 액션 버튼

- **Input** (`/components/ui/input.tsx`)
  - 텍스트 입력 필드
  - 사용처: 폼, 검색바

- **Label** (`/components/ui/label.tsx`)
  - 폼 레이블
  - 사용처: 모든 입력 필드

- **Badge** (`/components/ui/badge.tsx`)
  - Variants: default, secondary, destructive, outline
  - 사용처: 상태 표시, 카테고리 태그

- **Switch** (`/components/ui/switch.tsx`)
  - 토글 스위치
  - 사용처: 설정 페이지, 활성화/비활성화

- **Checkbox** (`/components/ui/checkbox.tsx`)
  - 체크박스
  - 사용처: 다중 선택, 동의 확인

### 2. Molecules (분자) - 6개
2개 이상의 Atoms가 결합된 컴포넌트

- **FormField** (`/components/molecules/FormField.tsx`)
  - Label + Input 조합
  - 사용처: 모든 폼 페이지

- **SearchBar** (`/components/molecules/SearchBar.tsx`)
  - 검색 아이콘 + Input 조합
  - 사용처: 목록 페이지 상단

- **StatCard** (`/components/molecules/StatCard.tsx`)
  - 아이콘 + 제목 + 값 조합
  - 사용처: 대시보드 통계 카드

- **StatusBadge** (`/components/molecules/StatusBadge.tsx`)
  - 상태에 따라 자동으로 색상이 매핑되는 배지
  - 사용처: 테이블의 상태 컬럼

- **TableActions** (`/components/molecules/TableActions.tsx`)
  - 보기/수정/삭제 버튼 그룹
  - 사용처: 테이블의 액션 컬럼

- **IconWithBadge** (`/components/molecules/IconWithBadge.tsx`)
  - 아이콘 + 숫자 배지 조합
  - 사용처: 알림, 카운트 표시

### 3. Organisms (유기체) - 8개
복잡한 기능을 가진 큰 컴포넌트

- **PageHeader** (`/components/organisms/PageHeader.tsx`)
  - 아이콘 + 제목 + 부제목
  - **모든 페이지의 표준 헤더**
  - 사용처: 모든 페이지 상단

- **StatCards** (`/components/organisms/StatCards.tsx`)
  - 4개의 StatCard를 그리드로 배치
  - **표준 페이지 포맷의 2번째 섹션**
  - 사용처: 대시보드, 목록 페이지

- **SearchFilter** (`/components/organisms/SearchFilter.tsx`)
  - 검색바 + 필터 버튼 + 액션 버튼
  - **표준 페이지 포맷의 3번째 섹션**
  - 사용처: 목록 페이지

- **DataTable** (`/components/organisms/DataTable.tsx`)
  - 테이블 + 페이지네이션
  - 사용처: 모든 목록 페이지

- **PageLayout** (`/components/organisms/PageLayout.tsx`)
  - 페이지 전체 레이아웃 래퍼
  - 사용처: 모든 페이지

- **EmptyState** (`/components/organisms/EmptyState.tsx`)
  - 데이터 없음 상태 표시
  - 사용처: 빈 테이블, 빈 목록

- **FormSection** (`/components/organisms/FormSection.tsx`)
  - 폼 필드를 그룹화하는 섹션
  - 사용처: 등록/수정 페이지

- **MobileCard** (`/components/organisms/MobileCard.tsx`)
  - 모바일 반응형 카드
  - 사용처: 모바일 환경의 목록

### 4. Templates (템플릿) - 4개
페이지 레이아웃 템플릿

- **DashboardTemplate** (`/components/templates/DashboardTemplate.tsx`)
  - PageHeader → StatCards → 컨텐츠 그리드
  - 사용처: 대시보드 페이지

- **ListPageTemplate** (`/components/templates/ListPageTemplate.tsx`)
  - PageHeader → StatCards → SearchFilter → DataTable
  - **가장 많이 사용되는 표준 템플릿**
  - 사용처: 품목관리, 거래처관리 등 모든 목록 페이지

- **FormPageTemplate** (`/components/templates/FormPageTemplate.tsx`)
  - PageHeader → FormSection[] → 액션 버튼
  - 사용처: 등록/수정 페이지

- **TabbedPageTemplate** (`/components/templates/TabbedPageTemplate.tsx`)
  - PageHeader → Tabs → 탭별 컨텐츠
  - 사용처: 탭이 있는 복합 페이지

## 표준 페이지 구조

모든 페이지는 다음 순서를 따라야 합니다:

```
1. PageHeader (제목 + 부제목 + 아이콘)
   ↓
2. StatCards (대시보드 통계 4개)
   ↓
3. SearchFilter (검색/필터)
   ↓
4. Content (메인 컨텐츠 - Table, Form 등)
```

## 디자인 토큰 관리

모든 스타일은 `/styles/globals.css`에서 CSS 변수로 중앙 관리됩니다.

### 주요 디자인 토큰

#### 색상 (Colors)
- `--primary`: #3B82F6 (주요 액션 색상)
- `--secondary`: #F1F5F9 (보조 색상)
- `--background`: #FAFAFA (배경 색상)
- `--foreground`: #1A1A1A (텍스트 색상)
- `--destructive`: #EF4444 (삭제/경고 색상)
- `--border`: #E2E8F0 (테두리 색상)
- `--muted`: #F8FAFC (비활성 색상)

#### 타이포그래피 (Typography)
- `--font-family`: Pretendard
- `--font-size`: 16px
- `--font-weight-normal`: 400
- `--font-weight-medium`: 500

#### 간격 & 레이아웃 (Spacing)
- `--radius`: 0.75rem (기본 border-radius)

### 디자인 토큰 수정 방법

1. `/styles/globals.css` 파일 열기
2. `:root` 섹션에서 원하는 토큰 값 수정
3. 저장 시 전체 시스템에 자동 반영

예시:
```css
:root {
  --primary: #3B82F6; /* 이 값을 변경하면 모든 버튼, 링크 등의 색상이 변경됨 */
  --radius: 0.75rem; /* 이 값을 변경하면 모든 컴포넌트의 모서리가 변경됨 */
}
```

## 디자인 시스템 페이지 기능

### 1. 개요 탭
- 아토믹 디자인 시스템 설명
- 계층 구조 안내
- 표준 페이지 구조 설명

### 2. Atoms/Molecules/Organisms/Templates 탭
- 각 컴포넌트의 파일 경로 확인
- 사용법 코드 예제 제공
- 코드 복사 버튼 (클릭 한 번으로 복사)
- Variants 정보 표시

### 3. Design Tokens 탭
- 현재 적용된 디자인 토큰 값 확인
- 색상 미리보기
- globals.css 수정 안내

## 컴포넌트 수정 시 주의사항

### ⚠️ 중요: 영향 범위 확인

컴포넌트를 수정할 때는 아래 사항을 반드시 확인하세요:

1. **Atoms 수정** → 모든 페이지에 영향
   - 예: Button 수정 시 모든 버튼이 변경됨

2. **Molecules 수정** → 해당 Molecule을 사용하는 모든 페이지에 영향
   - 예: FormField 수정 시 모든 폼이 변경됨

3. **Organisms 수정** → 해당 Organism을 사용하는 페이지들에 영향
   - 예: PageHeader 수정 시 모든 페이지 헤더가 변경됨

4. **Templates 수정** → 해당 Template을 사용하는 페이지들에 영향
   - 예: ListPageTemplate 수정 시 모든 목록 페이지가 변경됨

### ✅ 권장 수정 방법

1. **새 Variant 추가**: 기존 컴포넌트는 유지하고 새로운 옵션 추가
2. **Props 추가**: 기존 기능은 유지하고 선택적 props 추가
3. **테스트**: 여러 페이지에서 변경사항 확인

## 새 페이지 생성 시 체크리스트

새 페이지를 만들 때는 다음을 따르세요:

- [ ] ListPageTemplate, FormPageTemplate 등 적절한 Template 사용
- [ ] PageHeader로 페이지 헤더 구성
- [ ] 가능한 경우 StatCards로 통계 표시 (4개)
- [ ] 목록 페이지인 경우 SearchFilter 사용
- [ ] DataTable로 데이터 표시
- [ ] FormField로 입력 필드 구성
- [ ] StatusBadge로 상태 표시
- [ ] TableActions로 액션 버튼 구성

## 통계

- **총 Atoms**: 6개 (Button, Input, Label, Badge, Switch, Checkbox)
- **총 Molecules**: 6개 (FormField, SearchBar, StatCard, StatusBadge, TableActions, IconWithBadge)
- **총 Organisms**: 8개 (PageHeader, StatCards, SearchFilter, DataTable, PageLayout, EmptyState, FormSection, MobileCard)
- **총 Templates**: 4개 (DashboardTemplate, ListPageTemplate, FormPageTemplate, TabbedPageTemplate)

## 추가 리소스

- 아토믹 디자인 시스템: `/ATOMIC_DESIGN_SYSTEM.md`
- 공통 컴포넌트 가이드: `/COMMON_COMPONENTS_GUIDE.md`
- 표준 페이지 포맷: `/STANDARD_PAGE_FORMAT.md`
- Shadcn UI 컴포넌트: `/components/ui/` 디렉토리

## 문의

디자인 시스템 관련 문의사항은 개발팀에 문의하세요.
