@wishket/design-system 3.6.0 → 3.8.0

package/dist/ai/components/SearchField.md

@@ -0,0 +1,117 @@
+---
+id: INPUT-17
+component: SearchField
+version: 0.0.3
+status: draft
+figma.componentKey: 891b93a624445312daea6efc719271f1073972f7
+---
+
+# 17. SearchField
+
+**개정 이력**
+
+- v0.0.1 (2026.09.28): 초안 작성
+- v0.0.2 (2026.10.01): 프론트매터 추가, Properties를 코드(`SearchFieldProps`)·스토리북 기준으로 정리, 피그마 ↔ 코드 상태 대응표·Size 추가, 미결 항목을 `Z. 미결`로 분리
+- v0.0.3 (2026.10.02): Properties 안내 문구 통일, `value` · `onChange` · `className` 추가, `Filters` 안의 `alignRight` 명시, 형식 정리 (#1295 리뷰 반영)
+
+## A. Anatomy
+
+SearchField는 **Container** 안에 검색어를 입력하는 **Text**와 우측의 **Search Icon**으로 구성되며, 좌측에 검색 범위를 고르는 **Text Button Dropdown**을 둘 수 있습니다.
+
+| 요소 | 필수 여부 | 설명 |
+| --- | --- | --- |
+| Container | 필수 | 배경·테두리·패딩을 담당하는 영역. 클릭/포커스 영역의 기준 |
+| Text Button Dropdown | 선택 | 좌측에서 **검색 범위·조건**을 고르는 드롭다운 |
+| Placeholder / Text | 필수 | 입력 전에는 Placeholder, 입력 중에는 검색어 |
+| Search Icon | 필수 | 우측의 돋보기 아이콘. 검색 실행. **Enter 키로도 실행**됩니다 |
+
+## B. Description
+
+### 1. 정의
+
+사용자가 원하는 특정 항목을 찾아야 할 때 사용합니다.
+
+### 2. 사용 시점
+
+- 목록이나 페이지에서 **검색어로 결과를 좁힐 때** 사용합니다.
+- 검색 대상을 **범위별로 나눠야** 할 때 `Text Button Dropdown`을 함께 사용합니다. (`전체`, `프로젝트명`, `작성자`)
+- 입력하는 동안 **제안 목록을 띄워 고르게** 하는 것이 목적이라면 **Autocomplete**를 사용합니다.
+- 검색이 아니라 값을 입력받는 것이라면 **Input(Text Field)** 을 사용합니다.
+
+### 3. 키워드
+
+SearchField, 검색, 검색창, 검색 필드, Search, 검색어 입력, 돋보기
+
+### 4. Size
+
+- SearchField는 **부모 컨테이너 너비를 100% 채웁니다.** Figma의 `240`은 예시 값입니다.
+- 높이는 **50**입니다.
+- 검색어·Placeholder는 **1줄로 고정**합니다. 넘치면 줄바꿈하지 않고 가려집니다.
+
+### 5. Do / Don't
+
+**Do**
+
+- Placeholder에는 **무엇으로 검색할 수 있는지** 적습니다. (`프로젝트명으로 검색`)
+- Dropdown 라벨은 현재 선택된 범위를 그대로 보여줍니다.
+- 검색 결과가 없을 때의 안내를 함께 설계합니다.
+
+**Don't**
+
+- 검색어를 2줄로 표시하지 않습니다.
+- Search Icon 자리에 다른 액션(초기화 등)을 겹쳐 넣지 않습니다.
+- Dropdown 라벨을 문장으로 쓰지 않습니다.
+- 입력할 때마다 결과 페이지로 이동시키지 않습니다.
+
+## C. Properties
+
+스토리북(코드) 이름 기준입니다. 표의 Property는 읽기 쉽게 첫 글자를 대문자로 적었고, **코드에서는 첫 글자가 소문자**입니다 (`OnSearch` → `onSearch`). 화면에 보이는 속성뿐 아니라 **동작용(`on…`)·개발용 prop도 적습니다.** 비고에 피그마 이름을 함께 적었습니다.
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| OnSearch | Function |  | **필수.** 검색 실행 동작(Search Icon 클릭 또는 Enter 시 호출) · 동작용, 시각 변화 없음 |
+| Placeholder | String |  | 입력 전 안내 문구. 피그마 `Variant = Placeholder`에 해당 |
+| Value | String |  | 입력한 검색어 |
+| OnChange | Function |  | 검색어가 바뀔 때 호출 · 동작용 |
+| Disabled | Boolean | True / False | 입력·드롭다운·검색 모두 비활성. 피그마 `State = Disabled`에 해당 |
+| Filters | Object | 아래 표 | **값을 넣으면 Text Button Dropdown이 나타납니다.** 켜고 끄는 Boolean이 아닙니다 · 피그마 `TextButtonDropdown`에 해당 (이름 변경 제안은 Z-4) |
+| ClassName | String |  | 개발용 스타일 지정 |
+
+**`Filters` 안에 넣는 값**
+
+| 값 | Type | 비고 |
+| --- | --- | --- |
+| Items | 항목 목록 | **필수.** 드롭다운 항목. 항목 하나는 `{ key, value }` (`value`가 화면에 보이는 글자) |
+| SelectedItem | 항목 | **필수.** 지금 선택된 항목. 라벨에 이 값이 표시됩니다 |
+| OnItemClick | Function | **필수.** 항목을 골랐을 때 호출 · 동작용 |
+| AlignRight | Boolean | 드롭다운 목록을 **오른쪽 기준으로** 펼칩니다. 기본은 왼쪽 기준 |
+
+**피그마 ↔ 코드 대응**
+
+피그마의 `Variant`와 `State`는 코드에 따로 넣는 값이 없고, **자동으로** 정해집니다.
+
+| 피그마 | 코드 | 모습 |
+| --- | --- | --- |
+| `Variant = Empty` | 값·Placeholder 없음 | 빈 입력 영역 |
+| `Variant = Placeholder` | `placeholder`만 있음 | 회색 안내 문구 |
+| `Variant = Text` | 입력값 있음 | 검정 검색어 |
+| `State = Enabled` | 기본 | 회색 테두리 |
+| `State = Hovered` | 마우스 hover (자동) | Primary 테두리 |
+| `State = Focused` | 입력 중 (자동) | Primary 테두리 |
+| `State = Disabled` | `disabled` | 회색 배경, 글자·아이콘 흐리게 |
+
+> ```tsx
+> <SearchField placeholder="프로젝트명으로 검색" onSearch={search}
+>   value={keyword} onChange={e => setKeyword(e.target.value)}
+>   filters={{ items: [{ key: 'all', value: '전체' }, { key: 'title', value: '프로젝트명' }],
+>              selectedItem, onItemClick: setSelectedItem }} />
+> ```
+
+## Z. 미결 (구현하지 말 것)
+
+> 아래는 **결정되지 않은 제안**입니다. 구현 기준은 위 A~C입니다. 결정되면 본문으로 옮기고 여기서 지웁니다.
+
+1. **피그마 시안의 2줄 텍스트**: 드롭다운이 있는 변형에서 "플레이스 홀더"·"입력한 텍스트"가 2줄로 꺾여 있어, 이 문서의 Don't("검색어를 2줄로 표시하지 않습니다")와 어긋납니다. 피그마 텍스트를 1줄 고정으로 수정 필요
+2. **피그마 드롭다운 켜고 끄기**: 피그마 변형 12종이 모두 드롭다운이 있는 모습입니다. 드롭다운 없는 SearchField를 피그마에서 어떻게 표현하는지(Boolean 속성 유무) 확인 필요
+3. **스토리북 예시 (개발팀 전달)**: 스토리북 예시의 드롭다운 항목이 정렬 기준("기본 정렬 순", "금액 높은 순" …)이라 가이드(검색 범위: `전체`, `프로젝트명`, `작성자`)와 다릅니다. 또 `SearchField.tsx` 주석 예시가 `label` · `{ label, value }` 형태를 쓰는데 실제 타입은 `{ key, value }` · `selectedItem` · `onItemClick`입니다
+4. **`Filters` 이름 변경 제안**: 스토리북 `filters`와 피그마 `TextButtonDropdown`을 **`withFilter`** 로 통일하자는 제안. 코드 prop 이름을 바꾸는 일이라 개발팀과 결정 필요

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

@@ -0,0 +1,123 @@
+---
+id: INPUT-08
+component: TextButton
+version: 0.0.2
+status: draft
+figma.componentKey: 3eee8fa20aa4f3bb067ce717749cf42223042f16
+---
+
+# 8. TextButton
+
+**개정 이력**
+
+- 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 등 **방향·이동을 보조** |
+
+
+> Container가 없어 **텍스트 크기가 곧 클릭 영역**입니다. 별도의 패딩을 갖지 않습니다.
+
+## B. Description
+
+### 1. 정의
+
+클릭 시 이벤트가 발생하는 경우에 사용되는 컴포넌트로, 보조 액션 또는 행동 트리거에 적합한 텍스트형 버튼입니다.
+
+### 2. 사용 시점
+
+- 부가적이지만 **강조가 필요한 행동**에 사용합니다. (`수정`, `삭제`, `더보기`)
+- 페이지 내에서 액션이 일어나는 경우, **Link 대신** TextButton을 사용합니다. Link는 페이지 이동에만 씁니다.
+- 화면의 주요 액션(Primary)에는 사용하지 않습니다. 배경이 있는 **Button**을 사용합니다.
+- 테이블 행·카드 하단처럼 여러 액션을 좁은 공간에 나열해야 할 때 적합합니다.
+- 아이콘만으로 의미가 통하고 공간이 없다면 **IconButton**을 사용합니다.
+- 아이콘 색상은 텍스트 색상을 따릅니다.
+- **밑줄은 텍스트에만** 적용하고 아이콘에는 적용하지 않습니다.
+- Hovered에서 색상은 바뀌지 않습니다. 밑줄만 추가됩니다.
+
+> TextButton은 Button보다 **낮은 시각 위계**를 가집니다. 한 화면에서 Button과 TextButton이 함께 있으면 Button이 주요 액션입니다.
+
+### 3. 키워드
+
+TextButton, 텍스트버튼, 버튼, Btn, txt, 텍스트 링크, Primary Text Button
+
+### 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 모두 텍스트 굵기는 **Medium**입니다. 본문과 구분되도록 하는 장치입니다.
+- 주변 본문의 폰트 크기에 맞춰 Size를 고릅니다. 본문이 16이면 Medium, 14면 Small을 씁니다.
+
+### 4-1. Color
+
+
+| Color       | 사용 상황          |
+| ----------- | -------------- |
+| **Primary** | 주요 행동을 유도하는 경우 |
+| **Gray**    | 보조 행동          |
+
+
+- 한 묶음 안에서 **주요 행동 하나만 Primary**로 두고 나머지는 Gray로 둡니다. (`수정` Primary · `삭제` Gray)
+- 삭제·취소 같은 부정적 액션을 Primary로 강조하지 않습니다.
+
+### 4-2. 나란히 배치할 때
+
+- 여러 TextButton을 나란히 둘 때는 **Divider(1 × 16)** 로 구분하고, Divider 좌우에 **각각 12 간격**을 둡니다.
+- 같은 묶음 안에서는 Size를 통일합니다.
+
+### 4-3. 클릭·터치 영역
+
+1. 텍스트 크기가 그대로 클릭 영역이므로 **모바일에서는 투명 여백을 더해 최소 44 × 44**를 확보합니다.
+2. 여백을 더해도 **텍스트의 정렬선은 유지**합니다. 좌측 정렬된 문단 안에서 들여쓰기가 생기면 안 됩니다.
+
+### 4-4. Overflow
+
+1. 라벨은 **1줄로 고정**하며 줄바꿈하지 않습니다.
+2. 너비를 초과하면 말줄임이 아니라 **라벨 자체를 짧게 고쳐 쓰는 것이 원칙**입니다.
+
+### 5. Do / Don't
+
+**Do**
+
+- 라벨은 동사 중심으로 짧게 작성합니다. (`수정`, `더보기`)
+- 시각적 힌트가 필요한 경우에만 아이콘을 추가합니다.
+- 같은 묶음의 TextButton은 Size와 정렬을 맞춥니다.
+- 페이지 내 액션에는 Link 대신 TextButton을 사용합니다.
+
+**Don't**
+
+- 라벨 앞뒤에 아이콘을 동시에 넣지 않습니다.
+- 본문 문장 중간에 끼워 넣지 않습니다. 그 경우는 Link입니다.
+- 한 묶음에서 Primary를 두 개 이상 쓰지 않습니다.
+- 밑줄을 기본 상태에 상시 적용하지 않습니다. 밑줄은 Hovered의 표현입니다.
+
+## C. Properties
+
+Property 이름은 **소문자로 시작**하게 적었습니다. 피그마에만 있는 속성도 같은 방식으로 적고, 비고에 `피그마에만 존재`라고 표시했습니다.
+
+| Property | Type | Values | 비고 |
+| --- | --- | --- | --- |
+| 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과 같은 문제)