@makitt.io/mds-mcp-server 0.1.3 → 0.2.1

package/dist/data/playbook/form.md

@@ -5,17 +5,33 @@
 > 인용 컴포넌트는 모두 `packages/mds/src/` 에 실재 — fabrication 0. 임의 룰은
 > **TBD** 명시 — 사용자 합의 후 결정.
 
+## Scope
+
+이 문서는 **MDS component usage** 를 정한다.
+
+- 컨테이너: page-form / drawer-form / modal-form
+- 배치: vertical stack / 2-col pair / Section + AnchorNav
+- 필드: `Field` compound + input component mapping
+- 피드백: `Field.Error` / `Banner` / `toast` / `Notification`
+- 기본 form library guidance: simple/medium form 은 RHF + Zod 기본/권장
+
+도메인 form architecture 는 각 app 의 playbook 이 정한다. MDS 는 UI/a11y/layout
+contract 를 강제하고, state model 은 강제하지 않는다. 단, RHF + Zod 가
+기본값이다. 커스텀 store/reducer 는 RHF 로 표현하면 도메인 모델을 왜곡하거나
+기존 동작을 깨는 경우에만 허용하고, 그 사유와 adapter contract 를 app playbook
+에 명시해야 한다.
+
 ---
 
 ## 1. 컨테이너 결정
 
-| 상황 | 컨테이너 | 이유 | Mobile 변형 |
-|---|---|---|---|
-| 페이지 본문 메인 작업 (상품 생성/수정, 설정 페이지) | **page-form** (`Page` shell 안 직접 Form) | 본업 — 가장 큰 공간 | Sidebar → drawer, content full-width, sticky action bar bottom |
-| 목록 화면 옆에서 행 1개 부분 편집 (이름·상태 빠른 수정) | **drawer-form** (`Drawer` 안 Form) | 목록 컨텍스트 유지 + side-by-side | `Drawer side="bottom"` (Sheet style) |
-| 짧은 입력 (필드 ≤ 5 · 확인성 액션, 쿠폰 발급) | **modal-form** (`Modal` 안 Form) | 짧은 입력 + 강제 집중. 5 초과면 page 또는 drawer 로 | `Modal` → full-screen Sheet |
-| 메인 form 안 sub-entity 편집 (variant 추가) | **nested drawer-form** (메인 form 살아있는 채 Drawer 오픈) | nested modal 보다 mental stack 얕음 | 동일 — Drawer 가 적합 |
-| 단순 확인 ("정말 삭제?") | **`Dialog` (confirm)** — Form 아님 | input 없음, action 만 | `Modal.confirm` 그대로 |
+| 상황                                                    | 컨테이너                                                   | 이유                                                | Mobile 변형                                                    |
+| ------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------- |
+| 페이지 본문 메인 작업 (상품 생성/수정, 설정 페이지)     | **page-form** (`Page` shell 안 직접 Form)                  | 본업 — 가장 큰 공간                                 | Sidebar → drawer, content full-width, sticky action bar bottom |
+| 목록 화면 옆에서 행 1개 부분 편집 (이름·상태 빠른 수정) | **drawer-form** (`Drawer` 안 Form)                         | 목록 컨텍스트 유지 + side-by-side                   | `Drawer side="bottom"` (Sheet style)                           |
+| 짧은 입력 (필드 ≤ 5 · 확인성 액션, 쿠폰 발급)           | **modal-form** (`Modal` 안 Form)                           | 짧은 입력 + 강제 집중. 5 초과면 page 또는 drawer 로 | `Modal` → full-screen Sheet                                    |
+| 메인 form 안 sub-entity 편집 (variant 추가)             | **nested drawer-form** (메인 form 살아있는 채 Drawer 오픈) | nested modal 보다 mental stack 얕음                 | 동일 — Drawer 가 적합                                          |
+| 단순 확인 ("정말 삭제?")                                | **`Dialog` (confirm)** — Form 아님                         | input 없음, action 만                               | `Modal.confirm` 그대로                                         |
 
 ### 절대 금지
 
@@ -26,47 +42,52 @@
 
 ## 2. Form 안 input 배치 — Section 개수 기준 + caller 재량
 
-| 패턴 | 사용 시점 | 예시 | Mobile 변형 |
-|---|---|---|---|
-| **vertical stack** (단일 column) | **1 section** (단일 의미 단위) | 회원가입, 단순 modal-form (쿠폰 발급), 단일 entity 의 simple form | 그대로 |
-| **2-col pair** (horizontal grid) | 의미상 쌍 (시작-종료, 가로-세로, 이름-이메일) — section 내부 또는 단독 | 주소 입력 (이름&이메일 가로 / 도시&우편 가로) | 1-col vertical |
-| **Section + AnchorNav** | **6+ section** (큰 form, 의미 단위 분명) | 상품 등록 (9 section), 큰 설정 페이지 | AnchorNav → drawer (좌측 sidebar 모드) |
-| **2-5 section** | 의미 단위 명확 시 vertical or 2-col pair — caller 재량 | 정책 편집 (3 section), 사용자 프로필 (4 section) | 그대로 또는 1-col |
+| 패턴                             | 사용 시점                                                              | 예시                                                              | Mobile 변형                            |
+| -------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------- |
+| **vertical stack** (단일 column) | **1 section** (단일 의미 단위)                                         | 회원가입, 단순 modal-form (쿠폰 발급), 단일 entity 의 simple form | 그대로                                 |
+| **2-col pair** (horizontal grid) | 의미상 쌍 (시작-종료, 가로-세로, 이름-이메일) — section 내부 또는 단독 | 주소 입력 (이름&이메일 가로 / 도시&우편 가로)                     | 1-col vertical                         |
+| **Section + AnchorNav**          | **6+ section** (큰 form, 의미 단위 분명)                               | 상품 등록 (9 section), 큰 설정 페이지                             | AnchorNav → drawer (좌측 sidebar 모드) |
+| **2-5 section**                  | 의미 단위 명확 시 vertical or 2-col pair — caller 재량                 | 정책 편집 (3 section), 사용자 프로필 (4 section)                  | 그대로 또는 1-col                      |
 
-> **결정 근거** — Section 개수가 form 의 정신적 무게의 진짜 기준. 필드 수보다 의미 단위 분명.
-> 동일 9 필드라도 1 section (단순 form) vs 6 section (복잡 form) 의 UX 가 다름.
+> **결정 근거** — Section 개수가 form 의 정신적 무게의 진짜 기준. 필드 수보다
+> 의미 단위 분명. 동일 9 필드라도 1 section (단순 form) vs 6 section (복잡 form)
+> 의 UX 가 다름.
 
 ---
 
 ## 3. Field 타입 매핑 (데이터 → MDS 컴포넌트)
 
-> 모든 컴포넌트 `packages/mds/src/primitives/inputs/` + `compounds/` 실재 검증됨.
-
-| 데이터 형태 | MDS 컴포넌트 | 비고 |
-|---|---|---|
-| 짧은 문자열 (이름, 슬러그) | `TextField` | |
-| 긴 문자열 (설명, 메모) | `Textarea` | |
-| 리치 텍스트 (블로그 본문) | `RichText` (compounds) | 도메인 한정 |
-| 정수 / 통화 / 수량 | `NumberInput` | ArrowUp/Down + Shift x10 + Home/End 키보드 ✓ |
-| 단일 선택 (≤ 7) | `RadioGroup` | 시각적 비교 가능 |
-| 단일 선택 (8+) | `Select` | dropdown |
-| 다중 선택 (작은, ≤ 5) | `Checkbox` ×N | 시각적 비교 |
-| 다중 선택 (큰, 6+) | `<Select multiple>` | discriminated union — `multiple: true` 시 value 가 array. token chip 표시 |
-| boolean 즉시 효과 toggle | `Switch` | TBD: 자동 저장 / 수동 저장 |
-| boolean 약관 동의 | `Checkbox` | submit 시 평가 |
-| 날짜 1개 | `DatePicker` | |
-| 시간 | `TimePicker` | |
-| 숫자 슬라이더 | `Slider` / `RangeSlider` | |
-| 색상 / 토큰 선택 | `Swatch` | |
-| chip 형태 다중 토글 | `ChipToggle` | |
-| 단계형 입력 (1→2→3) | `Stepper` (primitives/feedback) + 페이지 분할 | wizard |
+> 모든 컴포넌트 `packages/mds/src/primitives/inputs/` + `compounds/` 실재
+> 검증됨.
+
+| 데이터 형태                | MDS 컴포넌트                                  | 비고                                                                      |
+| -------------------------- | --------------------------------------------- | ------------------------------------------------------------------------- |
+| 짧은 문자열 (이름, 슬러그) | `TextField`                                   |                                                                           |
+| 긴 문자열 (설명, 메모)     | `Textarea`                                    |                                                                           |
+| 리치 텍스트 (블로그 본문)  | `RichText` (compounds)                        | 도메인 한정                                                               |
+| 정수 / 통화 / 수량         | `NumberInput`                                 | ArrowUp/Down + Shift x10 + Home/End 키보드 ✓                              |
+| 단일 선택 (≤ 7)            | `RadioGroup`                                  | 시각적 비교 가능                                                          |
+| 단일 선택 (8+)             | `Select`                                      | dropdown                                                                  |
+| 다중 선택 (작은, ≤ 5)      | `Checkbox` ×N                                 | 시각적 비교                                                               |
+| 다중 선택 (큰, 6+)         | `<Select multiple>`                           | discriminated union — `multiple: true` 시 value 가 array. token chip 표시 |
+| boolean 즉시 효과 toggle   | `Switch`                                      | TBD: 자동 저장 / 수동 저장                                                |
+| boolean 약관 동의          | `Checkbox`                                    | submit 시 평가                                                            |
+| 날짜 1개                   | `DatePicker`                                  |                                                                           |
+| 시간                       | `TimePicker`                                  |                                                                           |
+| 숫자 슬라이더              | `Slider` / `RangeSlider`                      |                                                                           |
+| 색상 / 토큰 선택           | `Swatch`                                      |                                                                           |
+| chip 형태 다중 토글        | `ChipToggle`                                  |                                                                           |
+| 단계형 입력 (1→2→3)        | `Stepper` (primitives/feedback) + 페이지 분할 | wizard                                                                    |
 
 ### `Field` compound — label + control + error + hint
 
 `packages/mds/src/compounds/Field/` 가 input 을 감싸는 표준 compound:
+
 - `Field.Label`, control (TextField 등), `Field.Error`, `Field.Hint`
-- input 의 a11y attribute (htmlFor / aria-describedby / aria-errormessage / aria-invalid) 자동 wire
-- 원자 input 직접 사용 보다 `Field` compound 권장 (Storybook 의 stories 도 Field 사용 예시)
+- input 의 a11y attribute (htmlFor / aria-describedby / aria-errormessage /
+  aria-invalid) 자동 wire
+- 원자 input 직접 사용 보다 `Field` compound 권장 (Storybook 의 stories 도 Field
+  사용 예시)
 
 ### 파일 / 이미지 — `FileUpload` (Step 13 완료)
 
@@ -94,83 +115,85 @@
 </Field.Root>
 ```
 
-- mds 는 picker / drag-drop / preview / progress UI 만 책임. server upload (S3 / Cloudinary / 자체 API / multipart) 는 caller 결정.
-- `upload` 안 주면 deferred mode (File 객체 만 보관, form submit 시 caller 가 처리).
+- mds 는 picker / drag-drop / preview / progress UI 만 책임. server upload (S3 /
+  Cloudinary / 자체 API / multipart) 는 caller 결정.
+- `upload` 안 주면 deferred mode (File 객체 만 보관, form submit 시 caller 가
+  처리).
 - Controlled (`value` + `onChange`) + Uncontrolled (`defaultValue`) 둘 다 지원.
-- `FileItem`: `{ id, file?, url?, name, size, type, status: 'pending'|'uploading'|'success'|'error', progress?, error? }` — File 객체 + server URL 양쪽 표현 가능 (편집 시 기존 URL 도 자연 처리).
+- `FileItem`:
+  `{ id, file?, url?, name, size, type, status: 'pending'|'uploading'|'success'|'error', progress?, error? }`
+  — File 객체 + server URL 양쪽 표현 가능 (편집 시 기존 URL 도 자연 처리).
 - `onReject` callback — `accept` / `maxSize` / `maxFiles` validation fail 시.
 
 ---
 
 ## 4. 검증 + 에러 표시
 
-| 에러 종류 | 표시 위치 | 컴포넌트 |
-|---|---|---|
-| 단일 필드 검증 (format / 필수 / length) | **inline 필드 아래** | `Field.Error` slot |
-| Cross-field (비밀번호 ≠ 확인) | inline 두 필드 + form summary | `Field.Error` + `Banner` 상단 |
-| Form 전체 검증 (서버 422 + 필드 에러) | 필드별 분배 + 상단 `Banner` 요약 | `Banner` + `Field.Error` |
-| 비검증성 서버 에러 (500, 네트워크) — **일시적** | **toast.error** | `toast.error(title, {description})` |
-| 단순 정보 (저장됐다) — **일시적** | **toast.success** | `toast.success(...)` |
-| **영속** 경고 (라이선스 만료, 결제 만료) | **Notification** (banner, 직접 닫기) | mds 의 영속 Notification — Step 14 별도 신규 작업. 임시 — `Banner` (variant=`warning` / `error`) 의 dismissible mode 활용 |
+| 에러 종류                                       | 표시 위치                            | 컴포넌트                                                                                                                  |
+| ----------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| 단일 필드 검증 (format / 필수 / length)         | **inline 필드 아래**                 | `Field.Error` slot                                                                                                        |
+| Cross-field (비밀번호 ≠ 확인)                   | inline 두 필드 + form summary        | `Field.Error` + `Banner` 상단                                                                                             |
+| Form 전체 검증 (서버 422 + 필드 에러)           | 필드별 분배 + 상단 `Banner` 요약     | `Banner` + `Field.Error`                                                                                                  |
+| 비검증성 서버 에러 (500, 네트워크) — **일시적** | **toast.error**                      | `toast.error(title, {description})`                                                                                       |
+| 단순 정보 (저장됐다) — **일시적**               | **toast.success**                    | `toast.success(...)`                                                                                                      |
+| **영속** 경고 (라이선스 만료, 결제 만료)        | **Notification** (banner, 직접 닫기) | mds 의 영속 Notification — Step 14 별도 신규 작업. 임시 — `Banner` (variant=`warning` / `error`) 의 dismissible mode 활용 |
 
-> **핵심 구분**: **Toast = 일시적** (자동 사라짐), **Notification = 영속** (명시적 닫기 전 유지).
+> **핵심 구분**: **Toast = 일시적** (자동 사라짐), **Notification = 영속**
+> (명시적 닫기 전 유지).
 
 ### 검증 시점 (RHF mode)
 
-| Form 종류 | RHF mode | 동작 |
-|---|---|---|
-| **default** (modal-form / drawer-form / 작은 form) | `onSubmit` (RHF default) | submit 시 검증. 입력 중 방해 X |
-| **page-form** (큰 form / multi-section) | `onTouched` 권장 | blur 후 첫 검증 + 이후 change 시 즉시 재검증 (한 번 틀린 필드는 실시간 fix 도움) |
-| **특수 케이스** (비밀번호 강도, slug 중복) | `onChange` (caller 결정) | 실시간 도움 필수 |
+| Form 종류                                          | RHF mode                 | 동작                                                                             |
+| -------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------- |
+| **default** (modal-form / drawer-form / 작은 form) | `onSubmit` (RHF default) | submit 시 검증. 입력 중 방해 X                                                   |
+| **page-form** (큰 form / multi-section)            | `onTouched` 권장         | blur 후 첫 검증 + 이후 change 시 즉시 재검증 (한 번 틀린 필드는 실시간 fix 도움) |
+| **특수 케이스** (비밀번호 강도, slug 중복)         | `onChange` (caller 결정) | 실시간 도움 필수                                                                 |
 
-확정 룰:
-| 시점 | 동작 |
-|---|---|
-| submit | 전체 form 검증 + 첫 에러 필드로 scroll/focus |
-| 서버 응답 422 | 서버 에러를 RHF `setError` 로 필드 분배 |
+확정 룰: | 시점 | 동작 | |---|---| | submit | 전체 form 검증 + 첫 에러 필드로
+scroll/focus | | 서버 응답 422 | 서버 에러를 RHF `setError` 로 필드 분배 |
 
 ---
 
 ## 5. 저장 액션
 
-| 액션 종류 | 버튼 위치 | 비활성 조건 |
-|---|---|---|
-| 페이지 form 저장 | 페이지 하단 sticky `Toolbar` 또는 `PageHeader` 우측 primary | `isDirty === false` 또는 `isSubmitting` |
-| Modal/Drawer form 저장 | Footer 우측 primary | 동일 |
-| 위험 액션 (삭제, 환불) | `Modal.confirm` + 빨간 primary | 항상 |
+| 액션 종류              | 버튼 위치                                                   | 비활성 조건                             |
+| ---------------------- | ----------------------------------------------------------- | --------------------------------------- |
+| 페이지 form 저장       | 페이지 하단 sticky `Toolbar` 또는 `PageHeader` 우측 primary | `isDirty === false` 또는 `isSubmitting` |
+| Modal/Drawer form 저장 | Footer 우측 primary                                         | 동일                                    |
+| 위험 액션 (삭제, 환불) | `Modal.confirm` + 빨간 primary                              | 항상                                    |
 
 ### Inline 편집 (DataGrid 의 1 필드 빠른 수정)
 
-| 동작 | 결정 |
-|---|---|
-| 활성화 | cell click → input mode (pencil icon optional) |
-| **저장** | **Enter 키 또는 체크 버튼 명시 click** (blur 자동 저장 ❌) |
-| 취소 | Esc 키 또는 X 버튼 |
-| 위험 / 큰 필드 변경 | Inline 안 함 — drawer / modal 사용 (caller 재량) |
+| 동작                | 결정                                                       |
+| ------------------- | ---------------------------------------------------------- |
+| 활성화              | cell click → input mode (pencil icon optional)             |
+| **저장**            | **Enter 키 또는 체크 버튼 명시 click** (blur 자동 저장 ❌) |
+| 취소                | Esc 키 또는 X 버튼                                         |
+| 위험 / 큰 필드 변경 | Inline 안 함 — drawer / modal 사용 (caller 재량)           |
 
-> **이유** — Notion/Airtable 같은 blur 자동 저장은 실수 위험 + 의도 불명확.
-> 명시 저장 = click 1 회 더지만 의도 확실.
+> **이유** — Notion/Airtable 같은 blur 자동 저장은 실수 위험 + 의도 불명확. 명시
+> 저장 = click 1 회 더지만 의도 확실.
 
 ### Submit 후 결과 처리
 
-| 결과 | 처리 |
-|---|---|
+| 결과                  | 처리                                                    |
+| --------------------- | ------------------------------------------------------- |
 | 200 OK (modal/drawer) | 컨테이너 닫기 + 부모 query invalidate + `toast.success` |
-| 200 OK (페이지) | 페이지 유지 + `isDirty=false` reset + `toast.success` |
-| 4xx 검증 | 컨테이너 유지 + 필드 에러 분배 + 첫 에러 scroll |
-| 5xx / 네트워크 | 컨테이너 유지 + `toast.error` |
+| 200 OK (페이지)       | 페이지 유지 + `isDirty=false` reset + `toast.success`   |
+| 4xx 검증              | 컨테이너 유지 + 필드 에러 분배 + 첫 에러 scroll         |
+| 5xx / 네트워크        | 컨테이너 유지 + `toast.error`                           |
 
 ### Optimistic update — 기본 적용
 
-| 결정 | 동작 |
-|---|---|
-| **기본** | **모든 mutation optimistic** — UI 즉시 갱신, 서버 응답 비동기 |
-| Rollback | 5xx / network error 시 자동 rollback + `toast.error("저장 실패")` |
-| 4xx 검증 에러 | rollback + 필드 에러 분배 + 첫 에러 scroll |
+| 결정                   | 동작                                                                     |
+| ---------------------- | ------------------------------------------------------------------------ |
+| **기본**               | **모든 mutation optimistic** — UI 즉시 갱신, 서버 응답 비동기            |
+| Rollback               | 5xx / network error 시 자동 rollback + `toast.error("저장 실패")`        |
+| 4xx 검증 에러          | rollback + 필드 에러 분배 + 첫 에러 scroll                               |
 | **예외** (caller 결정) | 결제 / 환불 / 큰 금액 mutation — 명시 응답 대기 (`isSubmitting` loading) |
 
-> **이유** — UX 가장 빠름. React Query 의 `onMutate` + `setQueryData` + `onError rollback`
-> 패턴 표준화.
+> **이유** — UX 가장 빠름. React Query 의 `onMutate` + `setQueryData` +
+> `onError rollback` 패턴 표준화.
 
 ---
 
@@ -178,12 +201,12 @@
 
 상세 → [array-input Playbook](./array-input.md) (Step 4.6).
 
-| 패턴 | 컴포넌트 | 비고 |
-|---|---|---|
-| 짧은 동질 배열 (태그) | `ChipToggle` | item = 단순 string |
-| 가변 row (variant 가격) | RHF `useFieldArray` + `Stack` | 각 row = sub-form |
-| nested entity 다수 (정책, 결제 옵션) | `useFieldArray` + row 클릭 시 **drawer 편집** | row = 요약 |
-| reorder | `Tree` 또는 `useFieldArray` + dnd-kit (mds 자체 dnd 없음) | |
+| 패턴                                 | 컴포넌트                                                  | 비고               |
+| ------------------------------------ | --------------------------------------------------------- | ------------------ |
+| 짧은 동질 배열 (태그)                | `ChipToggle`                                              | item = 단순 string |
+| 가변 row (variant 가격)              | RHF `useFieldArray` + `Stack`                             | 각 row = sub-form  |
+| nested entity 다수 (정책, 결제 옵션) | `useFieldArray` + row 클릭 시 **drawer 편집**             | row = 요약         |
+| reorder                              | `Tree` 또는 `useFieldArray` + dnd-kit (mds 자체 dnd 없음) |                    |
 
 ---
 
@@ -194,29 +217,30 @@
 - `useSkillAutofill(agentType)` — generic hook
 - `FormFillApprovalBanner` — Apply / Reject UI
 - `skill-registry` — 등록 → AI 가 catalog query
-- 도메인별 fill hook / Banner / Prompt 작성 금지 (`useSkillAutofill` + shared 사용)
+- 도메인별 fill hook / Banner / Prompt 작성 금지 (`useSkillAutofill` + shared
+  사용)
 
 ---
 
 ## 8. 사용 시점 결정표 (lookup)
 
-| 케이스 | 답 |
-|---|---|
-| "필드 ≤ 5 짧은 입력" | modal-form |
-| "10+ 필드 + 설정 페이지" | page-form |
-| "리스트 행 빠른 편집" | drawer-form |
-| "정말 삭제?" | `Modal.confirm` |
-| "저장됐다 일시 알림" | `toast.success` |
-| "서버 500 일시 알림" | `toast.error` |
-| "라이선스 만료 영속 경고" | `Notification` (TBD) |
-| "input 옆 즉시 검증" | `Field.Error` inline |
-| "form 위 전체 요약 에러" | `Banner` 상단 |
-| "variant 줄 추가" | `useFieldArray` + 행 편집 = drawer |
-| "boolean 즉시 효과" | `Switch` (TBD 자동 저장 여부) |
-| "boolean submit 시 평가" | `Checkbox` |
-| "8+ 선택지" | `Select` |
-| "≤ 7 선택지" | `RadioGroup` |
-| "숫자 ↑↓ 키보드" | `NumberInput` (ArrowUp/Down + Shift x10) |
+| 케이스                    | 답                                       |
+| ------------------------- | ---------------------------------------- |
+| "필드 ≤ 5 짧은 입력"      | modal-form                               |
+| "10+ 필드 + 설정 페이지"  | page-form                                |
+| "리스트 행 빠른 편집"     | drawer-form                              |
+| "정말 삭제?"              | `Modal.confirm`                          |
+| "저장됐다 일시 알림"      | `toast.success`                          |
+| "서버 500 일시 알림"      | `toast.error`                            |
+| "라이선스 만료 영속 경고" | `Notification` (TBD)                     |
+| "input 옆 즉시 검증"      | `Field.Error` inline                     |
+| "form 위 전체 요약 에러"  | `Banner` 상단                            |
+| "variant 줄 추가"         | `useFieldArray` + 행 편집 = drawer       |
+| "boolean 즉시 효과"       | `Switch` (TBD 자동 저장 여부)            |
+| "boolean submit 시 평가"  | `Checkbox`                               |
+| "8+ 선택지"               | `Select`                                 |
+| "≤ 7 선택지"              | `RadioGroup`                             |
+| "숫자 ↑↓ 키보드"          | `NumberInput` (ArrowUp/Down + Shift x10) |
 
 ---
 
@@ -228,7 +252,8 @@
 - ❌ `Notification` 으로 "저장됨" — toast 가 맞음 (일시적)
 - ❌ Toast 로 "라이선스 만료" — Notification (영속)
 - ❌ raw `<input>` / `<textarea>` 사용 — mds `TextField` / `Textarea` 만
-- ❌ form value 를 `useState` 로 직접 관리 — RHF + Zod 만 (현재 ESLint 룰 추가 검토 중)
+- ❌ simple/medium form value 를 ad-hoc `useState` 로 흩어 관리 — RHF + Zod 또는
+  app-level form adapter 사용
 - ❌ Field compound 외부에 input — Field 의 a11y wire 누락
 - ❌ 도메인별 fill hook 작성 — `useSkillAutofill` 사용
 
@@ -236,13 +261,13 @@
 
 ## 10. Cross-cutting
 
-| Axis | 적용 |
-|---|---|
-| **Responsive** | 모든 표의 "Mobile 변형" 컬럼 — 자동 적용 |
-| **A11y** | Field compound 의 aria-* 자동 wire / RHF 의 setFocus 첫 에러 |
-| **i18n** | label / error / placeholder 모두 `t()` 통과 — apps/web 의 ESLint rule 강제 (Step 7) |
-| **AI fill** | skill-registry 등록만 — AI 가 자동 query |
-| **Catalog** | 각 컴포넌트 (TextField / Select / Field 등) 의 catalog.json 자동 추출 (Step 5) |
+| Axis           | 적용                                                                                |
+| -------------- | ----------------------------------------------------------------------------------- |
+| **Responsive** | 모든 표의 "Mobile 변형" 컬럼 — 자동 적용                                            |
+| **A11y**       | Field compound 의 aria-\* 자동 wire / RHF 의 setFocus 첫 에러                       |
+| **i18n**       | label / error / placeholder 모두 `t()` 통과 — apps/web 의 ESLint rule 강제 (Step 7) |
+| **AI fill**    | skill-registry 등록만 — AI 가 자동 query                                            |
+| **Catalog**    | 각 컴포넌트 (TextField / Select / Field 등) 의 catalog.json 자동 추출 (Step 5)      |
 
 ---
 
@@ -250,37 +275,42 @@
 
 ### 확정 (cycle 1)
 
-| § | 결정 |
-|---|---|
-| §2 Form 배치 | Section 개수 기준 (1 vertical / 2-5 caller 재량 / 6+ AnchorNav) |
-| §4 RHF mode | default `onSubmit`, page-form `onTouched`, 특수 `onChange` |
-| §5 Inline 편집 | 허용 + Enter/체크 명시 저장 (blur 자동 ❌) + Esc 취소 |
-| §5 Optimistic | 모든 mutation 기본 적용 + rollback + error toast. 결제/환불 예외 |
+| §              | 결정                                                             |
+| -------------- | ---------------------------------------------------------------- |
+| §2 Form 배치   | Section 개수 기준 (1 vertical / 2-5 caller 재량 / 6+ AnchorNav)  |
+| §4 RHF mode    | default `onSubmit`, page-form `onTouched`, 특수 `onChange`       |
+| §5 Inline 편집 | 허용 + Enter/체크 명시 저장 (blur 자동 ❌) + Esc 취소            |
+| §5 Optimistic  | 모든 mutation 기본 적용 + rollback + error toast. 결제/환불 예외 |
 
 ### 확정 (cycle 2 — Step 4.1)
 
-| § | 결정 | 근거 |
-|---|---|---|
-| §3 다중 선택 (큰 list) | `<Select multiple>` 사용 — discriminated union (SelectSingleProps vs SelectMultipleProps) | mds 의 Select 가 이미 multiple prop 지원 검증됨 (Select.types.ts §79 + tests §102-194 + stories §100-151) |
-| §5 저장 button i18n key | `t('common.save')` / `t('common.cancel')` / `t('common.delete')` / `t('common.discard')` — 공통 namespace | apps/web 의 i18n.md §3 — common namespace |
-| §5 위험 액션 typing rule | 일반 삭제 = `Modal.confirm` (단순). **영향 큰 액션** (계정 삭제 / 가입자 전체 삭제 / DB drop / 환불 전체) = typing confirm — Modal 안 input + 정확한 문구 입력 시에만 destructive button enabled | 실수 방지 — confirm click 한 번보다 typing 이 의도 명시가 강함. caller 가 판단 ("이게 영향 큰가") |
-| §5 위험 액션 typing 표준 문구 | i18n key `confirm.typeXToConfirm` + `{x}` 가 entity name (shop slug / customer email / etc.) — 영문 또는 일치 텍스트 | 일관 UX (caller 별 다른 typing rule 안 됨) |
+| §                             | 결정                                                                                                                                                                                             | 근거                                                                                                      |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| §3 다중 선택 (큰 list)        | `<Select multiple>` 사용 — discriminated union (SelectSingleProps vs SelectMultipleProps)                                                                                                        | mds 의 Select 가 이미 multiple prop 지원 검증됨 (Select.types.ts §79 + tests §102-194 + stories §100-151) |
+| §5 저장 button i18n key       | `t('common.save')` / `t('common.cancel')` / `t('common.delete')` / `t('common.discard')` — 공통 namespace                                                                                        | apps/web 의 i18n.md §3 — common namespace                                                                 |
+| §5 위험 액션 typing rule      | 일반 삭제 = `Modal.confirm` (단순). **영향 큰 액션** (계정 삭제 / 가입자 전체 삭제 / DB drop / 환불 전체) = typing confirm — Modal 안 input + 정확한 문구 입력 시에만 destructive button enabled | 실수 방지 — confirm click 한 번보다 typing 이 의도 명시가 강함. caller 가 판단 ("이게 영향 큰가")         |
+| §5 위험 액션 typing 표준 문구 | i18n key `confirm.typeXToConfirm` + `{x}` 가 entity name (shop slug / customer email / etc.) — 영문 또는 일치 텍스트                                                                             | 일관 UX (caller 별 다른 typing rule 안 됨)                                                                |
 
 ### 별도 step (큰 작업 — Phase 2 계획)
 
-| 항목 | 별도 step |
-|---|---|
-| §3 FileUpload | **Step 13 — mds FileUpload 추가** (필요한 a11y / drag-drop / 진행률 / multi / preview / type validation 전체 컴포넌트 설계) |
+| 항목                 | 별도 step                                                                                                                       |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| §3 FileUpload        | **Step 13 — mds FileUpload 추가** (필요한 a11y / drag-drop / 진행률 / multi / preview / type validation 전체 컴포넌트 설계)     |
 | §4 Notification 영속 | **Step 14 — mds Notification 추가** (Toast 와 분리 — Toast 는 일시, Notification 은 영속. 직접 닫기 전 유지. badge 또는 inline) |
 
-> cycle 2 마무리 — form.md 의 모든 TBD 확정 또는 별도 step 으로 이관. mds Form 영역 = 완벽 마무리.
+> cycle 2 마무리 — form.md 의 모든 TBD 확정 또는 별도 step 으로 이관. mds Form
+> 영역 = 완벽 마무리.
 
 ---
 
 ## Related Playbooks
 
-- [feedback.md](./feedback.md) — Toast / Notification / Banner / Modal Dialog (Step 4.2)
+- [feedback.md](./feedback.md) — Toast / Notification / Banner / Modal Dialog
+  (Step 4.2)
 - [overlay.md](./overlay.md) — Modal / Drawer / Sheet / Dialog (Step 4.4)
 - [array-input.md](./array-input.md) — useFieldArray + drawer 편집 (Step 4.6)
 - [async-states.md](./async-states.md) — loading/error/empty/skeleton (Step 4.7)
-- [ai-fill.md](./ai-fill.md) — skill-registry + FormFillApprovalBanner (Step 4.8)
+- [ai-fill.md](./ai-fill.md) — skill-registry + FormFillApprovalBanner (Step
+  4.8)
+- [apps/web form-architecture.md](../../../../apps/web/docs/playbook/form-architecture.md)
+  — MAKITT web domain form adapter / shell rules