@wishket/design-system 3.5.0 → 3.7.0

package/dist/ai/components/AutoCompleteList.md

@@ -0,0 +1,85 @@
+---
+id: INPUT-01
+component: AutoCompleteList
+version: 0.0.2
+status: draft
+---
+
+# 1. AutoCompleteList
+
+**개정 이력**
+
+- v0.0.1 (2026.09.22): 초안 작성
+- v0.0.2 (2026.09.30): Error Message를 Supporting Text와 별도 요소로 분리 (#1291 리뷰 반영)
+
+## A. Anatomy
+
+Autocomplete는 입력을 받는 **Text Field**와, 입력값에 연관된 제안을 보여주는 **Autocomplete List**로 구성됩니다. 선택된 값은 Text Field 안에 **Input Chip**으로 누적됩니다.
+
+| 요소 | 필수 여부 | 설명 |
+| --- | --- | --- |
+| Text Field (Container) | 필수 | 배경·테두리·패딩을 담당하는 입력 영역. 클릭/포커스 영역의 기준 |
+| Placeholder / Value Text | 필수 | 입력 전에는 Placeholder, 입력 중에는 사용자가 타이핑한 텍스트 |
+| Input Chip | 조건부 | 선택 완료된 항목. 다중 선택 시 누적되며 개별 삭제(×) 가능 |
+| Supporting Text | 선택 | 필드 하단 보조 설명 |
+| Error Message | 조건부 | 오류 시 필드 하단에 노출되는 문구. Supporting Text와 별도 요소이며 함께 노출될 수 있음 |
+| Autocomplete List | 조건부 | Focused 상태에서 필드 아래 노출되는 제안 리스트. 별도 컴포넌트 |
+
+> Autocomplete List의 내부 규격(Item, Divider, IndexBar, Variant)은 **AutoCompleteList 문서**를 따릅니다. 이 문서에서는 Autocomplete가 리스트를 **어떻게 띄우는지**만 정의합니다.
+> 
+
+## B. Description
+
+### 1. 정의
+
+사용자가 텍스트를 입력할 때, 입력값과 연관된 제안 항목을 실시간으로 표시하는 리스트 컴포넌트입니다.
+
+### 2. 사용 시점
+
+- 선택지가 많아(대략 10개 이상) 목록을 훑어 고르는 것이 비효율적일 때 사용합니다.
+- 사용자가 찾으려는 값을 이미 알고 있어 **타이핑이 탐색보다 빠를 때** 사용합니다.
+- 여러 항목을 선택해야 할 때 사용합니다. (선택값이 Chip으로 누적됩니다)
+- 선택지가 적고 고정되어 있다면 **Select**를 사용합니다.
+- 제안 없이 자유 입력만 받는다면 **Input(Text Field)** 을 사용합니다.
+- 입력 후 검색 결과 페이지로 이동하는 것이 목적이라면 **SearchBar**를 사용합니다.
+
+### 3. 키워드
+
+Autocomplete, 자동완성, 오토컴플리트, Typeahead, Combobox, 입력 제안, 다중 선택 입력
+
+### 4. Size
+
+- Autocomplete는 **부모 컨테이너 너비를 100% 채웁니다.** (Fill 고정)
+- Autocomplete List는 **Text Field와 항상 동일한 너비**를 사용합니다. 내용에 따라 넓어지거나 좁아지지 않습니다.
+
+### 5. Do / Don't
+
+**Do**
+
+- Placeholder에는 **무엇을 입력해야 하는지**를 적습니다. (`기술 스택을 입력하세요`)
+- 입력값과 일치하는 부분을 리스트 항목에서 시각적으로 구분해 줍니다.
+- 선택 완료된 항목은 리스트에서 제외하거나 선택 상태로 표시합니다.
+- 오류는 Error Message로 알려주고, 테두리는 Error 색상으로 함께 바꿉니다.
+
+**Don't**
+
+- 선택지가 5개 이하인 경우에 Autocomplete를 쓰지 않습니다. (Select 사용)
+- 리스트를 필드보다 넓거나 좁게 만들지 않습니다.
+- Chip을 가로 스크롤로 감추지 않습니다.
+- 오류가 났다고 Supporting Text를 Error Message로 덮어쓰지 않습니다. 둘은 별도 요소입니다.
+
+## C. Properties
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| Variant | Variant | Default/IndexBar | 피그마 수정 |
+| Scrollbar | Boolean | True / False | 스토리북 추가 |
+
+Item
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| Variant | Variant | Search(Help)/Search(Count)/Search(Result) |  |
+| State | Variant | Enabled/Hovered |  |
+| Leading Icon | Boolean | True / False |  |
+| Skill | Boolean | True / False |  |

package/dist/ai/components/Autocomplete.md

@@ -0,0 +1,82 @@
+---
+id: INPUT-05
+component: Autocomplete
+version: 0.0.2
+status: draft
+---
+
+# 5. Autocomplete
+
+**개정 이력**
+
+- v0.0.1 (2026.09.22): 초안 작성
+- v0.0.2 (2026.09.30): Error Message를 Supporting Text와 별도 요소로 분리 (#1291 리뷰 반영), 사내 Notion 링크 제거 (#1292 리뷰 반영)
+
+## A. Anatomy
+
+Autocomplete는 입력을 받는 **Text Field**와, 입력값에 연관된 제안을 보여주는 **Autocomplete List**로 구성됩니다. 선택된 값은 Text Field 안에 **Input Chip**으로 누적됩니다.
+
+| 요소 | 필수 여부 | 설명 |
+| --- | --- | --- |
+| Text Field (Container) | 필수 | 배경·테두리·패딩을 담당하는 입력 영역. 클릭/포커스 영역의 기준 |
+| Placeholder / Value Text | 필수 | 입력 전에는 Placeholder, 입력 중에는 사용자가 타이핑한 텍스트 |
+| Input Chip | 조건부 | 선택 완료된 항목. 다중 선택 시 누적되며 개별 삭제(×) 가능 |
+| Supporting Text | 선택 | 필드 하단 보조 설명 |
+| Error Message | 조건부 | 오류 시 필드 하단에 노출되는 문구. Supporting Text와 별도 요소이며 함께 노출될 수 있음 |
+| Autocomplete List | 조건부 | Focused 상태에서 필드 아래 노출되는 제안 리스트. 별도 컴포넌트 |
+
+> Autocomplete List의 내부 규격(Item, Divider, IndexBar, Variant)은 **AutoCompleteList 문서**를 따릅니다. 이 문서에서는 Autocomplete가 리스트를 **어떻게 띄우는지**만 정의합니다.
+> 
+
+## B. Description
+
+### 1. 정의
+
+사용자가 텍스트를 입력할 때 연관된 추천 옵션을 자동으로 제안하여 빠른 선택을 돕는 입력 컴포넌트입니다.
+
+### 2. 사용 시점
+
+- 선택지가 많아(대략 10개 이상) 목록을 훑어 고르는 것이 비효율적일 때 사용합니다.
+- 사용자가 찾으려는 값을 이미 알고 있어 **타이핑이 탐색보다 빠를 때** 사용합니다.
+- 여러 항목을 선택해야 할 때 사용합니다. (선택값이 Chip으로 누적됩니다)
+- 선택지가 적고 고정되어 있다면 **Select**를 사용합니다.
+- 제안 없이 자유 입력만 받는다면 **Input(Text Field)** 을 사용합니다.
+- 입력 후 검색 결과 페이지로 이동하는 것이 목적이라면 **SearchBar**를 사용합니다.
+
+### 3. 키워드
+
+Autocomplete, 자동완성, 오토컴플리트, Typeahead, Combobox, 입력 제안, 다중 선택 입력
+
+### 4. Size
+
+- Autocomplete는 **부모 컨테이너 너비를 100% 채웁니다.** (Fill 고정)
+- Autocomplete List는 **Text Field와 항상 동일한 너비**를 사용합니다. 내용에 따라 넓어지거나 좁아지지 않습니다.
+- Chip이 한 줄을 넘으면 **줄바꿈(wrap)** 되며, 필드 높이가 아래로 늘어납니다. 가로 스크롤하지 않습니다.
+- 입력 커서(타이핑 텍스트)는 **항상 마지막 Chip 뒤**에 위치합니다.
+- 필드가 늘어나도 Autocomplete List는 필드 하단 기준 4 간격을 유지합니다.
+
+### 5. Do / Don't
+
+**Do**
+
+- Placeholder에는 **무엇을 입력해야 하는지**를 적습니다. (`기술 스택을 입력하세요`)
+- 입력값과 일치하는 부분을 리스트 항목에서 시각적으로 구분해 줍니다.
+- 선택 완료된 항목은 리스트에서 제외하거나 선택 상태로 표시합니다.
+- 오류는 Error Message로 알려주고, 테두리는 Error 색상으로 함께 바꿉니다.
+
+**Don't**
+
+- 선택지가 5개 이하인 경우에 Autocomplete를 쓰지 않습니다. (Select 사용)
+- 리스트를 필드보다 넓거나 좁게 만들지 않습니다.
+- Chip을 가로 스크롤로 감추지 않습니다.
+- 오류가 났다고 Supporting Text를 Error Message로 덮어쓰지 않습니다. 둘은 별도 요소입니다.
+
+## C. Properties
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| Variant | Variant | Default/IndexBar | 스토리북 추가? |
+| Disabled | Boolean | True / False | 스토리북 추가? |
+| Is Error | Boolean | True / False |  |
+| State | Variant | Enabled/Hovered/Focused | 스토리북 추가? |
+| Supporting Text | Boolean | True / False | 스토리북 추가? |

package/dist/ai/components/Button.md

@@ -0,0 +1,205 @@
+---
+id: INPUT-06
+component: Button
+version: 0.0.3
+status: draft
+---
+
+# 6. Button
+
+**개정 이력**
+
+- v0.0.1 (2026.09.22): 초안 작성
+- v0.0.2 (2026.09.29): Figma `Button 36` 컴포넌트 기준으로 구조 재정리. 세부규칙(컬러 정책, Variant값 등 추가)
+- v0.0.3 (2026.09.30): Properties를 코드(`ButtonProps`)와 일치시킴 — Leading/Trailing Icon prop 제거(children 사용), NeedThrottle 추가. 미결 항목을 `Z. 미결`로 분리, 접근성·Gray 변수명 사실 정정 (#1292 리뷰 반영)
+
+## A. Anatomy
+
+Button은 **Label**을 감싸는 **Container**로 구성되며, 선택적으로 **Leading Icon**, **Trailing Icon**, **Badge**를 가질 수 있습니다.
+
+| 요소 | 필수 여부 | 설명 |
+| --- | --- | --- |
+| Container | 필수 | 배경·테두리·패딩을 담당하는 영역. 터치/클릭 영역의 기준 |
+| Label | 조건부 필수 | 액션을 설명하는 텍스트. Icon-only 유형에서만 생략 가능 |
+| Leading Icon | 선택 | 라벨 앞 아이콘. 액션의 **의미를 보조** |
+| Trailing Icon | 선택 | 라벨 뒤 아이콘. Chevron 등 **동작을 보조** |
+| Badge | 선택 | 라벨 뒤에 위치하는 수량·상태 표시 |
+
+## B. Description
+
+### 1. 정의
+
+명확한 액션을 쉽게 수행할 수 있도록 돕는 기본 인터랙션 컴포넌트입니다.
+
+### **2. 사용 시점**
+
+- 사용자가 즉시 실행할 수 있는 명확한 액션이 있을 때 사용합니다. (`저장`, `제안 보내기`, `확인`)
+- 페이지 이동이 주 목적이고 액션 성격이 약하다면 **Link**를 사용합니다.
+- 상태를 켜고 끄는 것이 목적이라면 **Toggle / Switch / Chip**을 사용합니다.
+
+### **3. 키워드**
+
+Button, Btn, 버튼, CTA, Call to Action, 액션 버튼
+
+### 4. Size
+
+| Size | Height | Padding (좌우) | Font size | Icon size | Icon–Label Gap | Min width |
+| --- | --- | --- | --- | --- | --- | --- |
+| XLarge | 60 | 24 | 17 | 24 | 8 | **88** |
+| Large | 50 | 20 | 16 | 20 | 8 | **72** |
+| Medium | 42 | 16 | 15 | 20 | 6 | **64** |
+| Small | 36 | 14 | 14 | 16 | 4 | **56** |
+
+### 4-1. Width Mode
+
+Button의 너비는 아래 세 가지 모드 중 하나로 동작합니다.
+
+| Mode | 동작 | 사용 상황 |
+| --- | --- | --- |
+| **Hug** (기본) | 콘텐츠 너비에 맞춤. Min width 적용 | 데스크탑 인라인 액션, 테이블/카드 내 액션, 툴바 |
+| **Fill** | 부모 컨테이너 너비를 100% 채움 | 모바일 하단 CTA, 바텀시트, 폼 제출, 모달 액션 영역 |
+| **Fixed** | 고정 너비 지정 | 버튼 그룹의 너비를 강제로 맞춰야 할 때만 예외적으로 사용 |
+
+### 4-2. Min/Max  width
+
+- **Hug 모드에만 적용**됩니다. Fill / Fixed 모드에서는 무시합니다.
+- 다음 경우에는 **적용하지 않습니다.**
+    - **Icon-only**: 정사각형으로 고정합니다. `Min width = Height` (36 / 42 / 50 / 60)
+    - **Text · Ghost 등 좌우 패딩이 없는 유형**: 강제 너비가 생기면 텍스트 정렬선이 깨집니다.
+- 별도의 고정값을 지정하지 않으며, **상한은 부모 컨테이너의 너비**입니다.
+- 다국어 대응이 필요한 경우에만 `320` 수준의 상한을 옵션으로 검토합니다.
+
+### 4-3. Overflow (라벨이 넘칠 때)
+
+1. 버튼 라벨은 **항상 1줄로 고정**하며, 줄바꿈하지 않습니다.
+2. 너비를 초과하면 **말줄임이 아니라 라벨 자체를 짧게 고쳐 쓰는 것이 원칙**입니다. 말줄임된 버튼은 어떤 액션인지 알 수 없습니다.
+3. **예외**: 사용자 입력값이 라벨에 포함되는 경우(`"OOO님께 제안 보내기"`)에 한해 말줄임(`…`)을 허용하며, 이때 전체 문구는 툴팁으로 제공합니다.
+
+### 4-4. Label with icon
+
+- Leading icon: Button label의 추가 설명을 도울 때 사용합니다.
+- Trailing icon: Button의 행동 자체를 강하게 유도할 때 사용합니다.
+
+### 5. Do / Don't
+
+**Do**
+
+- 라벨은 동사 중심으로 짧고 명확하게 작성합니다. (`저장`, `제안 보내기`)
+- 한 화면의 주요 액션(Primary)은 하나로 유지합니다.
+- 버튼 그룹 내에서는 동일한 Size를 사용합니다.
+- 모바일 하단 고정 CTA는 Fill을 사용합니다.
+
+**Don't**
+
+- 라벨 앞뒤에 아이콘을 동시에 넣지 않습니다.
+- 버튼 라벨을 2줄로 표시하거나 말줄임 처리하지 않습니다. (사용자 입력값 제외)
+- Min width보다 좁게 버튼을 축소하지 않습니다.
+- 장식 목적으로 아이콘을 추가하지 않습니다.
+- 페이지 이동만을 목적으로 Button을 남용하지 않습니다.
+
+## C. Properties
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| Children | ReactNode | Label (+ Icon) | 아이콘도 children으로 넣습니다. 피그마 추가 |
+| Size | Variant | 36 / 42 / 50 / 60 (Small / Medium / Large / XLarge) | 피그마 수정 |
+| Variant | Variant | 코드: `outlined` / `solid` / `outline_filled` / `outline_gray` · 피그마: filled / outlined / outlined+filled / rounded | 피그마 수정 |
+| Rounded | Boolean | True / False | 피그마 수정 |
+| Disabled | Boolean | True / False |  |
+| IsLoading | Boolean | True / False | 피그마 추가 |
+| NeedThrottle | Boolean | True / False | 연속 클릭 방지(쓰로틀링). 시각 변화 없음 · 코드에만 존재 |
+| State | Variant | Enabled / Hovered / Focused / Pressed / Loading / Disabled | 피그마만 존재 |
+
+> **Leading / Trailing Icon은 prop이 아닙니다.** `leadingIcon` 같은 prop은 코드에 없습니다. 아이콘은 라벨과 함께 **children으로** 넣습니다.
+>
+> ```tsx
+> <Button variant="solid" size="50">
+>   <SystemIcon name="large_search" />
+>   검색
+> </Button>
+> ```
+
+---
+
+## 추가 상세 규칙
+
+## Variant & Color
+
+### 1. Variant 구성 (Figma 기준)
+
+Figma의 Button은 **Variant**(형태)와 **Color**(색상) 두 축의 조합으로 구성됩니다. 존재하는 조합은 아래 6가지입니다.
+
+| Variant | Color | 형태 | Radius |
+| --- | --- | --- | --- |
+| Filled | Primary | Primary 배경 + 흰색 라벨 | 12 |
+| Outlined | Primary | 흰 배경 + 회색 테두리 + Primary 라벨 | 12 |
+| Outlined | Gray | 흰 배경 + 회색 테두리 + 회색 라벨 | 12 |
+| Outlined+Filled | Primary | 연한 Primary 배경 + Primary 테두리 + Primary 라벨 | 12 |
+| Rounded | Primary | Outlined(Primary)와 동일, 모서리만 pill | 24 |
+| Rounded | Gray | Outlined(Gray)와 동일, 모서리만 pill | 24 |
+
+`Filled / Gray`, `Outlined+Filled / Gray` 조합은 존재하지 않습니다.
+
+### 2. 강조 수준 (Emphasis)
+
+Button의 시각적 주목도는 채움 정도에 따라 달라집니다. 한 화면 안에서는 **Filled → Outlined(Primary) → Outlined(Gray)** 순으로 위계를 구성합니다.
+
+| Emphasis | Variant | 화면 내 개수 | Usage |
+| --- | --- | --- | --- |
+| **High** | Filled (Primary) | 1개 | 화면에서 가장 중요한 메인 액션(CTA). 예: `확인`, `제안 보내기` |
+| **Medium** | Outlined+Filled (Primary) / Outlined (Primary) | 여러 개 | 메인 액션을 보조하는 중요 액션, 또는 CTA가 없는 영역의 주요 액션. 예: `수정`, `미리보기` |
+| **Low** | Outlined (Gray) | 여러 개 | 중요도가 낮은 보조 액션. 예: `설정`, `취소` |
+- **Rounded** : 위계는 같은 Color의 Outlined와 동일하게 봅니다. 필터·정렬·카드 내부의 가벼운 액션처럼 **부드러운 인상**이 필요한 곳에 한정하고, 한 버튼 그룹 안에서 Rounded와 사각형 버튼을 섞지 않습니다.
+- **Outlined+Filled** : Outlined보다 한 단계 강조가 필요할 때 사용합니다. Filled와 나란히 두면 위계가 모호해지므로 함께 쓰지 않는 것을 권장합니다.
+
+### 3. 컬러 정책
+
+- 디자인 컴포넌트에서는 **Primary + Gray**만 정의합니다.
+- 추가 컬러(예: 삭제 = `w-orange-500`(caution), 닫기 = `w-bluegray-200`)는 별도 Variant를 만들지 않고 **코드 단에서 Token 기반으로 관리**합니다.
+- 버튼 색상은 시각적 구분이 아니라 **행동의 목적**에 따라 사용합니다. Primary 색상은 가장 중요한 동작에만 사용합니다.
+- 삭제·초기화처럼 되돌릴 수 없는 액션에는 위험 색상 토큰을 적용하고, 주로 확인 Dialog 안에서 사용합니다.
+
+### 4. 버튼 다중 배치
+
+- **가로 배치**: 주요 액션(Filled)을 **오른쪽**에, 보조 액션(Outlined Gray)을 왼쪽에 둡니다. 모바일에서 오른손 엄지로 누르기 쉬운 위치입니다.
+- **세로 배치**: 라벨이 길거나 두 액션의 비중 차이가 클 때 사용합니다. 주요 액션을 **위쪽**에 둡니다. 모바일 하단 CTA는 Fill 모드로 사용합니다.
+- 한 버튼 그룹 안에서는 **같은 Size, 같은 모서리 형태**(사각형 또는 Rounded)를 사용합니다.
+
+---
+
+## Content
+
+### 1. Label
+
+- 동사 중심으로 짧고 명확하게 씁니다. (`저장`, `제안 보내기`)
+- 같은 화면에서 같은 액션은 같은 단어로 씁니다. (`닫기`와 `취소`를 섞지 않음)
+
+### 2. Icon
+
+- **Leading Icon**: 라벨의 의미를 보충할 때 사용합니다. (예: `+` 추가, 다운로드)
+- **Trailing Icon**: 다음 단계로 이동·펼침 등 **동작 방향**을 알려줄 때 사용합니다. (예: `›`, `▾`)
+- Leading과 Trailing을 **동시에 사용하지 않습니다.**
+- 아이콘 색상은 라벨 색상을 따릅니다.
+
+### 3. Badge
+
+- 버튼과 관련된 **수량**을 보여줄 때만 사용합니다. (예: `선택 완료 3`)
+- Count Badge: Caption 11/Regular, Radius 10, 색상은 D-2 토큰표를 따릅니다. ✅
+- 숫자가 0이면 Badge를 숨깁니다.
+
+---
+
+## Z. 미결 (구현하지 말 것)
+
+> 아래는 **결정되지 않은 제안**입니다. 구현 기준은 위 A~C와 상세 규칙입니다. 결정되면 본문으로 옮기고 여기서 지웁니다.
+
+1. **State 체계**
+    - 현행: `State = Enabled / Hovered / Loading` + `Disabled = True/False`
+    - 제안: `State = Enabled / Hovered / Pressed / Focused / Disabled`로 정리하고, **Loading은 Boolean(`isLoading`)으로 분리**. 키보드 사용자를 위해 Focused(포커스 링) 정의 필요
+2. **Size 확장**: 42 / 50 / 60 컴포넌트 추가 여부와 스펙 확정. 사이즈별 컴포넌트 유지 vs Size Variant 통합
+3. **Rounded 분리**: Variant → Boolean 옵션 전환 여부
+4. **위험(Critical) 색상**: `w-orange-500` vs `w-red-500` 확정 및 시맨틱 토큰명 정의
+5. **접근성 대비 — 토큰 차원의 결정 필요**: 흰색 라벨 기준, primary 팔레트에 WCAG AA(일반 텍스트 4.5:1)를 만족하는 단계가 **하나도 없습니다.** `primary-500`(`#3BA3C7`)은 2.90:1로 큰 텍스트 기준(3.0:1)도 미달이고, 가장 어두운 `primary-900`(`#2E82AB`)도 4.29:1입니다. 선택지는 ① 4.5:1을 넘는 더 어두운 primary 단계 추가 ② Filled 라벨을 흰색이 아닌 어두운 색으로 ③ Filled를 큰 텍스트 전용으로 제한(이 경우도 `primary-600` 이상 필요). Button 문서가 아니라 토큰 이슈로 다룹니다
+6. **변수명 정리**: Figma `Gray/`(`#9E9E9E`) → **`Gray/400`** (코드 `w-gray-400`. `w-gray-500`은 `#757575`로 다른 색)
+7. **Icon Button**: 코드에는 이미 별도 컴포넌트 `IconButton`(INPUT-07)이 있습니다. Figma에서 Button에 포함할지 여부만 남아 있습니다
+8. **문서 보강 아이디어**: 컴포넌트 경로 추가, 실제로 구현해 보며 자주 나는 실수 목록 정리

package/dist/ai/components/Calendar.md

@@ -0,0 +1,84 @@
+---
+id: INPUT-09
+component: Calendar
+version: 0.0.2
+status: draft
+---
+
+# 9. Calendar
+
+**개정 이력**
+
+- v0.0.1 (2026.09.22): 초안 작성
+- v0.0.2 (2026.09.30): 미결 항목(Date Picker 신설)을 `Z. 미결`로 분리 (#1292 리뷰 반영)
+
+## A. Anatomy
+
+Calendar는 날짜를 표시하는 **Container(입력 필드)** 와, Focused 상태에서 아래에 열리는 **Calendar Panel**로 구성됩니다.
+
+| 요소 | 필수 여부 | 설명 |
+| --- | --- | --- |
+| Container | 필수 | 배경·테두리·패딩을 담당하는 입력 영역. 클릭/포커스 영역의 기준 |
+| Icon | 필수 | 좌측의 달력 아이콘. 날짜 입력임을 알려줍니다 |
+| Placeholder / Text | 필수 | 선택 전에는 Placeholder, 선택 후에는 날짜 텍스트 |
+| Calendar Panel | 조건부 | Focused 상태에서 필드 아래 열리는 달력 |
+| ├ Selection Row | 필수 | 연·월 표시와 이전·다음 이동 버튼 |
+| ├ Week | 필수 | 요일 헤더 (일~토) |
+| └ Item | 필수 | 날짜 셀. 선택 대상 |
+
+## B. Description
+
+### 1. 정의
+
+사용자가 날짜를 선택할 수 있도록 제공하는 일정 선택용 컴포넌트입니다.
+
+> 현재 Figma에는 **단일 날짜 선택만** 정의되어 있습니다. 기간(시작일~종료일) 선택은 컴포넌트에 없습니다.
+> 
+
+### 2. 사용 시점
+
+- 사용자가 **특정 날짜를 지정**해야 할 때 사용합니다. (마감일, 시작일, 예약일)
+- 달력의 맥락(요일, 이번 달 며칠인지)이 판단에 필요할 때 사용합니다.
+
+### 2-1. Calendar Panel 노출 규칙
+
+1. 패널은 **Focused 상태에서만** 노출합니다. Hovered에서는 노출하지 않습니다.
+2. 위치는 **필드 바로 아래 4**이며, 화면 하단 공간이 부족하면 위쪽으로 뒤집어 노출합니다.
+3. 패널은 **Overlay(띄움)** 로 동작합니다. 주변 레이아웃을 밀어내지 않습니다.
+4. 패널이 열린 동안 필드 테두리는 **Focused 색상을 유지**합니다.
+5. 날짜 선택 · 바깥 영역 클릭 · `Esc` 시 패널을 닫습니다.
+
+### 3. 키워드
+
+Calendar, 캘린더, 달력, 날짜 선택, 날짜 입력, Date Picker, 일정
+
+### 4. Do / Don't
+
+**Do**
+
+- Placeholder에는 **기대하는 날짜의 의미**를 적습니다. (`마감일을 선택하세요`)
+- 선택 가능 범위가 있다면 패널을 열기 전부터 Disabled로 보여줍니다.
+- 오늘 날짜는 사용자가 위치를 잡는 기준이 되므로 별도 표시를 검토합니다.
+- 필드를 클릭하면 **선택된 날짜가 있는 달**이 먼저 열리게 합니다.
+
+**Don't**
+
+- 날짜를 직접 타이핑해야만 입력되게 만들지 않습니다. 달력에서 고를 수 있어야 합니다.
+- 달마다 그리드 행 수를 바꿔 패널 높이가 달라지게 하지 않습니다.
+- 선택 불가한 날짜를 목록에서 감추지 않습니다.
+- 패널을 필드 너비에 맞춰 억지로 좁히지 않습니다.
+
+## C. Properties
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| Disabled | Boolean | True / False |  |
+| Variant | Variant | Placeholder/Text | 스토리북 수정 |
+| isError | Boolean | True / False | 초안 `isError` → 피그마 표기와 통일 |
+| State | Variant | Enabled/Hovered/Focused | 스토리북 수정 |
+
+## Z. 미결 (구현하지 말 것)
+
+> 아래는 **결정되지 않은 제안**입니다. 구현 기준은 위 A~C입니다.
+
+1. **Date Picker 컴포넌트 신설**: 기간(시작일~종료일) 선택 등 Calendar가 다루지 않는 입력을 별도 컴포넌트로 둘지 검토

package/dist/ai/components/Checkbox.md

@@ -0,0 +1,86 @@
+---
+id: INPUT-11
+component: Checkbox
+version: 0.0.3
+status: draft
+---
+
+# 11. Checkbox
+
+**개정 이력**
+
+- v0.0.1 (2026.09.23): 초안 작성
+- v0.0.2 (2026.10.01): 프론트매터 추가, Type 값을 스토리북 기준(`box` / `circle` / `sub`)으로 통일 (피그마 `Ghost` = `sub`), 미결 항목을 `Z. 미결`로 분리
+- v0.0.3 (2026.10.02): Properties 안내 문구 추가, `Is Error` → `IsError` 표기 통일, `onChange` · `className` 추가 (#1295 리뷰 반영)
+
+## A. Anatomy
+
+Checkbox는 **Container**와 그 안의 **체크 아이콘**으로 구성됩니다. 개별 컴포넌트로 제공되어 자유롭게 조합해 사용할 수 있으며, **Label과 함께 쓰면 CheckboxList**가 됩니다.
+
+| 요소 | 필수 여부 | 설명 |
+| --- | --- | --- |
+| Container | 필수 | 배경·테두리·모서리를 담당하는 사각 영역 |
+| System Icons | 조건부 | 선택되었을 때만 나타나는 체크 표시 |
+
+## B. Description
+
+### 1. 정의
+
+사용자가 하나 이상의 옵션을 선택할 수 있게 해주는 컴포넌트입니다. 목록에서 여러 항목을 선택하거나 약관 동의와 같은 선택적 작업에 사용됩니다.
+
+### 2. 사용 시점
+
+- 여러 항목 중 **하나 또는 여러 개**를 선택하게 할 때 사용합니다.
+- 항목 하나의 동의 여부를 받을 때 사용합니다. (약관 동의)
+- 선택값을 **저장 액션 후에 반영**할 때 사용합니다. 즉시 반영이 목적이라면 **Switch**를 사용합니다.
+- 여러 선택지 중 **하나만** 골라야 한다면 **Radio**를 사용합니다.
+- Label이 함께 필요하면 Checkbox 단독이 아니라 **CheckboxList**를 사용합니다.
+
+**Checkbox와 Switch**
+
+Checkbox와 Switch는 모두 사용자의 선택 여부를 표시하는 컴포넌트입니다.
+
+| 속성 | Checkbox | Switch |
+| --- | --- | --- |
+| 선택값 적용 | 저장하기 등의 액션을 수행해야 값이 저장됨 | 별다른 액션 없이 즉시 적용됨 |
+| 항목 구성 방식 | 하나의 카테고리에 여러 항목으로 나열할 수 있음 | 개별 항목으로 구성하는 것을 권장 |
+| 하위 항목 구성 | 부모가 모든 하위 항목을 선택·해제할 수 있음 | 부모와 하위 항목 간 관계가 없음 |
+
+### 3. 키워드
+
+Checkbox, 체크박스, 다중 선택, 복수 선택, 동의, Rectangular Checkbox
+
+### 4. Do / Don't
+
+**Do**
+
+- Checkbox는 Label과 함께 사용합니다. 단독으로 쓰는 경우는 테이블 행 선택 등 맥락이 분명할 때로 한정합니다.
+- 선택 불가한 항목은 숨기지 말고 Disabled로 남깁니다.
+- Checkbox만으로는 무엇이 잘못되었는지 알 수 없습니다. **오류 사유는 반드시 Supporting Text로 함께** 제공합니다.
+
+**Don't**
+
+- 선택 즉시 저장·이동이 일어나게 만들지 않습니다. 그 경우는 Switch입니다.
+- Checkbox 하나에 두 가지 의미를 담지 않습니다.
+- 16보다 작게 축소하지 않습니다.
+- 테두리 색상만으로 오류를 알리지 않습니다.
+
+## C. Properties
+
+스토리북(코드) 이름 기준입니다. 표의 Property는 읽기 쉽게 첫 글자를 대문자로 적었고, **코드에서는 첫 글자가 소문자**입니다 (`IsError` → `isError`). 화면에 보이는 속성뿐 아니라 **동작용(`on…`)·개발용 prop도 적습니다.** 비고에 피그마 이름을 함께 적었습니다.
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| Checked | Boolean | True / False |  |
+| Disabled | Boolean | True / False | State의 Disabled 값과 중복 (Z-1) |
+| IsError | Boolean | True / False | 피그마 `Is Error` |
+| Type | Variant | `box` / `circle` / `sub` | 기본값 `box`. 피그마 `Ghost` = `sub` → 피그마 이름을 `sub`로 통일 · 피그마에 Type 속성 추가 필요 |
+| OnChange | Function |  | 체크 상태가 바뀔 때 호출 · 동작용, 시각 변화 없음 |
+| ClassName | String |  | 개발용 스타일 지정 |
+| State | Variant | Enabled / Hovered / Disabled | 피그마에만 존재. Hovered는 마우스 hover로 자동 처리 |
+
+## Z. 미결 (구현하지 말 것)
+
+> 아래는 **결정되지 않은 제안**입니다. 구현 기준은 위 A~C입니다. 결정되면 본문으로 옮기고 여기서 지웁니다.
+
+1. **Disabled 중복**: 코드는 `disabled` Boolean으로 다룹니다. 피그마 `State`의 `Disabled` 값을 제거하고 Boolean으로 통일할지 검토

package/dist/ai/components/CheckboxCard.md

@@ -0,0 +1,114 @@
+---
+id: INPUT-12
+component: CheckboxCard
+version: 0.0.3
+status: draft
+---
+
+# 12. CheckboxCard
+
+**개정 이력**
+
+- v0.0.1 (2026.09.23): 초안 작성
+- v0.0.2 (2026.10.01): 프론트매터 추가, Properties를 코드(`CheckboxCardProps`)와 일치시킴, Type 행 제거(피그마·코드 모두 없음), RadioCard와 공통 규칙 관계 명시, 미결 항목을 `Z. 미결`로 분리
+- v0.0.3 (2026.10.02): Properties 안내 문구 추가, 누락 prop(`onChange` · `name` · `value` · `className` · `containerClassName` · `testId`) 추가, `iconName` 기본값(`receipt`) 명시 (#1295 리뷰 반영)
+
+## A. Anatomy
+
+CheckboxCard는 **Container** 안에 **Checkbox**, **Icon**, **Title**, **Supporting Text**를 담은 선택 가능한 카드입니다. 세로형(기본)과 가로형(Wide) 두 레이아웃을 지원합니다.
+
+| 요소 | 필수 여부 | 설명 |
+| --- | --- | --- |
+| Container | 필수 | 배경·테두리·모서리를 담당하는 카드 영역. 전체가 클릭 영역 |
+| Checkbox | 필수 | 선택 여부 표시. Checkbox 컴포넌트를 그대로 사용 |
+| Icon | 조건부 | Product Icons (60). 기본형은 필수, Wide형은 선택 |
+| Title | 필수 | 선택 항목의 이름 |
+| Supporting Text | 선택 | 제목을 보충하는 한 줄 설명 |
+
+## B. Description
+
+### 1. 정의
+
+체크박스와 함께 아이콘, 제목, 설명을 포함하여 사용자가 선택 항목을 명확하게 인식할 수 있도록 돕는 카드형 컴포넌트입니다.
+
+### 2. 사용 시점
+
+- 선택지마다 **설명이 필요해서** 한 줄짜리 체크박스로는 부족할 때 사용합니다.
+- 선택지를 **아이콘으로 구분**할 수 있을 때 사용합니다. (분야 선택, 플랜 선택)
+- 선택이 **중요한 분기**여서 시각적 비중을 키워야 할 때 사용합니다.
+- 설명 없이 항목만 나열한다면 **CheckboxList**를 사용합니다.
+- 하나만 골라야 한다면 **Radio Card**를 사용합니다.
+- 선택지가 8개를 넘으면 카드보다 **CheckboxList**를 사용합니다.
+
+### 2-1. 기본형 / Wide형
+
+|  | 기본형 | Wide형 |
+| --- | --- | --- |
+| 배치 | 아이콘 위, 텍스트 아래 | 아이콘 왼쪽, 텍스트 오른쪽 |
+| 나열 방향 | 가로로 여러 장 | 세로로 쌓기 |
+| 적합한 상황 | 데스크톱 등 **넓은 화면**에서 선택지를 한눈에 비교 | 화면 폭이 좁거나, 설명이 길어 한 줄로 읽히는 편이 나을 때 |
+
+> 기본형과 Wide형은 별도 컴포넌트가 아니라 **하나의 CheckboxCard**이며, `isWide`로 전환합니다.
+>
+> **RadioCard도 2-1 ~ 2-3 규칙을 그대로 따릅니다.** 두 카드는 선택 컨트롤(Checkbox / Radio)만 다르고 레이아웃·Size·배열 규칙이 같으므로, 공통 규칙의 원본은 이 문서에 둡니다.
+
+### 2-2. Size
+
+- 카드 너비는 **부모 컨테이너에 맞춰 늘립니다.** Figma의 `224` / `298`은 예시 값입니다.
+- 한 줄에 나열할 때는 **모든 카드의 너비와 높이를 동일하게** 맞춥니다. 설명 길이가 달라도 높이를 맞춥니다.
+- Wide형은 부모 너비를 100% 채우는 것을 기본으로 합니다.
+
+### 2-3. 배열 규칙
+
+1. CheckboxCard 사이 간격은 **최소 16**을 유지합니다. (가로·세로 모두)
+2. 기본형은 **데스크톱 등 넓은 화면 환경**에서 사용합니다. 좁은 화면에서는 Wide형으로 전환합니다.
+3. 한 그룹 안에서 기본형과 Wide형을 섞지 않습니다.
+
+### 3. 키워드
+
+CheckboxCard, 체크박스 카드, 카드형 선택, 다중 선택, 선택 카드, Selectable Card
+
+### 4. Do / Don't
+
+**Do**
+
+- **카드 전체를 클릭 영역**으로 만듭니다. Checkbox만 눌리게 하지 않습니다.
+- 아이콘은 선택지를 구분하는 데 도움이 될 때만 씁니다.
+- Supporting Text는 선택했을 때 **무엇이 달라지는지**를 적습니다.
+- 같은 그룹의 카드는 아이콘 유무를 통일합니다.
+
+**Don't**
+
+- 카드 사이 간격을 16보다 좁히지 않습니다.
+- 카드 안에 버튼이나 링크를 넣지 않습니다.
+- 설명 없이 제목만 있는 카드를 쓰지 않습니다. 그 경우는 CheckboxList가 맞습니다.
+- 좁은 화면에서 기본형을 억지로 줄여 쓰지 않습니다.
+
+## C. Properties
+
+스토리북(코드) 이름 기준입니다. 표의 Property는 읽기 쉽게 첫 글자를 대문자로 적었고, **코드에서는 첫 글자가 소문자**입니다 (`IsError` → `isError`). 화면에 보이는 속성뿐 아니라 **동작용(`on…`)·개발용 prop도 적습니다.** 비고에 피그마 이름을 함께 적었습니다.
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| Title | String |  | **필수.** 카드 제목 |
+| Description | String |  | 피그마 `supporting text` → **`description`으로 이름 통일** |
+| IconName | Instance | Product Icon 이름 | 기본형 필수 · Wide형 선택. **비우면 `receipt` 아이콘이 들어갑니다** · 피그마 `icon`(Boolean) → `iconName` |
+| Checked | Boolean | True / False |  |
+| Disabled | Boolean | True / False | State의 Disabled 값과 중복 (Checkbox 문서와 동일 이슈, Z-1) |
+| IsError | Boolean | True / False |  |
+| IsWide | Boolean | True / False | 피그마 추가 |
+| OnChange | Function |  | 체크 상태가 바뀔 때 호출 · 동작용, 시각 변화 없음 |
+| Name | String |  | 폼 전송용 이름 · 개발용 |
+| Value | String |  | 폼 전송용 값 · 개발용 |
+| ClassName | String |  | 개발용 스타일 지정 |
+| ContainerClassName | String |  | 카드 바깥 영역 스타일 지정 · 개발용 |
+| TestId | String |  | 테스트용 ID · 개발용 |
+| State | Variant | Enabled / Hovered / Disabled | 피그마에만 존재. Hovered는 마우스 hover로 자동 처리 |
+
+> **Type 속성은 없습니다** (피그마·코드 모두). 카드 안의 Checkbox는 항상 기본 `box`로 렌더됩니다. 하나만 고르는 카드가 필요하면 **RadioCard**를 사용합니다.
+
+## Z. 미결 (구현하지 말 것)
+
+> 아래는 **결정되지 않은 제안**입니다. 구현 기준은 위 A~C입니다. 결정되면 본문으로 옮기고 여기서 지웁니다.
+
+1. **Disabled 중복**: 코드는 `disabled` Boolean으로 다룹니다. 피그마 `State`의 `Disabled` 값을 제거하고 Boolean으로 통일할지 검토 (Checkbox Z-1과 함께 결정)