@wishket/design-system 3.7.0 → 3.8.0

package/dist/ai/components/SegmentedControl.md

@@ -0,0 +1,131 @@
+---
+id: INPUT-28
+component: SegmentedControl
+version: 0.0.2
+status: draft
+---
+
+# 28. SegmentedControl
+
+**개정 이력**
+
+- v0.0.1 (2026.10.06): 초안 작성
+- v0.0.2 (2026.10.16): 터치 영역을 코드에 맞춤 — Item 영역만 눌리고, 줄의 남는 공간은 눌리지 않음 (#1299 리뷰 반영)
+
+## A. Anatomy
+
+SegmentedControl은 **Item**을 가로로 붙여 놓은 한 줄입니다. 그중 하나만 선택되고, 선택된 Item에만 테두리가 생깁니다.
+
+| 요소 | 필수 여부 | 설명 |
+| --- | --- | --- |
+| Container | 필수 | Item을 간격 없이 가로로 붙임. 양 끝 모서리 12 |
+| Item | 필수 | 선택지 하나. 텍스트만 들어감. 너비는 텍스트에 맞춤(좌우 16) |
+
+> 피그마의 Item `Variant`(Start / Middle / End)는 **위치에 따른 모서리 모양**입니다. 코드는 첫·마지막 Item에 자동으로 모서리를 넣습니다.
+
+**크기별**
+
+| Size | 높이 | 텍스트 | 여백 |
+| --- | --- | --- | --- |
+| Small (`sm`) | 40 | Body 14 (선택 시 Medium) | 상하 8 · 좌우 16 |
+| Medium (`md`, 기본값) | 50 | Body 16 Regular | 상하 12 · 좌우 16 |
+
+**상태별 표시**
+
+| 상태 | 테두리 | 배경 | 텍스트 |
+| --- | --- | --- | --- |
+| 선택되지 않음 | 없음 | `w-gray-50` | `w-gray-300` |
+| 선택됨 | `primary-500` 1px | `primary-10` | `primary-500` |
+
+> **Hover · 키보드 포커스 상태는 추가해야 합니다.** 지금은 코드·피그마 모두 없어, 피그마에 모습을 정하고 코드 수정을 요청해야 합니다. Disabled는 미정입니다. (Z-1)
+
+## B. Description
+
+### 1. 정의
+
+동일 화면 안에서 짧은 필터·보기 전환을 빠르게 제공할 때 사용합니다. 최대 4~5개의 짧은 라벨을 쓰고, 콘텐츠는 탭 바로 아래에서 즉시 바뀌는 상황에 적합합니다.
+
+### 2. 사용 시점
+
+- 같은 내용을 **보는 방식·기간·조건을 바꿀 때** 사용합니다. (`일간` / `주간` / `월간`, `전체` / `진행 중` / `완료`)
+- 선택지가 **2~5개**로 적고, 모두 한 줄에 들어갈 때 사용합니다.
+- 폼에서 값을 고르고 나중에 저장하는 것이라면 **Radio** · **RadioList**를 사용합니다.
+- 선택지가 많거나 길다면 **TextButtonDropdown**을 사용합니다.
+- 화면의 다른 영역(다른 콘텐츠)으로 이동하는 것이라면 **TextTab** · **BoxTab**을 사용합니다.
+- 켜고 끄는 선택 하나라면 **Switch**를 사용합니다.
+
+**SegmentedControl · ChoiceChip · Radio**
+
+| 기준 | SegmentedControl | ChoiceChip | Radio |
+| --- | --- | --- | --- |
+| 선택 개수 | 하나만 | 하나 또는 여러 개 | 하나만 |
+| 반영 | 고르면 바로 | 고르면 바로(필터) 또는 저장 시 | 보통 저장 시 |
+| 모양 | 붙어 있는 한 줄 | 떨어진 칩 여러 개 | 세로 목록 |
+| 선택 해제 | 불가 (항상 하나 선택) | 가능 | 불가 |
+| 예시 | 일간 / 주간 / 월간 | 기술 스택, 관심 분야 | 결제 수단, 사업자 유형 |
+
+### 3. 키워드
+
+SegmentedControl, 세그먼트 컨트롤, 세그먼트, Segment, 토글, 보기 전환, 기간 선택, 단일 선택
+
+### 4. 터치 영역
+
+**Item 하나하나**가 눌리는 영역입니다. 텍스트만이 아니라 Item의 여백까지 눌러도 선택됩니다. Item끼리는 간격 없이 붙어 있어 Item 사이에 빈틈은 없습니다.
+
+다만 Item은 **텍스트 너비만큼만** 차지합니다. 컴포넌트 줄이 Item들보다 넓으면 **마지막 Item 오른쪽에 남는 공간은 눌리지 않습니다.** (줄을 꽉 채우는 배치는 Z-5)
+
+### 5. 가이드라인 (Do / Don't)
+
+**선택지는 2~5개**
+
+- Do: 선택지는 2~5개로 둡니다. 한 줄에 다 들어가야 비교하며 고를 수 있습니다.
+- Don't: 선택지가 많아 줄이 넘치거나 줄바꿈되게 두지 않습니다. 그럴 때는 **TextButtonDropdown**을 씁니다.
+
+**텍스트는 짧고 길이를 비슷하게**
+
+- Do: 한두 단어의 짧은 말로, Item끼리 길이를 비슷하게 씁니다. Item 너비가 텍스트에 맞춰지므로 길이가 다르면 칸 크기가 들쭉날쭉해집니다.
+
+**처음부터 하나를 선택해 두기**
+
+- Do: 항상 하나가 선택된 상태로 시작합니다. (예: `전체`, 가장 많이 보는 기간) 선택 해제는 되지 않습니다.
+
+**바로 반영되는 전환에만**
+
+- Do: 고르면 아래 내용이 곧바로 바뀌는 곳에 씁니다.
+- Don't: 저장 버튼을 눌러야 반영되는 폼 값에 쓰지 않습니다. 그 경우는 **Radio**입니다.
+
+**그 밖에**
+
+- 한 화면에 SegmentedControl을 여러 개 둘 때는 각각 `name`을 다르게 줍니다. (C. Properties · Z-2)
+- 한 화면에서 Small과 Medium을 섞지 않습니다.
+
+## C. Properties
+
+스토리북(코드) 이름 기준입니다. 표의 Property는 읽기 쉽게 첫 글자를 대문자로 적었고, **코드에서는 첫 글자가 소문자**입니다 (`SelectedValue` → `selectedValue`). 화면에 보이는 속성뿐 아니라 **동작용(`on…`)·개발용 prop도 적습니다.** 비고에 피그마 이름을 함께 적었습니다.
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| ValueList | Array | `{ key, name }` 목록 | **필수.** `name` = Item에 보이는 텍스트, `key` = 값 · 피그마는 Item을 직접 배치 |
+| SelectedValue | String |  | **필수.** 선택된 Item의 `key` · 피그마 Item `Is Selected` |
+| Size | Variant | `sm` / `md` | 기본값 `md`. 피그마 `Size` (Small / Medium) · 피그마 기본값은 Small |
+| OnChange | Function |  | **필수.** 선택이 바뀔 때 고른 `key`를 넘김 · 동작용 |
+| Name | String |  | 기본값 `segmented-control`. 안의 라디오 묶음 이름 · 개발용. 한 화면에 여러 개면 다르게 줌 (Z-2) |
+| Variant (Item) | Variant | Start / Middle / End | 피그마에만 존재. 위치에 따른 모서리 · 코드는 첫·마지막 Item에 자동 적용 |
+
+> `Disabled` · `ClassName` · `TestId`는 이 컴포넌트에 **없습니다.**
+>
+> ```tsx
+> <SegmentedControl size="sm" name="period"
+>   valueList={[{ key: 'day', name: '일간' }, { key: 'week', name: '주간' }, { key: 'month', name: '월간' }]}
+>   selectedValue={period} onChange={setPeriod} />
+> ```
+
+## Z. 미결 (구현하지 말 것)
+
+> 아래는 **결정되지 않은 제안**입니다. 구현 기준은 위 A~C입니다. 결정되면 본문으로 옮기고 여기서 지웁니다.
+
+1. **Disabled 없음**: 코드·피그마 모두 전체 또는 Item 하나를 비활성으로 만드는 상태가 없습니다 → 필요한 화면이 있는지 확인하고 추가할지 결정
+2. **`name` 기본값이 고정됨 (코드 확인 필요)**: `name`을 안 넣으면 모두 `segmented-control`이 됩니다. 한 화면에 두 개 이상 두면 안의 라디오가 한 묶음으로 잡혀 키보드 이동·폼 전송이 꼬일 수 있습니다 → 컴포넌트마다 자동으로 다른 이름을 주도록 개발팀에 요청
+3. **무엇을 고르는지 스크린리더에 알릴 수 없음 (코드 확인 필요)**: 묶음의 설명이 `segmented control`로 고정돼 있어 "기간 선택"처럼 용도를 알려줄 수 없습니다 → 바꿀 수 있게 할지 개발팀에 요청
+4. **기본 크기 차이**: 코드 기본값은 `md`, 피그마 기본값은 Small입니다 → 피그마 기본값을 Medium으로 맞출지 검토
+5. **너비를 꽉 채우는 배치**: 지금은 Item이 텍스트 너비에 맞춰지고, 남는 공간은 비어 있고 눌리지도 않습니다. 모바일처럼 줄 전체를 Item이 같은 너비로 나눠 채우는 배치가 필요한지 결정

package/dist/ai/components/Switch.md

@@ -0,0 +1,114 @@
+---
+id: INPUT-29
+component: Switch
+version: 0.0.2
+status: draft
+---
+
+# 29. Switch
+
+**개정 이력**
+
+- v0.0.1 (2026.10.06): 초안 작성
+- v0.0.2 (2026.10.16): `className`이 적용되는 자리를 코드에 맞춤 — 바깥 영역이 아니라 트랙 (#1299 리뷰 반영)
+
+## A. Anatomy
+
+Switch는 가로로 긴 **Container**(트랙) 위를 **Handle**(동그라미)이 좌우로 움직이는 구조입니다. 켜지면 Handle이 오른쪽, 꺼지면 왼쪽에 있습니다. **Label은 컴포넌트에 포함돼 있지 않습니다.**
+
+| 요소 | 필수 여부 | 설명 |
+| --- | --- | --- |
+| Container | 필수 | 32×16 트랙. 모서리 완전히 둥글게. 켜짐/꺼짐을 색으로 표시 |
+| Handle | 필수 | 20×20 흰 원, 테두리 1px. 트랙보다 살짝 커서 양쪽으로 2~4px 밖에 나옴. 전환 시 미끄러지듯 이동 |
+
+> 보이는 전체 크기는 **36×20**입니다 (피그마와 같음). 크기는 하나뿐입니다.
+
+**상태별 표시**
+
+| 상태 | Container | Handle |
+| --- | --- | --- |
+| 꺼짐 | `w-gray-300` | 흰색 · 왼쪽 |
+| 켜짐 | `primary-500` | 흰색 · 오른쪽 |
+| Disabled + 꺼짐 | `w-gray-100` | 흰색 · 왼쪽 |
+| Disabled + 켜짐 | `primary-100` | 흰색 · 오른쪽 |
+
+> Hover · 키보드 포커스 상태는 코드·피그마 모두 없습니다.
+
+## B. Description
+
+### 1. 정의
+
+사용자가 두 가지 상태를 빠르게 전환할 수 있도록 제공되는 토글형 컴포넌트입니다. 켜거나 끄면 **저장 없이 바로 적용**됩니다.
+
+### 2. 사용 시점
+
+- 설정을 **켜고 끄면 즉시 반영**될 때 사용합니다. (알림 받기, 프로필 공개, 자동 연장)
+- 저장하기를 눌러야 반영되는 폼 항목이라면 **Checkbox**를 사용합니다.
+
+**Switch와 Checkbox**
+
+| 속성 | Switch | Checkbox |
+| --- | --- | --- |
+| 값 적용 | 별도 액션 없이 즉시 | 저장하기 등 액션을 해야 저장 |
+| 항목 구성 | 개별 항목으로 구성 | 한 카테고리에 여러 항목 나열 가능 |
+| 하위 항목 | 부모·하위 관계 없음 | 부모가 하위 항목을 모두 선택·해제 |
+
+> Checkbox 문서의 비교표와 같은 내용입니다.
+
+### 3. 키워드
+
+Switch, 스위치, 토글, Toggle, On/Off, 켜기/끄기, 설정
+
+### 4. 가이드라인 (Do / Don't)
+
+**즉시 반영되는 곳에만**
+
+- Do: 켜고 끄는 순간 바로 적용되는 설정에 씁니다.
+- Don't: 저장·확인을 눌러야 반영되는 곳에 쓰지 않습니다. 그 경우는 **Checkbox**입니다.
+
+**항목마다 독립적으로**
+
+- Do: 하나의 Switch는 하나의 설정만 켭니다.
+- Don't: "전체 켜기"처럼 다른 Switch들을 한꺼번에 제어하는 부모·하위 구조에 쓰지 않습니다. 그 경우는 **Checkbox**입니다.
+
+**Label과 함께, 무엇을 켜는지 알 수 있게**
+
+- Do: Switch 옆에 무엇을 켜는지 Label을 두고, Label을 눌러도 켜지게 연결합니다.
+- Do: Label은 항목 이름으로 짧게 씁니다. (`마케팅 정보 수신 동의`, `댓글 알림`) 필요하면 아래에 설명을 한 줄 더합니다.
+
+**Disabled는 Label까지**
+
+- Do: Switch를 Disabled로 두면 옆의 Label도 비활성 색(`w-gray-300`)으로 바꿉니다.
+- Don't: Switch만 흐리게 하고 Label은 그대로 두지 않습니다. 항목 전체가 못 쓰는 상태인지 알 수 없습니다.
+
+**그 밖에**
+
+- 설정 목록에서는 Label을 왼쪽, Switch를 오른쪽 끝에 정렬합니다.
+- 바로 적용되므로, 결과가 크거나 되돌리기 어려운 설정은 켜기 전에 확인 **Dialog**를 띄웁니다.
+
+## C. Properties
+
+스토리북(코드) 이름 기준입니다. 표의 Property는 읽기 쉽게 첫 글자를 대문자로 적었고, **코드에서는 첫 글자가 소문자**입니다 (`OnChange` → `onChange`). 화면에 보이는 속성뿐 아니라 **동작용(`on…`)·개발용 prop도 적습니다.** 비고에 피그마 이름을 함께 적었습니다.
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| Checked | Boolean | True / False | 켜짐 여부 · 피그마 `Checked` |
+| Disabled | Boolean | True / False | 피그마 `Disabled` |
+| OnChange | Function |  | 켜거나 끌 때 호출 · 동작용 |
+| Id | String |  | Label과 연결할 때 사용 (`<label htmlFor>`) · 개발용 |
+| Name | String |  | 폼 전송용 이름 · 개발용 |
+| ClassName | String |  | 개발용 스타일 지정. **스위치 트랙에 적용**됩니다 — 바깥 영역이 아니라서 여백(`mt-4` 등)을 주면 트랙만 움직입니다. 위치는 감싼 요소에서 잡습니다 |
+| State | Variant | Enabled | 피그마에만 존재. 값이 하나뿐이라 의미 없음 |
+
+> 이 외에도 일반 `<input type="checkbox">`의 속성(`aria-*` 등)을 그대로 받습니다. `Label` · `Size`는 없습니다.
+>
+> ```tsx
+> <label htmlFor="noti">알림 받기</label>
+> <Switch id="noti" checked={on} onChange={() => setOn(!on)} />
+> ```
+
+## Z. 미결 (구현하지 말 것)
+
+> 아래는 **결정되지 않은 제안**입니다. 구현 기준은 위 A~C입니다. 결정되면 본문으로 옮기고 여기서 지웁니다.
+
+1. **Handle 테두리 색 토큰 (코드 확인 필요)**: 코드가 디자인 시스템 토큰 `w-gray-200`이 아니라 Tailwind 기본 `gray-200`을 씁니다. 두 색이 다를 수 있습니다 → `w-gray-200`으로 바꾸도록 개발팀에 요청

package/dist/ai/components/TextButton.md

@@ -1,8 +1,9 @@
 ---
 id: INPUT-08
 component: TextButton
-version: 0.0.1
+version: 0.0.2
 status: draft
+figma.componentKey: 3eee8fa20aa4f3bb067ce717749cf42223042f16
 ---
 
 # 8. TextButton
@@ -10,19 +11,21 @@ status: draft
 **개정 이력**
 
 - v0.0.1 (2026.09.22): 초안 작성
+- v0.0.2 (2026.10.16): Property 이름을 소문자로 통일 (피그마 전용 속성 포함)
 
 ## A. Anatomy
 
 TextButton은 **Text**로 구성되며, 선택적으로 **Leading Icon**과 **Trailing Icon**을 가집니다. 배경과 테두리가 없습니다.
 
-| 요소 | 필수 여부 | 설명 |
-| --- | --- | --- |
-| Text | 필수 | 액션을 설명하는 텍스트. 이 컴포넌트의 클릭 영역 기준 |
-| Leading Icon | 선택 | 텍스트 앞 아이콘. 액션의 **의미를 보조** |
-| Trailing Icon | 선택 | 텍스트 뒤 아이콘. Chevron 등 **방향·이동을 보조** |
+
+| 요소            | 필수 여부 | 설명                                 |
+| ------------- | ----- | ---------------------------------- |
+| Text          | 필수    | 액션을 설명하는 텍스트. 이 컴포넌트의 클릭 영역 기준     |
+| Leading Icon  | 선택    | 텍스트 앞 아이콘. 액션의 **의미를 보조**          |
+| Trailing Icon | 선택    | 텍스트 뒤 아이콘. Chevron 등 **방향·이동을 보조** |
+
 
 > Container가 없어 **텍스트 크기가 곧 클릭 영역**입니다. 별도의 패딩을 갖지 않습니다.
-> 
 
 ## B. Description
 
@@ -42,7 +45,6 @@ TextButton은 **Text**로 구성되며, 선택적으로 **Leading Icon**과 **Tr
 - Hovered에서 색상은 바뀌지 않습니다. 밑줄만 추가됩니다.
 
 > TextButton은 Button보다 **낮은 시각 위계**를 가집니다. 한 화면에서 Button과 TextButton이 함께 있으면 Button이 주요 액션입니다.
-> 
 
 ### 3. 키워드
 
@@ -50,19 +52,25 @@ TextButton, 텍스트버튼, 버튼, Btn, txt, 텍스트 링크, Primary Text Bu
 
 ### 4. Size
 
-| Size | Font | Icon | Icon–Text Gap | 높이 |
-| --- | --- | --- | --- | --- |
-| **Small** | Body 14 / Medium (14 · line-height 24) | 14 | 2 | 24 |
-| **Medium** | Body 16 / Medium (16 · line-height 26) | 16 | 4 | 26 |
+
+| Size       | Font                                   | Icon | Icon–Text Gap | 높이  |
+| ---------- | -------------------------------------- | ---- | ------------- | --- |
+| **Small**  | Body 14 / Medium (14 · line-height 24) | 14   | 2             | 24  |
+| **Medium** | Body 16 / Medium (16 · line-height 26) | 16   | 4             | 26  |
+
+
 - 두 Size 모두 텍스트 굵기는 **Medium**입니다. 본문과 구분되도록 하는 장치입니다.
 - 주변 본문의 폰트 크기에 맞춰 Size를 고릅니다. 본문이 16이면 Medium, 14면 Small을 씁니다.
 
 ### 4-1. Color
 
-| Color | 사용 상황 |
-| --- | --- |
+
+| Color       | 사용 상황          |
+| ----------- | -------------- |
 | **Primary** | 주요 행동을 유도하는 경우 |
-| **Gray** | 보조 행동 |
+| **Gray**    | 보조 행동          |
+
+
 - 한 묶음 안에서 **주요 행동 하나만 Primary**로 두고 나머지는 Gray로 둡니다. (`수정` Primary · `삭제` Gray)
 - 삭제·취소 같은 부정적 액션을 Primary로 강조하지 않습니다.
 
@@ -99,13 +107,17 @@ TextButton, 텍스트버튼, 버튼, Btn, txt, 텍스트 링크, Primary Text Bu
 
 ## C. Properties
 
+Property 이름은 **소문자로 시작**하게 적었습니다. 피그마에만 있는 속성도 같은 방식으로 적고, 비고에 `피그마에만 존재`라고 표시했습니다.
+
 | Property | Type | Values | 비고 |
 | --- | --- | --- | --- |
-| Text | String |  | 피그마 추가 |
-| Size | Variant | Small / Medium | 스토리북 `IsTextSmall` → **`Size`** 로 네이밍 통일 |
-| IsGray | Boolean | True / False | 피그마 수정 |
-| State | Variant | Enabled / Hovered | **Pressed·Focused 추가 필요** |
-| isUnderline | Boolean | True / False | 피그마 수정 or 스토리북 수정>State추가(Hovered상태) |
-| Disabled | Boolean | True / False |  |
-| LeadingIcon | Instance |  | 아이콘 교체가 필요하면 **Instance로 변경** (피그마 수정) |
-| TrailingIcon | Instance |  | 아이콘 교체가 필요하면 **Instance로 변경** (피그마 수정) |
+| text | String |  | 피그마 추가 |
+| size | Variant | Small / Medium | 스토리북 `isTextSmall` → `size` 로 네이밍 통일 |
+| isGray | Boolean | True / False | 피그마 수정 |
+| state | Variant | Enabled / Hovered | 피그마에만 존재 |
+| isUnderline | Boolean | True / False | 스토리북 수정 → `state`로 추가 (Hovered 상태) |
+| disabled | Boolean | True / False |  |
+| leadingIcon | Instance |  | 아이콘 교체가 필요하면 **Instance로 변경** (피그마 수정) |
+| trailingIcon | Instance |  | 아이콘 교체가 필요하면 **Instance로 변경** (피그마 수정) |
+
+

package/dist/ai/components/TextButtonDropdown.md

@@ -0,0 +1,101 @@
+---
+id: INPUT-23
+component: TextButtonDropdown
+version: 0.0.2
+status: draft
+---
+
+# 23. TextButtonDropdown
+
+**개정 이력**
+
+- v0.0.1 (2026.10.02): 초안 작성
+- v0.0.2 (2026.10.16): 목록에서 선택된 항목 표시를 코드에 맞춤 — 색만 바뀌고 굵기는 그대로 (#1299 리뷰 반영)
+
+## A. Anatomy
+
+TextButtonDropdown은 **현재 선택값을 보여주는** **Text Button**과, 버튼을 누르면 그 아래 8px 간격으로 열리는 **List**로 구성됩니다.
+
+| 요소 | 필수 여부 | 설명 |
+| --- | --- | --- |
+| Text Button | 필수 | 목록을 여는 버튼. 텍스트 + 우측 화살표, 사이 간격 8px (피그마 4px → 8px로 수정 필요) |
+| Text | 필수 | **선택된 항목의 텍스트**가 그대로 표시됨. Body 16 Regular (피그마 Medium → Regular로 수정 필요) / `w-gray-600` |
+| Arrow Icon | 필수 | `medium_arrow_down`(16). 목록이 열리면 위로 돌아감 |
+| List | 조건부 | 버튼을 눌렀을 때만 표시. 최소 너비 160, 버튼 사이 간격 8px |
+| List Item | 필수 | 목록의 선택지. 텍스트 + 선택적 Leading Icon(Medium 16) |
+
+**상태별 표시**
+
+| 상태 | 텍스트 · 아이콘 |
+| --- | --- |
+| 기본 | `w-gray-600` |
+| 목록 열림 | `w-gray-600`, 화살표가 위로 |
+| Disabled | `w-gray-300` |
+
+목록 항목의 선택·Hover 표시는 **List** 컴포넌트와 같습니다. (선택됨 = 텍스트 `primary-500`, 굵기는 그대로 Regular · Hover·키보드 포커스 = 배경 `primary-10`)
+
+## B. Description
+
+### 1. 정의
+
+버튼 클릭 시 리스트 형태의 옵션을 표시해 사용자가 원하는 항목을 선택할 수 있도록 돕는 컴포넌트입니다. 버튼에 **현재 선택값이 텍스트로 보여서**, 무엇이 적용돼 있는지 바로 알 수 있습니다.
+
+### 2. 사용 시점
+
+- 목록 상단에서 **정렬 기준·보기 방식**을 바꿀 때 사용합니다. (`기본 정렬 순`, `금액 높은 순`)
+- 항목을 고르면 **즉시 반영**되고 목록이 닫힙니다.
+- 공간이 좁아 텍스트를 둘 수 없다면 **IconButtonDropdown**을 사용합니다.
+- 폼에서 값을 고르게 한다면 **TextFieldDropdown**을 사용합니다.
+
+**유형**
+
+| 유형 | 설명 |
+| --- | --- |
+| **Left** | 목록의 왼쪽 끝을 버튼 왼쪽에 맞춥니다. 기본값. |
+| **Right** | 목록의 오른쪽 끝을 버튼 오른쪽에 맞춥니다. 화면·카드 오른쪽 끝에 놓인 버튼에 써서 목록이 밖으로 잘리지 않게 합니다. |
+| **Disabled** | 버튼을 눌러도 목록이 열리지 않고, 텍스트·아이콘이 `w-gray-300`으로 표시됩니다. 키보드(`Tab` · `Enter`)로도 열리지 않습니다. |
+
+### 3. 키워드
+
+TextButtonDropdown, 텍스트 버튼 드롭다운, 드롭다운, Dropdown, 정렬, Sort
+
+### 4. Do / Don't
+
+**Do**
+
+- 항목 텍스트는 짧은 한 줄로 씁니다. 고른 텍스트가 그대로 버튼에 표시됩니다.
+- 처음부터 기본값 하나를 선택해 둡니다. (`기본 정렬 순`)
+- 버튼이 화면·카드의 오른쪽 끝에 있으면 `alignRight`를 씁니다.
+
+**Don't**
+
+- 항목을 너무 많이 넣지 않습니다. 목록에 높이 제한과 스크롤이 없어 항목 수만큼 길어집니다. (Z-2)
+- 폼 값을 받는 데 쓰지 않습니다. 그 경우는 **TextFieldDropdown**입니다.
+- 더보기·삭제 같은 동작 메뉴에 쓰지 않습니다. 버튼 텍스트가 고른 동작 이름으로 바뀝니다.
+
+## C. Properties
+
+스토리북(코드) 이름 기준입니다. 표의 Property는 읽기 쉽게 첫 글자를 대문자로 적었고, **코드에서는 첫 글자가 소문자**입니다 (`AlignRight` → `alignRight`). 화면에 보이는 속성뿐 아니라 **동작용(`on…`)·개발용 prop도 적습니다.** 비고에 피그마 이름을 함께 적었습니다.
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| Items | Array | `{ key, value, leadingIcon? }` 목록 | **필수.** `value` = 항목 텍스트, `leadingIcon` = System Icon 이름 (Medium) |
+| SelectedItem | Object | Items 중 하나 | **필수.** 이 항목의 텍스트가 버튼에 표시되고 목록에서 강조됨 · 피그마는 버튼 텍스트를 직접 입력(`텍스트 버튼`) |
+| AlignRight | Boolean | True / False | 기본값 False(왼쪽 정렬). 피그마 `Variant` (Left / Right) · IconButtonDropdown은 `align = left / right` → 이름 다름 (Z-1) |
+| Disabled | Boolean | True / False | 피그마 `Disabled` · 키보드로도 열리면 안 됨. **현재 코드는 Tab 포커스 후 `Enter`로 열림 → 수정 요청 필요** |
+| OnItemClick | Function |  | **필수.** 항목을 고를 때 호출 · 동작용 |
+| State | Variant | Enabled / Focused | 피그마에만 존재. Focused = 목록이 열린 모습 · 코드는 클릭으로 자동 처리 |
+
+> `ClassName` · `TestId`는 이 컴포넌트에 **없습니다.**
+>
+> ```tsx
+> <TextButtonDropdown items={items} selectedItem={selected}
+>   onItemClick={setSelected} alignRight />
+> ```
+
+## Z. 미결 (구현하지 말 것)
+
+> 아래는 **결정되지 않은 제안**입니다. 구현 기준은 위 A~C입니다. 결정되면 본문으로 옮기고 여기서 지웁니다.
+
+1. **정렬 prop 이름**: 이 컴포넌트는 `alignRight`(Boolean), IconButtonDropdown은 `align = left / right`, 피그마는 둘 다 `Variant = Left / Right`입니다 → 하나로 통일할지 검토 (코드 prop을 바꾸면 breaking change)
+2. **목록 최대 높이 지정 필요**: List 기본값(최대 240, 스크롤)을 이 컴포넌트가 끄고 있어 항목 수만큼 길어집니다. 최대 높이는 지정하기로 했고, 값(List 기본 240을 따를지 등)은 미정 (IconButtonDropdown과 같은 문제)

package/dist/ai/components/TextField.md

@@ -3,6 +3,7 @@ id: INPUT-18
 component: TextField
 version: 0.0.3
 status: draft
+figma.componentKey: b7abe3753ce5d9aa134c43fe28cd3c769b6f92b4
 ---
 
 # 18. TextField

package/dist/ai/components/TextFieldDropdown.md

@@ -0,0 +1,123 @@
+---
+id: INPUT-22
+component: TextFieldDropdown
+version: 0.0.2
+status: draft
+---
+
+# 22. TextFieldDropdown
+
+**개정 이력**
+
+- v0.0.1 (2026.10.02): 초안 작성
+- v0.0.2 (2026.10.16): `variant = label`의 트리거 높이(66)·목록 간격(6px) 추가, 선택된 항목 표시를 코드에 맞춤 — 색만 바뀌고 굵기는 그대로 (#1299 리뷰 반영)
+
+## A. Anatomy
+
+TextFieldDropdown은 TextField와 같은 모양의 **Text Field**(트리거)와, 트리거를 누르면 그 아래로 열리는 **List**로 구성됩니다. 트리거 아래에는 TextField와 같은 **Error Text · Supporting Text** 줄이 붙습니다.
+
+| 요소 | 필수 여부 | 설명 |
+| --- | --- | --- |
+| Container | 필수 | 모서리 12, 테두리 `w-gray-200`. 누르면 목록이 열리는 영역. 높이는 아래 표 |
+| Label | 조건부 | `variant = label`일 때 필드 **안쪽 상단**에 얹히는 항목명 |
+| Placeholder / Text | 필수 | 고르기 전에는 Placeholder, 고른 뒤에는 선택한 항목 텍스트 |
+| Arrow Icon | 필수 | 우측 `medium_arrow_down`(16). 목록이 열리면 위로 돌아감 |
+| List | 조건부 | 트리거를 눌렀을 때만 표시. 너비는 트리거와 같고(최소 220), **최대 높이 240** 넘으면 스크롤 |
+| List Item | 필수 | 목록의 선택지. 텍스트 + 선택적 Leading Icon(Medium 16) |
+| Error Text | 조건부 | 오류 문구. 필드 하단, **Supporting Text 위에 별도 줄**로 표시 |
+| Supporting Text | 선택 | 필드 하단 좌측의 도움말 |
+
+**Variant별 크기**
+
+| Variant | 트리거 높이 | 트리거와 목록 사이 |
+| --- | --- | --- |
+| `default` (기본값) | 50 | 4px |
+| `label` | 66 | 6px |
+
+**상태별 표시**
+
+| 상태 | 테두리 | 배경 | 텍스트 |
+| --- | --- | --- | --- |
+| 기본 | `w-gray-200` | `w-white` | Placeholder `w-gray-300` / 선택값 `w-gray-600` |
+| Hover · 목록 열림 | `primary-500` | `w-white` | 기본과 같음 |
+| Error | `w-red-500` (Hover·열림에도 유지) | `w-white` | 기본과 같음 |
+| Disabled | `w-gray-200` | `w-gray-10` | Placeholder `w-gray-200` / 선택값 `w-gray-300`, 아이콘 `w-gray-300` |
+
+목록 항목의 선택·Hover 표시는 **List** 컴포넌트와 같습니다. (선택됨 = 텍스트 `primary-500`, 굵기는 그대로 Regular · Hover·키보드 포커스 = 배경 `primary-10`)
+
+## B. Description
+
+### 1. 정의
+
+사용자가 리스트에서 직접 항목을 선택할 수 있도록 설계된 컴포넌트입니다. 생김새는 TextField와 같고, 타이핑 대신 목록에서 하나를 골라 값을 채웁니다.
+
+### 2. 사용 시점
+
+- 폼에서 **정해진 선택지 중 하나**를 값으로 받을 때 사용합니다. (업종, 직무, 지역)
+- 선택지가 많아 화면에 다 펼칠 수 없을 때 사용합니다.
+- 선택지가 2~5개로 적다면 펼쳐 두는 **Radio**나 **ChoiceChip**을 사용합니다.
+- 여러 개를 골라야 한다면 **Checkbox** 계열을 사용합니다. 이 컴포넌트는 하나만 고릅니다.
+- 입력하면서 목록을 걸러 고르게 한다면 **Autocomplete**를 사용합니다.
+- 폼이 아니라 목록 상단의 정렬·보기 전환이라면 **TextButtonDropdown**이나 **IconButtonDropdown**을 사용합니다.
+- 누르면 목록이 아니라 **모달·패널**이 열려야 한다면 **TextFieldTrigger**를 사용합니다.
+
+**유형**
+
+유형(Default · Fixed Label · Label)은 **TextField와 같습니다.** 같은 폼에서 TextField와 나란히 쓸 때 `variant`를 맞춥니다.
+
+### 3. 키워드
+
+TextFieldDropdown, 드롭다운, Dropdown, 셀렉트, Select, 셀렉트 박스, Select Box, 단일 선택
+
+### 4. Do / Don't
+
+**Do**
+
+- Placeholder에는 **무엇을 고르는 칸인지**를 적습니다. (`업종을 선택해주세요`)
+- 항목 텍스트는 짧은 한 줄로 씁니다. 선택하면 그 텍스트가 그대로 필드에 들어갑니다.
+- **Error Text와 Supporting Text가 동시에 있으면 둘 다 표시합니다.** Error Text를 위에, Supporting Text를 아래에 둡니다. (TextField와 같음)
+
+**Don't**
+
+- 항목을 고르자마자 화면 이동·저장이 일어나게 만들지 않습니다. 폼 값을 채우는 컴포넌트입니다.
+- Placeholder를 항목명 대신 쓰지 않습니다. 항목을 고르면 사라집니다.
+- 테두리 색상만으로 오류를 알리지 않습니다. Error Text를 함께 씁니다.
+
+## C. Properties
+
+스토리북(코드) 이름 기준입니다. 표의 Property는 읽기 쉽게 첫 글자를 대문자로 적었고, **코드에서는 첫 글자가 소문자**입니다 (`IsError` → `isError`). 화면에 보이는 속성뿐 아니라 **동작용(`on…`)·개발용 prop도 적습니다.** 비고에 피그마 쪽 상태를 함께 적었습니다.
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| Items | Array | `{ key, value, leadingIcon? }` 목록 | **필수.** `value` = 항목 텍스트, `leadingIcon` = System Icon 이름 (Medium) |
+| SelectedItem | Object | Items 중 하나 | 선택된 항목. 값이 있으면 필드에 텍스트로 표시되고 목록에서 강조됨 · 피그마 `Variant = Text`가 이 상태 |
+| Variant | Variant | `default` / `label` | 기본값 `default`. TextField와 같은 의미. 트리거 높이가 달라짐(A. Variant별 크기) · 피그마에 `label` 없음 (Z-2) |
+| Label | String |  | `variant = label`일 때 사용 |
+| Placeholder | String |  | 고르기 전 안내 문구 |
+| Disabled | Boolean | True / False | 피그마 `Disabled` |
+| IsError | Boolean | True / False | 오류 테두리. 피그마 `Is Error` |
+| ErrorMessage | String |  | 오류 문구. 필드 하단 Supporting Text **위**에 표시 · 피그마는 Error Text가 `Is Error`에 묶여 있음 |
+| SupportMessage | String |  | 도움말 문구 · 피그마에 없음 (Z-3) |
+| PanelWidth | Variant | `trigger` / `viewport` | 기본값 `trigger`. 화면 크기별 값도 가능 `{ base, tablet, desktop }` · 피그마에 없음 |
+| PanelGutter | Number |  | 기본값 `20`. `viewport`일 때 목록과 화면 좌우 끝 사이 여백(px) |
+| OnItemClick | Function |  | **필수.** 항목을 고를 때 호출 · 동작용 |
+| ClassName | String |  | 개발용 스타일 지정 (트리거에 적용) |
+| State | Variant | Enabled / Hovered / Focused | 피그마에만 존재. Focused = 목록이 열린 모습 · 코드는 마우스·클릭으로 자동 처리 (Z-1) |
+
+> 피그마의 `Variant`(Placeholder / Text)는 **코드에 따로 넣는 값이 없고** `selectedItem` 유무로 자동으로 정해집니다. 코드의 `variant`(default / label)와는 다른 것입니다.
+>
+> ```tsx
+> <TextFieldDropdown variant="label" label="업종" items={items}
+>   selectedItem={selected} onItemClick={setSelected}
+>   isError={!!error} errorMessage={error} />
+> ```
+
+## Z. 미결 (구현하지 말 것)
+
+> 아래는 **결정되지 않은 제안**입니다. 구현 기준은 위 A~C입니다. 결정되면 본문으로 옮기고 여기서 지웁니다.
+
+1. **State · Variant 이름 정리**: 피그마 `State = Focused`는 목록이 열린 모습이고, 피그마 `Variant`(Placeholder / Text)는 선택 여부입니다. 둘 다 코드에는 넣는 값이 없고, 특히 `Variant`는 코드의 `variant`(default / label)와 이름이 겹칩니다 → 피그마 속성 이름을 바꿀지 검토 (예: `Open`, `Selected`)
+2. **Label 트리거 누락**: 코드는 `variant = label`(TextField의 Label / Fixed Label과 같은 모양)을 지원하지만 피그마에는 Default만 있습니다 → 피그마 추가 검토. 추가할 때 트리거 높이 66 · 목록 간격 6px로 그립니다 (A. Variant별 크기)
+3. **Supporting Text 누락**: 코드는 `supportMessage`를 받지만 피그마에는 Error Text만 있습니다 → 피그마 추가 검토
+4. **선택한 항목의 아이콘**: 항목에 Leading Icon이 있어도 고른 뒤 필드에는 텍스트만 표시됩니다. 코드는 아이콘을 넘기지만 트리거가 그리지 않고, 피그마도 텍스트만 있습니다 → 필드에도 아이콘을 보여줄지 결정
+5. **선택 취소**: 한 번 고르면 빈 값으로 되돌릴 방법이 없습니다. 필수가 아닌 항목이라면 `선택 안 함` 같은 항목을 넣을지, 컴포넌트에 비우기를 넣을지 결정