@makitt.io/mds-mcp-server 0.1.2 → 0.2.0

package/dist/data/playbook/feedback.md

@@ -1,44 +1,48 @@
 # MDS Playbook — Feedback (Toast / Notification / Banner / Modal Dialog)
 
-사용자에게 메시지 / 알림 / 결정 강제 의 약속.
+사용자에게 메시지 / 알림 / 결정 강제를 적용하는 약속.
 
-> 4 채널 명확 분리. **일시 vs 영속 / 인박스 vs 페이지 / 자유 vs 강제** 가 결정 기준.
+> 4 채널 명확 분리. **일시 vs 영속 / 인박스 vs 페이지 / 자유 vs 강제** 가 결정
+> 기준.
 
 ---
 
 ## 1. 4 채널 의도 분리
 
-| 채널 | 의도 | 사용자 액션 | mental model | 컴포넌트 |
-|---|---|---|---|---|
-| **Toast** | **일시적 알림** (1회 표시 후 사라짐) | 무시 가능 | 화면 corner 의 작은 알림 (자동 dismiss 4~6s) | `toast.success/error/info/warning(message, {description})` |
-| **Notification** (영속) | **놓치면 안 되는 경고** (사용자가 명시적 닫을 때까지 유지) | 명시 닫기 또는 action | 화면 상단/사이드의 banner (Inbox 같은 느낌) | `<Notification tone="warning" persistent>` — TBD (mds 추가 예정) |
-| **Banner** (inline) | **페이지 내 inline 안내** (해당 페이지의 상태) | 무시 가능 또는 dismiss | 페이지 내 box (정보/경고/에러) | `<Banner tone="info" variant="soft">` |
-| **Modal Dialog** | **결정 강제** (사용자 응답 받아야 진행) | confirm / cancel 필수 | 작업 중단 + 짧은 결정 | `Modal.confirm / alert / prompt` (overlay.md §5) |
+| 채널                    | 의도                                                       | 사용자 액션            | mental model                                 | 컴포넌트                                                         |
+| ----------------------- | ---------------------------------------------------------- | ---------------------- | -------------------------------------------- | ---------------------------------------------------------------- |
+| **Toast**               | **일시적 알림** (1회 표시 후 사라짐)                       | 무시 가능              | 화면 corner 의 작은 알림 (자동 dismiss 4~6s) | `toast.success/error/info/warning(message, {description})`       |
+| **Notification** (영속) | **놓치면 안 되는 경고** (사용자가 명시적 닫을 때까지 유지) | 명시 닫기 또는 action  | 화면 상단/사이드의 banner (Inbox 같은 느낌)  | `<Notification tone="warning" persistent>` — TBD (mds 추가 예정) |
+| **Banner** (inline)     | **페이지 내 inline 안내** (해당 페이지의 상태)             | 무시 가능 또는 dismiss | 페이지 내 box (정보/경고/에러)               | `<Banner tone="info" variant="soft">`                            |
+| **Modal Dialog**        | **결정 강제** (사용자 응답 받아야 진행)                    | confirm / cancel 필수  | 작업 중단 + 짧은 결정                        | `Modal.confirm / alert / prompt` (overlay.md §5)                 |
 
 ### 핵심 차이
 
-- **시간** — Toast (일시 4-6s) / Banner (페이지 동안) / Notification (영속) / Dialog (응답까지)
-- **위치** — Toast (corner) / Banner (페이지 inline) / Notification (상단/사이드 inbox) / Dialog (centered overlay)
-- **간섭** — Toast (무시 가능) / Banner (무시 가능) / Notification (명시 닫기) / Dialog (응답 필수)
+- **시간** — Toast (일시 4-6s) / Banner (페이지 동안) / Notification (영속) /
+  Dialog (응답까지)
+- **위치** — Toast (corner) / Banner (페이지 inline) / Notification (상단/사이드
+  inbox) / Dialog (centered overlay)
+- **간섭** — Toast (무시 가능) / Banner (무시 가능) / Notification (명시 닫기) /
+  Dialog (응답 필수)
 
 ---
 
 ## 2. 결정 표 (lookup)
 
-| 케이스 | 답 |
-|---|---|
-| "저장됐어요" | `toast.success("저장됨")` |
-| "서버 500 에러" | `toast.error("저장 실패", { description: getErrorDisplayMessage(error) })` |
-| "백그라운드 동기화 중" | `toast.info("동기화 중")` 또는 silent (Step 4.7 async-states) |
-| "비밀번호 강도 약함" (input 안 hint) | `Field.Hint` (form.md §3) |
-| "form 422 검증 에러 요약" (상단) | `<Banner tone="danger">` |
-| "라이선스 만료 7일 남음" (영속) | `<Notification tone="warning" persistent>` (mds 추가 예정) |
-| "결제 카드 만료" (매번 페이지 진입 시) | `<Notification persistent>` 또는 dashboard 의 `<Banner>` |
-| "이 페이지는 베타입니다" (페이지 inline) | `<Banner tone="info" variant="soft">` |
-| "정말 삭제할까요?" | `Modal.confirm` (Dialog) |
-| "환불 사유 입력해주세요" | `Modal.prompt` (Dialog with input) |
-| "주문 완료" 페이지 진입 시 일회성 | `toast.success` (즉시 사라짐) |
-| "주문 완료" 페이지에 항상 표시 | `<Banner tone="success">` (페이지 안 inline) |
+| 케이스                                   | 답                                                                         |
+| ---------------------------------------- | -------------------------------------------------------------------------- |
+| "저장됐어요"                             | `toast.success("저장됨")`                                                  |
+| "서버 500 에러"                          | `toast.error("저장 실패", { description: getErrorDisplayMessage(error) })` |
+| "백그라운드 동기화 중"                   | `toast.info("동기화 중")` 또는 silent (Step 4.7 async-states)              |
+| "비밀번호 강도 약함" (input 안 hint)     | `Field.Hint` (form.md §3)                                                  |
+| "form 422 검증 에러 요약" (상단)         | `<Banner tone="danger">`                                                   |
+| "라이선스 만료 7일 남음" (영속)          | `<Notification tone="warning" persistent>` (mds 추가 예정)                 |
+| "결제 카드 만료" (매번 페이지 진입 시)   | `<Notification persistent>` 또는 dashboard 의 `<Banner>`                   |
+| "이 페이지는 베타입니다" (페이지 inline) | `<Banner tone="info" variant="soft">`                                      |
+| "정말 삭제할까요?"                       | `Modal.confirm` (Dialog)                                                   |
+| "환불 사유 입력해주세요"                 | `Modal.prompt` (Dialog with input)                                         |
+| "주문 완료" 페이지 진입 시 일회성        | `toast.success` (즉시 사라짐)                                              |
+| "주문 완료" 페이지에 항상 표시           | `<Banner tone="success">` (페이지 안 inline)                               |
 
 ---
 
@@ -46,12 +50,12 @@
 
 ### Toast tone
 
-| Tone | 사용 | 색 |
-|---|---|---|
-| success | 저장 / 완료 / 성공 | green |
-| error | 실패 / 5xx / network | red |
-| warning | 주의 / 약한 에러 / 부분 성공 | amber |
-| info | 정보 / 진행 / 백그라운드 알림 | blue |
+| Tone    | 사용                          | 색    |
+| ------- | ----------------------------- | ----- |
+| success | 저장 / 완료 / 성공            | green |
+| error   | 실패 / 5xx / network          | red   |
+| warning | 주의 / 약한 에러 / 부분 성공  | amber |
+| info    | 정보 / 진행 / 백그라운드 알림 | blue  |
 
 ### Toast 패턴
 
@@ -80,8 +84,9 @@ toast.promise(saveOrder(), {
 
 ### Toast 위치
 
-- mds 의 `<Toaster position="top-right">` (root layout 의 mount)
-- position 변경 — `Toaster` 의 prop (top-left / top-right / top-center / bottom-* / etc.)
+- mds 의 `<Toaster position="top-right">` (root layout 에 mount)
+- position 변경 — `Toaster` prop (top-left / top-right / top-center / bottom-\*
+  / etc.)
 - mobile = top-center 권장 (TBD)
 
 ---
@@ -110,20 +115,21 @@ import { Banner } from '@makitt/mds';
 
 ### Banner tone + variant
 
-| Tone | variant | 의도 |
-|---|---|---|
-| info | soft (default) | 일반 정보 안내 |
-| success | soft | 페이지 단위 성공 (예: "주문 완료") |
-| warning | soft | 주의 / 만료 임박 |
-| danger | soft | 페이지 에러 / 결제 만료 |
-| (각 tone) | solid | 강조 — 큰 announcement (시스템 점검 등) |
-| (각 tone) | outline | 약한 정보 |
+| Tone      | variant        | 의도                                    |
+| --------- | -------------- | --------------------------------------- |
+| info      | soft (default) | 일반 정보 안내                          |
+| success   | soft           | 페이지 단위 성공 (예: "주문 완료")      |
+| warning   | soft           | 주의 / 만료 임박                        |
+| danger    | soft           | 페이지 에러 / 결제 만료                 |
+| (각 tone) | solid          | 강조 — 큰 announcement (시스템 점검 등) |
+| (각 tone) | outline        | 약한 정보                               |
 
 ---
 
 ## 5. Notification (영속) — `overlays/Notification/` (Step 14 완료)
 
-영속 알림 inbox + Compound API. `notificationStore` (sessionStorage persist) + `useNotification()` hook.
+영속 알림 inbox + Compound API. `notificationStore` (sessionStorage persist) +
+`useNotification()` hook.
 
 ### Compound API
 
@@ -134,12 +140,15 @@ import { Notification, useNotification } from '@makitt/mds';
 <Drawer.Root>
   <Drawer.Trigger>알림</Drawer.Trigger>
   <Drawer.Content side="right">
-    <Drawer.Header><Drawer.Title>알림</Drawer.Title><Drawer.Close /></Drawer.Header>
+    <Drawer.Header>
+      <Drawer.Title>알림</Drawer.Title>
+      <Drawer.Close />
+    </Drawer.Header>
     <Drawer.Body>
-      <Notification.Root />  {/* store-bound list 자동 render */}
+      <Notification.Root /> {/* store-bound list 자동 render */}
     </Drawer.Body>
   </Drawer.Content>
-</Drawer.Root>
+</Drawer.Root>;
 
 // (B) imperative API — 알림 추가
 const { push, markRead, dismiss, clear } = useNotification();
@@ -154,11 +163,16 @@ push({
 
 ### 핵심
 
-- **`overlays/Notification/`** layer — 알림 센터 는 Drawer / Popover overlay 안 mount (caller 위치 결정, mds 강요 X)
-- **`notificationStore`** — sessionStorage persist (새 session 시 자동 clear, 동일 session 의 dismiss state 유지)
-- **`useNotification()`** hook — items / unreadCount / push / markRead / markAllRead / dismiss / clear
-- **Compound parts** — `Notification.Root` (store-bound list + header + auto empty state)
-- **4 level** — info / success / warning / danger (axe-pass: `role="alert"` for warning/danger, `role="status"` for info/success)
+- **`overlays/Notification/`** layer — 알림 센터 는 Drawer / Popover overlay 안
+  mount (caller 위치 결정, mds 강요 X)
+- **`notificationStore`** — sessionStorage persist (새 session 시 자동 clear,
+  동일 session 의 dismiss state 유지)
+- **`useNotification()`** hook — items / unreadCount / push / markRead /
+  markAllRead / dismiss / clear
+- **Compound parts** — `Notification.Root` (store-bound list + header + auto
+  empty state)
+- **4 level** — info / success / warning / danger (axe-pass: `role="alert"` for
+  warning/danger, `role="status"` for info/success)
 
 ### Banner 와 차이
 
@@ -169,24 +183,25 @@ push({
 ### TBD (별도 cycle)
 
 - Server-side dismiss persistence (현재 = sessionStorage client only)
-- Sub-component 분리 export (`Notification.Header`, `Notification.Item`, `Notification.EmptyState`)
+- Sub-component 분리 export (`Notification.Header`, `Notification.Item`,
+  `Notification.EmptyState`)
 
 ---
 
 ## 6. Modal Dialog — 결정 강제 (overlay.md §5 참조)
 
-| Dialog | 사용 |
-|---|---|
+| Dialog          | 사용                                   |
+| --------------- | -------------------------------------- |
 | `Modal.confirm` | 위험 액션 ("정말 삭제?"), 영향 큰 결정 |
-| `Modal.alert` | 정보 알림 (응답 필수 — 그러나 OK 만) |
-| `Modal.prompt` | 단일 input + 응답 |
+| `Modal.alert`   | 정보 알림 (응답 필수 — 그러나 OK 만)   |
+| `Modal.prompt`  | 단일 input + 응답                      |
 
 ### Dialog vs Toast
 
-| 의도 | 채널 |
-|---|---|
-| 사용자 결정 받아야 진행 | **Dialog** |
-| 알림만 (사용자 응답 필요 X) | **Toast** |
+| 의도                        | 채널       |
+| --------------------------- | ---------- |
+| 사용자 결정 받아야 진행     | **Dialog** |
+| 알림만 (사용자 응답 필요 X) | **Toast**  |
 
 → Toast 로 "OK" 응답 받지 말 것. Dialog 가 정답.
 
@@ -194,39 +209,40 @@ push({
 
 ## 7. Mobile 변형
 
-| 채널 | Mobile 변형 |
-|---|---|
-| Toast | position = top-center (default top-right 대신) |
-| Banner | full-width, padding 줄임 |
-| Notification | top of viewport (sidebar inbox X) |
-| Dialog | 그대로 또는 bottom Sheet (Step 4.4 overlay) |
+| 채널         | Mobile 변형                                    |
+| ------------ | ---------------------------------------------- |
+| Toast        | position = top-center (default top-right 대신) |
+| Banner       | full-width, padding 줄임                       |
+| Notification | top of viewport (sidebar inbox X)              |
+| Dialog       | 그대로 또는 bottom Sheet (Step 4.4 overlay)    |
 
 ---
 
 ## 8. 안티 패턴
 
-- ❌ **Toast 로 "정말 삭제?"** — Toast 는 dismissible. 응답 못 받음. **Dialog 가 정답**
+- ❌ **Toast 로 "정말 삭제?"** — Toast 는 dismissible. 응답 못 받음. **Dialog 가
+  정답**
 - ❌ **Notification 으로 "저장됨"** — 영속 의도 아님. **Toast 가 정답**
 - ❌ **Banner 와 Toast 동일 메시지 동시** — 한 곳만
-- ❌ **Toast 5+ 동시** — 사용자 의식 한계. mds 의 stacking 제한 활용
+- ❌ **Toast 5+ 동시** — 사용자 인지 한계. mds 의 stacking 제한 활용
 - ❌ **Dialog 안 form (input multiple)** — `Modal.prompt` 또는 form Modal
 - ❌ **Banner 의 너무 긴 텍스트** (2 줄 이상) — collapse 또는 Modal 로
-- ❌ **영속 Notification 의 dismiss 없음** — 사용자 강제 닫기 가능해야 (a11y)
+- ❌ **영속 Notification 에 dismiss 없음** — 사용자가 직접 닫을 수 있어야 (a11y)
 
 ---
 
 ## 9. 일시 vs 영속 의사결정 매트릭스
 
-| 시나리오 | 일시 (Toast) | 영속 (Banner / Notification) |
-|---|---|---|
-| 저장 success | ✓ | — |
-| 서버 에러 (한번 발생) | ✓ | — |
-| 백그라운드 동기화 | ✓ | — |
-| 라이선스 만료 (전체 영향) | — | ✓ (Notification) |
-| 결제 카드 만료 (모든 페이지) | — | ✓ (Notification) |
-| 이 페이지 특정 상태 (예: 베타) | — | ✓ (Banner) |
-| 페이지 안 form 의 422 에러 요약 | — | ✓ (Banner) |
-| 시스템 점검 announce | — | ✓ (Banner solid) |
+| 시나리오                        | 일시 (Toast) | 영속 (Banner / Notification) |
+| ------------------------------- | ------------ | ---------------------------- |
+| 저장 success                    | ✓            | —                            |
+| 서버 에러 (한번 발생)           | ✓            | —                            |
+| 백그라운드 동기화               | ✓            | —                            |
+| 라이선스 만료 (전체 영향)       | —            | ✓ (Notification)             |
+| 결제 카드 만료 (모든 페이지)    | —            | ✓ (Notification)             |
+| 이 페이지 특정 상태 (예: 베타)  | —            | ✓ (Banner)                   |
+| 페이지 안 form 의 422 에러 요약 | —            | ✓ (Banner)                   |
+| 시스템 점검 announce            | —            | ✓ (Banner solid)             |
 
 > 핵심 — **놓치면 안 되는가** 가 영속 결정. Toast 는 놓쳐도 OK.
 
@@ -234,22 +250,24 @@ push({
 
 ## 10. Cross-cutting
 
-| Axis | 적용 |
-|---|---|
-| **Responsive** | Toast position 모바일 변환 / Banner full-width |
-| **A11y** | `role="status"` (success/info) / `role="alert"` (error/warning) / `aria-live="polite"` (info) / `assertive` (error) |
-| **Telemetry** | error toast / banner click 추적 (Step 7) |
-| **i18n** | 모든 메시지 `t()` 통과 |
-| **AI fill** | AI 가 form 채운 후 `<FormFillApprovalBanner>` (Banner 형태) — Step 4.8 |
+| Axis           | 적용                                                                                                                |
+| -------------- | ------------------------------------------------------------------------------------------------------------------- |
+| **Responsive** | Toast position 모바일 변환 / Banner full-width                                                                      |
+| **A11y**       | `role="status"` (success/info) / `role="alert"` (error/warning) / `aria-live="polite"` (info) / `assertive` (error) |
+| **Telemetry**  | error toast / banner click 추적 (Step 7)                                                                            |
+| **i18n**       | 모든 메시지 `t()` 통과                                                                                              |
+| **AI fill**    | AI 가 form 채운 후 `<FormFillApprovalBanner>` (Banner 형태) — Step 4.8                                              |
 
 ---
 
 ## 11. TBD
 
-1. **Notification 영속 컴포넌트 mds 추가** — design + mount 위치 + persistence (sessionStorage / 서버)
+1. **Notification 영속 컴포넌트 mds 추가** — design + mount 위치 + persistence
+   (sessionStorage / 서버)
 2. **Toast position mobile** — top-center default 자동 변환
 3. **Toast stacking 최대** — 현재 5 권장? 정확 결정
-4. **Dialog 외 영구 alert** (예: 시스템 maintenance) — `<Banner solid>` 또는 별도
+4. **Dialog 외 영구 alert** (예: 시스템 maintenance) — `<Banner solid>` 또는
+   별도
 5. **Notification 의 read/unread 상태** — inbox 패턴 (Slack 처럼) 필요 여부
 
 ---
@@ -258,5 +276,6 @@ push({
 
 - [form.md](./form.md) — Form 의 검증 에러 (Banner + Field.Error) (Step 4.1)
 - [overlay.md](./overlay.md) — Modal.confirm / alert / prompt (Step 4.4)
-- [async-states.md](./async-states.md) — Background loading 의 toast vs silent (Step 4.7)
+- [async-states.md](./async-states.md) — Background loading 의 toast vs silent
+  (Step 4.7)
 - [ai-fill.md](./ai-fill.md) — FormFillApprovalBanner (Step 4.8)