@x-plat/design-system 0.5.0 → 0.5.2

package/guidelines/Guidelines.md

@@ -0,0 +1,57 @@
+# @x-plat/design-system Guidelines
+
+React 기반 디자인 시스템 라이브러리이다. Figma Make Kit과 1:1 대응한다.
+
+---
+
+## 핵심 규칙
+
+1. **컴포넌트에 `color`, `className`, `style` prop이 없다.** 색상과 스타일은 내부 semantic 토큰으로 고정한다.
+2. **레이아웃 조절은 래퍼 `<div>`로 감싸서 래퍼에만 스타일을 적용한다.**
+3. **CSS로 DS 컴포넌트 스타일을 오버라이드하지 않는다.**
+
+```tsx
+// 올바른 방법
+<div className="button-wrapper">
+  <Button type="primary">저장</Button>
+</div>
+
+// 금지
+<Button style={{ marginBottom: "1rem" }}>저장</Button>
+```
+
+---
+
+## 읽기 순서
+
+아래 순서로 읽는다.
+
+1. **[설치 및 설정](./setup.md)** - CSS/컴포넌트 import, ToastProvider 설정
+2. **파운데이션**
+   - [컬러](./foundations/color.md) - 4레이어 semantic 토큰
+   - [스페이싱](./foundations/spacing.md) - space, radius, stroke
+   - [타이포그래피](./foundations/typography.md) - font, size, weight
+   - [아이콘](./foundations/icons.md) - import, 크기/색상, 카테고리
+3. **컴포넌트**
+   - [Button](./components/button.md)
+   - [Input](./components/input.md) - Input, PasswordInput, TextArea
+   - [Select](./components/select.md)
+   - [Table](./components/table.md)
+   - [피드백](./components/feedback.md) - Alert, Toast, Badge
+   - [오버레이](./components/overlay.md) - Modal, Drawer, PopOver, Tooltip
+   - [폼 컨트롤](./components/form.md) - CheckBox, Radio, Switch
+   - [Chip & Tag](./components/chip-tag.md)
+   - [내비게이션](./components/navigation.md) - Tab, CardTab, Breadcrumb, Pagination, Steps
+   - [DatePicker](./components/datepicker.md) - Calendar, DatePicker 4종
+   - [Accordion](./components/accordion.md)
+   - [Avatar](./components/avatar.md)
+   - [Card](./components/card.md)
+   - [Chart](./components/chart.md)
+   - [데이터 표시](./components/data-display.md) - Divider, EmptyState, Skeleton, Spinner
+   - [Dropdown](./components/dropdown.md)
+   - [파일 & 미디어](./components/file-media.md) - FileUpload, ImageSelector, Video
+   - [Swiper](./components/swiper.md)
+   - [HtmlTypeWriter](./components/html-typewriter.md)
+4. **컴포지션**
+   - [Grid](./composition/grid.md) - Grid 시스템, 위젯 패턴
+   - [Layout](./composition/layout.md) - Layout, Header, SideBar

package/guidelines/components/accordion.md

@@ -0,0 +1,72 @@
+# Accordion
+
+접이식 패널을 표시한다. 단일/다중 모드를 지원하며, controlled/uncontrolled 모두 가능하다.
+
+```tsx
+import { Accordion } from "@xplat/design-system";
+```
+
+## Props
+
+### 공통
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| items `*` | `AccordionItemData[]` | — | 아코디언 아이템 배열 |
+| multiple | `boolean` | `false` | 다중 열기 허용 |
+
+### AccordionItemData
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| key `*` | `string` | 고유 식별자 |
+| title `*` | `ReactNode` | 헤더 영역 |
+| content `*` | `ReactNode` | 본문 영역 |
+
+### 단일 모드 (multiple 미지정 또는 false)
+
+| Prop | 타입 | 설명 |
+|------|------|------|
+| activeKey | `string \| null` | 열린 아이템 key (controlled) |
+| defaultActiveKey | `string` | 초기 열린 아이템 key (uncontrolled) |
+| onChange | `(key: string \| null) => void` | 변경 콜백 |
+
+### 다중 모드 (multiple={true})
+
+| Prop | 타입 | 설명 |
+|------|------|------|
+| activeKeys | `string[]` | 열린 아이템 key 목록 (controlled) |
+| defaultActiveKeys | `string[]` | 초기 열린 아이템 key 목록 (uncontrolled) |
+| onChange | `(keys: string[]) => void` | 변경 콜백 |
+
+---
+
+## 사용 예시
+
+### 단일 모드 (uncontrolled)
+
+```tsx
+<Accordion
+  defaultActiveKey="faq-1"
+  items={[
+    { key: "faq-1", title: "질문 1", content: "답변 1" },
+    { key: "faq-2", title: "질문 2", content: "답변 2" },
+  ]}
+/>
+```
+
+### 다중 모드 (controlled)
+
+```tsx
+const [openKeys, setOpenKeys] = useState<string[]>([]);
+
+<Accordion
+  multiple
+  activeKeys={openKeys}
+  onChange={setOpenKeys}
+  items={[
+    { key: "a", title: "섹션 A", content: <div>내용 A</div> },
+    { key: "b", title: "섹션 B", content: <div>내용 B</div> },
+  ]}
+/>
+```

package/guidelines/components/avatar.md

@@ -0,0 +1,35 @@
+# Avatar
+
+프로필 이미지 또는 이니셜을 표시한다. `src`가 있으면 이미지를 렌더하고, 없으면 `name` 기반 이니셜을 표시한다. 둘 다 없으면 기본 사람 아이콘을 표시한다.
+
+```tsx
+import { Avatar } from "@xplat/design-system";
+```
+
+## Props
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| src | `string` | — | 이미지 URL |
+| alt | `string` | name 또는 `"avatar"` | 이미지 alt 텍스트 |
+| name | `string` | — | 이니셜 생성용 이름 (예: `"홍 길동"` → `"홍길"`) |
+| size | `"sm" \| "md" \| "lg"` | `"md"` | 크기 |
+
+## 색상 자동 배정
+
+`name`의 첫 글자 charCode 기반으로 8가지 categorical color 중 하나를 자동 배정한다. 같은 이름은 항상 같은 색상이 된다.
+
+---
+
+## 사용 예시
+
+```tsx
+// 이미지
+<Avatar src="/profile.jpg" name="김철수" size="lg" />
+
+// 이니셜 (이미지 없음)
+<Avatar name="홍 길동" size="md" />
+
+// 기본 아이콘 (이름도 없음)
+<Avatar size="sm" />
+```

package/guidelines/components/button.md

@@ -0,0 +1,58 @@
+# Button
+
+## Type
+
+| type | 용도 |
+|------|------|
+| primary | 주요 액션 |
+| secondary | 보조 액션 |
+| danger | 삭제/위험 액션 |
+| ghost | 텍스트만 표시 |
+
+## Size
+
+| size | 높이 |
+|------|------|
+| sm | 32px |
+| md | 40px |
+| lg | 48px |
+
+## 상태
+
+| 상태 | 설명 |
+|------|------|
+| default | 기본 |
+| hover | 마우스 오버 |
+| pressed (`:active`) | 클릭 중 |
+| focused (`:focus-visible`) | 키보드 포커스 |
+| disabled | 비활성화 |
+
+---
+
+## 올바른 예시
+
+```tsx
+<Button type="primary" size="md">확인</Button>
+<Button type="secondary" size="lg">취소</Button>
+<Button type="danger">삭제</Button>
+<Button type="primary" disabled>비활성</Button>
+```
+
+## 잘못된 예시
+
+```tsx
+// 금지: style prop 사용
+<Button style={{ backgroundColor: "red" }}>삭제</Button>
+
+// 금지: className 사용
+<Button className="custom-btn">확인</Button>
+```
+
+---
+
+## 유사 컴포넌트 구분
+
+| 목적 | 사용할 것 |
+|------|----------|
+| 페이지/외부 링크 이동 | `<a>` 또는 라우터 Link |
+| 액션 실행 | Button |

package/guidelines/components/card.md

@@ -0,0 +1,28 @@
+# Card
+
+콘텐츠를 카드 형태로 감싸는 컨테이너이다.
+
+```tsx
+import { Card } from "@xplat/design-system";
+```
+
+## Props
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| children `*` | `ReactNode` | — | 카드 본문 |
+| title | `string` | — | 카드 상단 제목 |
+
+---
+
+## 사용 예시
+
+```tsx
+<Card title="매출 현황">
+  <p>이번 달 매출: 1,200만원</p>
+</Card>
+
+<Card>
+  <p>제목 없는 카드</p>
+</Card>
+```

package/guidelines/components/chart.md

@@ -0,0 +1,58 @@
+# Chart
+
+SVG 기반 차트를 렌더한다. line, bar, pie, doughnut 4가지 타입을 지원한다.
+
+```tsx
+import { Chart } from "@xplat/design-system";
+```
+
+## Props
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| type `*` | `"line" \| "bar" \| "pie" \| "doughnut"` | — | 차트 타입 |
+| data `*` | `Record<string, number[]>` | — | 데이터셋 (key: 시리즈 이름, value: 값 배열) |
+| labels `*` | `string[]` | — | x축 라벨 배열 |
+| tooltip | `boolean` | `true` | 호버 시 툴팁 표시 |
+
+## 색상
+
+primitive 팔레트 기반으로 시리즈별 색상을 자동 배정한다. line/bar는 `LINE_BAR_PALETTES`, pie/doughnut는 `PIE_PALETTES`를 사용한다.
+
+---
+
+## 사용 예시
+
+### Line
+
+```tsx
+<Chart
+  type="line"
+  labels={["1월", "2월", "3월", "4월"]}
+  data={{
+    매출: [100, 200, 150, 300],
+    비용: [80, 120, 100, 200],
+  }}
+/>
+```
+
+### Bar
+
+```tsx
+<Chart
+  type="bar"
+  labels={["서울", "부산", "대구"]}
+  data={{ 방문자: [500, 300, 200] }}
+/>
+```
+
+### Pie / Doughnut
+
+```tsx
+<Chart
+  type="doughnut"
+  labels={["모바일", "데스크톱", "태블릿"]}
+  data={{ 점유율: [60, 30, 10] }}
+  tooltip={false}
+/>
+```

package/guidelines/components/chip-tag.md

@@ -0,0 +1,49 @@
+# Chip & Tag
+
+## Chip
+
+읽기 전용 라벨이다. 삭제 기능이 없다.
+
+```tsx
+<Chip type="primary">진행중</Chip>
+<Chip type="success">완료</Chip>
+<Chip type="error">실패</Chip>
+```
+
+| type | 용도 |
+|------|------|
+| primary | 기본 강조 |
+| secondary | 보조 |
+| neutral | 중립 |
+| success | 성공 |
+| error | 에러 |
+| warning | 경고 |
+| info | 정보 |
+
+---
+
+## Tag
+
+제거 가능한 태그이다. `onClose`로 삭제를 처리한다.
+
+```tsx
+<Tag onClose={() => handleRemove("react")}>React</Tag>
+<Tag type="categorical" colorIndex={1} onClose={handleRemove}>TypeScript</Tag>
+<Tag disabled>삭제 불가</Tag>
+```
+
+| Prop | 설명 |
+|------|------|
+| type | `"neutral" \| "categorical"` |
+| onClose | 삭제 콜백 |
+| colorIndex | categorical 타입의 색상 인덱스 |
+| disabled | 비활성화 |
+
+---
+
+## 의사결정
+
+| 상황 | 사용할 것 |
+|------|----------|
+| 상태/분류 라벨 (삭제 불필요) | Chip |
+| 사용자가 제거할 수 있는 태그 | Tag |

package/guidelines/components/data-display.md

@@ -0,0 +1,96 @@
+# 데이터 표시: Divider / EmptyState / Skeleton / Spinner
+
+## Divider
+
+구분선을 표시한다.
+
+```tsx
+import { Divider } from "@xplat/design-system";
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| orientation | `"horizontal" \| "vertical"` | `"horizontal"` | 방향 |
+
+```tsx
+<Divider />
+<Divider orientation="vertical" />
+```
+
+---
+
+## EmptyState
+
+빈 상태 안내를 표시한다.
+
+```tsx
+import { EmptyState } from "@xplat/design-system";
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| icon | `ReactNode` | 기본 폴더 아이콘 | 상단 아이콘 |
+| title | `string` | `"데이터가 없습니다"` | 제목 |
+| description | `string` | — | 부가 설명 |
+| action | `ReactNode` | — | 하단 액션 영역 (버튼 등) |
+
+```tsx
+<EmptyState
+  title="검색 결과가 없습니다"
+  description="다른 키워드로 검색해 보세요."
+  action={<Button type="primary">전체 목록</Button>}
+/>
+```
+
+---
+
+## Skeleton
+
+로딩 플레이스홀더를 표시한다.
+
+```tsx
+import { Skeleton } from "@xplat/design-system";
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| variant | `"text" \| "circular" \| "rectangular"` | `"text"` | 형태 |
+| width | `string \| number` | — | 너비 |
+| height | `string \| number` | — | 높이 |
+
+```tsx
+<Skeleton variant="text" width="200px" />
+<Skeleton variant="circular" width={48} height={48} />
+<Skeleton variant="rectangular" width="100%" height={120} />
+```
+
+---
+
+## Spinner
+
+로딩 인디케이터를 표시한다.
+
+```tsx
+import { Spinner } from "@xplat/design-system";
+```
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| size | `"sm" \| "md" \| "lg"` | `"md"` | 크기 |
+| type | `"brand" \| "success" \| "error" \| "warning" \| "info"` | `"brand"` | 색상 타입 |
+
+```tsx
+<Spinner />
+<Spinner size="lg" type="success" />
+```
+
+---
+
+## 의사결정
+
+| 상황 | 사용할 것 |
+|------|----------|
+| 영역 구분선 | Divider |
+| 데이터가 없는 상태 안내 | EmptyState |
+| 콘텐츠 로딩 전 자리 차지 | Skeleton |
+| 로딩 중 표시 (인디케이터) | Spinner |

package/guidelines/components/datepicker.md

@@ -0,0 +1,60 @@
+# DatePicker: Calendar / DatePicker 4종
+
+## Calendar
+
+달력을 표시한다. 이벤트 표시와 `renderDay` 커스텀을 지원한다.
+
+```tsx
+<Calendar
+  events={[{ date: "2026-03-15", type: "success" }]}
+  renderDay={(date) => <span>{date.getDate()}</span>}
+/>
+```
+
+---
+
+## SingleDatePicker
+
+단일 날짜를 선택한다.
+
+```tsx
+<SingleDatePicker value={date} onChange={(d) => setDate(d)} />
+```
+
+## RangeDatePicker
+
+날짜 범위를 선택한다.
+
+```tsx
+<RangeDatePicker startDate={start} endDate={end} onChange={handleRange} />
+```
+
+## InputDatePicker
+
+Input + 드롭다운 형태이다.
+
+```tsx
+<InputDatePicker value={date} onChange={(d) => setDate(d)} />
+```
+
+## PopupDatePicker
+
+버튼 + 모달 형태이다.
+
+```tsx
+<PopupDatePicker
+  type="single"
+  component={<Button>날짜 선택</Button>}
+  value={date}
+  onChange={(d) => setDate(d)}
+/>
+```
+
+---
+
+## 의사결정
+
+| 상황 | 사용할 것 |
+|------|----------|
+| 달력 표시 / 이벤트 | Calendar |
+| 날짜 선택 | DatePicker (Single/Range/Input/Popup) |

package/guidelines/components/dropdown.md

@@ -0,0 +1,49 @@
+# Dropdown
+
+액션 메뉴를 표시한다. `children`이 트리거 역할을 하며, 클릭 시 메뉴가 열린다.
+
+```tsx
+import { Dropdown } from "@xplat/design-system";
+```
+
+## Props
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| items `*` | `DropdownItem[]` | — | 메뉴 아이템 배열 |
+| children `*` | `ReactNode` | — | 트리거 요소 |
+
+### DropdownItem
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| key `*` | `string` | 고유 식별자 |
+| label `*` | `ReactNode` | 표시 텍스트 |
+| onClick | `() => void` | 클릭 콜백 |
+| disabled | `boolean` | 비활성화 |
+| danger | `boolean` | 위험 액션 스타일 (빨간색) |
+
+---
+
+## 사용 예시
+
+```tsx
+<Dropdown
+  items={[
+    { key: "edit", label: "수정", onClick: () => handleEdit() },
+    { key: "copy", label: "복사", onClick: () => handleCopy() },
+    { key: "delete", label: "삭제", onClick: () => handleDelete(), danger: true },
+  ]}
+>
+  <Button type="ghost">더보기</Button>
+</Dropdown>
+```
+
+---
+
+## 유사 컴포넌트 구분
+
+| 목적 | 사용할 것 |
+|------|----------|
+| 값 선택 (폼 필드) | Select |
+| 액션 실행 (메뉴) | Dropdown |

package/guidelines/components/feedback.md

@@ -0,0 +1,64 @@
+# 피드백: Alert / Toast / Badge
+
+## Alert
+
+인라인 알림을 표시한다.
+
+```tsx
+<Alert type="info">정보 메시지</Alert>
+<Alert type="success">성공</Alert>
+<Alert type="warning">경고</Alert>
+<Alert type="error" onClose={() => {}}>에러 (닫기 가능)</Alert>
+```
+
+| Prop | 설명 |
+|------|------|
+| type | `"info" \| "success" \| "warning" \| "error"` |
+| onClose | 닫기 버튼 콜백 (전달 시 닫기 버튼 표시) |
+
+---
+
+## Toast
+
+일시적 알림을 표시한다. **ToastProvider가 앱 최상위에 필수이다.**
+
+```tsx
+// 앱 루트
+<ToastProvider position="top-right">
+  <App />
+</ToastProvider>
+
+// 컴포넌트 내
+const { toast } = useToast();
+toast("success", "저장 완료");
+toast("error", "오류 발생", 5000);
+```
+
+`toast(type, message, duration?)` 형태로 호출한다.
+
+---
+
+## Badge
+
+카운트 또는 도트를 표시한다.
+
+```tsx
+<Badge type="error" count={5}><BellIcon /></Badge>
+<Badge type="success" dot><UserIcon /></Badge>
+```
+
+| Prop | 설명 |
+|------|------|
+| type | `"error" \| "success" \| "warning" \| "info" \| "brand"` |
+| count | 숫자 표시 |
+| dot | 도트만 표시 |
+
+---
+
+## 의사결정
+
+| 상황 | 사용할 것 |
+|------|----------|
+| 인라인 알림 (페이지 내 고정) | Alert |
+| 일시적 알림 (자동 사라짐) | Toast |
+| 카운트/상태 표시 | Badge |