---
name: pds
description: "Partner Design System (PDS) React 컴포넌트 라이브러리 사용 가이드. 다음 상황에서 이 스킬을 활성화하라 - (1) @croquiscom/pds import가 있는 코드 작성/수정 시, (2) React UI 컴포넌트 구현 시 PDS 사용 여부 확인, (3) Modal, DataTable, Button, Stack 등 PDS 컴포넌트 props 검증 필요 시, (4) semantic_colors, spacing 등 Foundation 토큰 사용 시. PDS는 다른 라이브러리(MUI, Ant Design, Chakra)와 props 네이밍이 다르므로 이 문서의 Naming Differences 테이블을 반드시 따르라."
---

# PDS Design System Skills

## Critical Context

PDS는 카카오스타일에서 개발한 공식 디자인 시스템으로, 다양한 프로젝트에서 사용할 수 있다.

**핵심 특성**:
- **Figma 강결합**: 레이아웃, 형태, 위치는 디자이너의 Figma 디자인 결정을 따른다
- **독자적인 네이밍**: 다른 디자인 시스템(antd, Material-UI, Chakra UI)과 다른 props 네이밍을 사용한다

**필수 원칙**:
- 다른 라이브러리 props를 추측하여 사용하지 마라
- Foundation 토큰을 사용하라. 하드코딩하지 마라
- 이 문서의 Naming Differences 테이블과 Quick Reference를 따르라

---

## 문서 참조 전략 (3-Tier Progressive Disclosure)

### Tier 0: 이 문서 (추가 로드 없음)

대부분의 PDS 코드 작성은 **이 문서만으로 충분하다.** 리소스 파일을 읽기 전에 아래 섹션을 먼저 확인하라:
- **Quick Reference** → 컴포넌트별 필수 props, 주의사항, 리소스 파일명
- **비표준 호출 패턴** → `await Confirm()`, `useToast()` 등 **코드가 이미 있다. 추가 로드 불필요.**
- **Naming Differences** → 올바른 prop 이름 확인
- **Foundation Tokens** → 토큰 import 방법

**Tier 0으로 충분한 경우** (리소스 파일 로드 불필요):
- 비표준 호출 패턴에 코드가 있는 컴포넌트 (Toast, ConfirmModal, AlertModal, Notification)
- Quick Reference에 필수 props가 명시된 단순 컴포넌트 (Button, Badge, Switch 등)
- Naming Differences로 prop 이름만 확인하면 되는 경우

### Tier 1: Props 레퍼런스 (1회 로드)

Quick Reference에 없는 **세부 prop 타입, 설명, 기본값**이 필요할 때만 읽어라.

파일 경로는 Quick Reference의 **"리소스" 컬럼**을 사용하라:
```
resources/components/{리소스}.props.txt
```

> **잘못된 경로를 추측하지 마라.** 파일명을 모르면 `resources/index.txt`를 먼저 확인하라.

### Tier 2: Examples (거의 불필요)

> **Tier 0 + Tier 1 = 100% 커버리지.** 대부분의 구현에서 examples.txt를 읽을 필요가 없다.

**읽지 마라** (기본 원칙):
- 비표준 호출 패턴 섹션에 코드가 이미 있는 경우
- Quick Reference의 props 정보만으로 구현 가능한 경우
- Props 레퍼런스(Tier 1)로 타입/기본값을 확인한 경우

**다음 경우에만** examples를 읽어라 (극히 드문 경우):
- DataTable의 custom cell renderer 구현 시 구체적인 render 함수 패턴이 필요한 경우
- 여러 컴포넌트를 합성하는 복잡한 패턴의 구체적 코드가 필요한 경우

```
resources/components/{리소스}.examples.txt
```

### 기타 가이드
- Foundation 토큰 상세: `resources/guides/guide-foundation-usage.md`
- 흔한 실수 방지: `resources/guides/guide-common-mistakes.md`
- 처음 PDS 사용: `resources/guides/guide-getting-started.md`

---

## Naming Differences (중요)

| 기능 | Material-UI | Ant Design | Chakra UI | **PDS** |
| --- | --- | --- | --- | --- |
| **닫기 이벤트** | `onClose` | `onClose` | `onClose` | **`onClose`** |
| **열림 상태** | `open` | `open` | `isOpen` | **`opened`** |
| **스타일 종류** | `variant` | `type` | `variant` | **`kind`** |
| **열림 상태** | `open` | `open` | `isOpen` | **`opened`** |
| **상태** | `error` | `status` | `isInvalid` | **`status`** |
| **모달 열림 상태** | `open` | `visible` | `isOpen` | **`opened`** |
| **닫기 이벤트** | `onClose` | `onCancel` | `onClose` | **`onCancel`** |
| **Pagination 현재** | `page` | `current` | `page` | **`currentPage`** |
| **Pagination 전체** | `count` | `total` | `pageCount` | **`totalPages`** |
| **Pagination 변경** | `onChange` | `onChange` | `onChange` | **`onChangePage`** |
| **열림 상태** | `open` | `open` | `isOpen` | **`opened`** |
| **Stack spacing** | `spacing={2}` | `gutter={16}` | `spacing={4}` | **`gap`** |
| **선택 상태** | `checked` | `checked` | `isChecked` | **`isOn`** |
| **테이블 데이터** | `data` | `dataSource` | `data` | **`rows`** |
| **Tabs 활성** | `value` | `activeKey` | `index` | **`activeTabId`** |
| **Toast 표시** | `enqueueSnackbar()` | `message.info()` | `toast()` | **`toast.show()`** |
| **열림 상태** | `open` | `open` | `isOpen` | **`opened`** |

---

## Quick Reference: 컴포넌트별 필수 Props

| 컴포넌트 | 필수/주요 Props | 주의사항 | 리소스 |
|---------|----------------|---------|--------|
| **Banner** | `status`, `closable`, `onClose` | 닫기 버튼이 필요하면 closable과 onClose를 함께 사용한다 | `component-banner` |
| **BottomSheet** | `opened`, `onClose` | Modal의 onCancel과 다르게 onClose를 사용한다 | `component-bottomsheet` |
| **Button** | `kind` | variant, color가 아니다 | `component-button-button` |
| **CheckboxGroup** | `spacing` | gap이 아니라 spacing을 사용하라 | `component-control-checkboxgroup` |
| **SelectChip** | `variant`, `size`, `selected` | undefined | `component-chip-selectchip` |
| **DatePickerV2** | `value`, `onChange` | value는 CalendarItem[] 배열이다 ({id, from, to}) | `component-datepickerv2-datepickerv2` |
| **Divider** | `spacing` | gap이 아니라 spacing을 사용하라 | `component-divider` |
| **Drawer** | `opened`, `onClose`, `direction` | Modal의 onCancel과 다르게 onClose를 사용한다 | `component-drawer` |
| **Dropdown** | `options`, `value`, `onChange` | 제어 컴포넌트 (value+onChange 필수). FormField status 자동 공유 | `component-dropdown` |
| **FormField** | `status`, `size`, `alignment` | status는 Input/Dropdown/DropdownInput/NumericInput에만 자동 전달됩니다. size는 라벨과 children wrapper 높이를 맞추는 값이므로, 자식 form control의 size는 직접 지정하세요. alignment는 deprecated이며 항상 상단 정렬됩니다 | `component-form-formfield` |
| **Input** | `status`, `size` | FormField status가 자동 공유된다 | `component-input` |
| **Menu** | `selectedMenu`, `onClickMenu` | MenuItem, MenuGroup의 id로 selectedMenu를 제어하라. MenuGroup 필수: `id`, `label`. MenuItem 필수: `id`, `label` | `component-menu` |
| **AlertModal** | `kind`, `title` | Alert() 함수로 호출하라. <AlertModal> 직접 렌더링 금지 | `component-modal-alertmodal` |
| **ConfirmModal** | `kind`, `title` | Confirm() 함수로 호출하라. <ConfirmModal> 직접 렌더링 금지 | `component-modal-confirmmodal` |
| **Modal** | `opened`, `onCancel` | JSX로 직접 렌더링하라 (Alert/Confirm과 다름). onCancel은 reason 파라미터를 받는다 | `component-modal-basicmodal` |
| **Notification** | `useNotification()`, `notification.show()` | 컴포넌트를 직접 렌더링하지 마라. Hook으로 호출 | `component-notification` |
| **Pagination** | `currentPage`, `totalPages`, `onChangePage` | 1-based 인덱싱이다 | `component-pagination-pagination` |
| **Popover** | `content` | content 또는 title/description 중 하나 필수 | `component-popover` |
| **RadioGroup** | `spacing` | gap이 아니라 spacing을 사용하라 | `component-control-radiogroup-radio` |
| **Stack** | `direction`, `gap` | VStack/HStack은 deprecated | `component-stack-stack` |
| **Switch** | `isOn` | checked가 아니라 isOn을 사용한다 | `component-control-switch` |
| **DataTable** | `rows`, `columns` | useMemo로 메모이제이션하라. 행 선택은 selectableRows+onSelectRows를 사용하라 (커스텀 체크박스 금지). ColumnType 필수: `id`, `text`. ColumnGroupType 필수: `text`. StickyHeaderConfig 필수: `mode` | `component-table-datatable` |
| **LineTabs** | `activeTabId`, `onChange` | LineTab에 id가 필수다. LineTab 필수: `id` | `component-linetabs` |
| **TimeChipInput** | `value`, `onChange` | 제어 컴포넌트 (value+onChange 필수). value는 Date|null, onChange는 시·분이 자동 채워진 완성 Date를 받는다 | `component-timechipinput` |
| **Toast** | `useToast()`, `toast.show()` | 컴포넌트를 직접 렌더링하지 마라 | `component-toast` |
| **Tooltip** | `content` | children이 reference element이다 | `component-tooltip-basic` |

---

## 비표준 호출 패턴 (Non-Declarative Components)

일부 컴포넌트는 `<Component />` 선언형이 아닌 함수/Hook 호출로 사용한다:

### Promise 기반 호출

```tsx
const result = await Alert({ title: '제목', text: '내용', confirmText: '...' });
const result = await Confirm({ title: '제목', text: '내용', confirmText: '...', cancelText: '...', subtext: '...' });
```

### Hook 기반 호출

```tsx
const notification = useNotification();
notification.show({ content: '메시지', title: '...', linkText: '...', closeButton: '...' });
const toast = useToast();
toast.show({ content: '메시지' });
```

---

## Foundation Tokens Quick Reference

**사용하라**:
- `semantic_colors`: 색상 토큰
- `spacing`: 간격 토큰 (spacing_N = N × 4px)
- `shapes`: 모양 토큰 (border_radius 등)
- `text_styles`: 타이포그래피 토큰

**사용하지 마라**:
- 하드코딩된 색상 값 (`#333333`, `rgb(51, 51, 51)`)
- 하드코딩된 간격 값 (`16px`, `1rem`)
- 하드코딩된 크기 값 (`8px`, `12px`)

```tsx
import { semantic_colors, spacing, shapes } from '@croquiscom/pds';
```

상세한 토큰 사용법은 `resources/guides/foundation-usage.md`를 참조하라.

---

## 아이콘 선택

이모지 대신 정의된 PDS 아이콘 컴포넌트를 사용하라. 다른 오픈소스 라이브러리의 아이콘 이름을 추측하지 마라.

- 아이콘 컴포넌트 선택: `resources/guides/guide-icon-mapping.md`
  - **Read 전에 Grep**. 사용 맥락 키워드(예: `"닫기"`, `"더보기"`, `"알림"`, `"햄버거"`)로 검색하라.
  - 표 첫 컬럼이 카테고리(`방향`, `액션`, `UI` 등 20종)이므로 매치 행만으로 분류·코드명·사용 맥락 즉시 파악.
- 이모지/Unicode 기호 → 코드 매핑: `resources/guides/guide-icon-unicode-lookup.md`
  - **Read 전에 Grep**. Unicode 문자나 이모지(예: `"⚠️"`, `"🔍"`, `"←"`, `"☰"`)로 직접 검색하라.
  - 표 첫 컬럼이 Unicode 기호이므로 매치 행에 대응하는 PDS 아이콘 후보가 즉시 나온다.

---

## Resources

### 가이드 문서 (`resources/guides/`)
- `guide-common-mistakes.md`: 흔한 실수 (Common Mistakes)
- `guide-component-decision-tree.md`: Component Decision Tree
- `guide-composition-patterns.md`: PDS 합성 패턴 가이드
- `guide-foundation-usage.md`: Foundation 토큰 사용법
- `guide-getting-started.md`: 시작하기
- `guide-icon-mapping.md`: 아이콘 매핑 및 사용 가이드
- `guide-icon-unicode-lookup.md`: 아이콘 Unicode 역방향 인덱스
- `guide-style-utilities.md`: 스타일 유틸리티

### 컴포넌트 레퍼런스 (`resources/components/`)

**인덱스**: `resources/index.txt` - 전체 컴포넌트 목록 (108개)

**파일 패턴** (Quick Reference의 "리소스" 컬럼 참조):
- `{리소스}.props.txt` — Tier 1: Props 상세 (타입, 기본값, 설명)
- `{리소스}.examples.txt` — Tier 2: 사용 예제 (render 패턴, 합성 등)

---

## Verification Checklist

코드 생성 전 다음을 확인하라:

- [ ] 이 문서의 Naming Differences 테이블을 따랐는가?
- [ ] 다른 라이브러리의 Props를 추측하여 사용하지 않았는가?
- [ ] Foundation 토큰을 사용했는가? (하드코딩 금지)
- [ ] VStack/HStack 대신 Stack을 사용했는가?
- [ ] CheckboxGroup, RadioGroup, Divider에 gap 대신 spacing을 사용했는가?
- [ ] 이모지 대신 정의된 PDS 아이콘을 사용했는가? (mapping guide 참조)

---

**문서 버전**: v16.65.0
**마지막 업데이트**: 2026-07-21