@hjmds/design-contracts 1.12.1 → 1.13.1

package/docs/usage/screens/flow-collection.md

@@ -0,0 +1,96 @@
+# 목록과 상세
+
+- 단계: 화면
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/기본 흐름/목록과 상세`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/화면/콘텐츠/목록과 상세`
+
+## 목적
+
+ListDetailScreen을 사용해 목록과 상세 흐름을 구성한다. 제품이 데이터·권한·서버 확정·문구를 공급하며, 예제의 메모리 저장을 운영 저장으로 취급하지 않는다.
+
+## 영역 구조
+
+```text
+host: 남은 높이·safe area·키보드
+└─ 목록 헤더 → 목록 → 더 보기 / 상세 헤더 → 상세
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | ListDetailScreen | route 본문 | [API 배치 규칙](../components/list-detail-screen.md#배치), host 남은 높이 |
+| 내용 | 공개 슬롯 | 목록 헤더 → 목록 → 더 보기 / 상세 헤더 → 상세 | 화면 recipe의 sectionGap·itemGap; 슬롯 안은 각 지침 토큰 |
+| 상태 | state 또는 해당 API 상태 | 본문 자리·비차단 notice | 입력 중 실패는 본문 높이와 초안을 유지 |
+
+## 버튼과 행동 위치
+
+| 행동 | 컴포넌트·tone | 위치 | 개수·순서 |
+| --- | --- | --- | --- |
+| 작업 | ListDetailScreen 공개 행동 슬롯 | 새로고침은 actions, 상세 뒤로는 leading | 같은 표면에 경쟁하는 primary 하나만 |
+| 복구 | Button·secondary | 오류 근처 | 재시도할 대상과 범위를 표시 |
+
+## 상태
+
+| 상태 | 화면 모습 | 행동 |
+| --- | --- | --- |
+| 기본 | 목록 헤더 → 목록 → 더 보기 / 상세 헤더 → 상세 | 각 공개 콜백을 제품 상태에 연결 |
+| 로딩 | 최초 조회는 본문 상태, 저장은 해당 행동 pending | 중복 제출 차단; 성공을 먼저 표시하지 않음 |
+| 빈 | 실제 조회 0건 또는 아직 작성하지 않은 상태 안내 | 시작·조건 해제 등 맥락에 맞는 대안 |
+| 오류 | 목록 pane 유지; 상세 실패는 detail.content 안에서 복구 | 실패 원인과 재시도 경로 제공 |
+
+## 사용하는 지침
+
+| 지침 | 쓰는 곳 |
+| --- | --- |
+| [ListDetailScreen](../components/list-detail-screen.md) | 필수 props·슬롯·플랫폼 차이 |
+| [Button](../components/button.md) | 동작·로딩·보조 행동 |
+| [ScreenLayout](../components/screen-layout.md) | 화면 높이·본문 교체·스크롤 소유 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { List } from "@hjmds/react/display";
+import { ListDetailScreen } from "@hjmds/react/screen-flows";
+
+<ListDetailScreen
+  title={t("orders.title")}
+  list={<List label={t("orders.list")}>{rows}</List>}
+  {...(selected ? { detail: { title: selected.name, content: <OrderDetail order={selected} /> } } : {})}
+  back={{ label: t("common.back"), onAction: () => setSelected(null) }}
+  refresh={{ label: t("common.refresh"), onAction: refetch, pending: isRefetching }}
+/>
+```
+
+```tsx
+// Native
+import { List } from "@hjmds/react-native/data-display";
+import { ListDetailScreen } from "@hjmds/react-native/screen-flows";
+
+<ListDetailScreen
+  title={t("orders.title")}
+  list={<List label={t("orders.list")}>{rows}</List>}
+  {...(selected ? { detail: { title: selected.name, content: <OrderDetail order={selected} /> } } : {})}
+  back={{ label: t("common.back"), onAction: () => setSelected(null) }}
+  refresh={{ label: t("common.refresh"), onAction: refetch, pending: isRefetching }}
+/>
+```
+
+콜백·데이터·지역화 함수는 제품에서 공급한다. Web·Native import와 필수 props는 위 API 지침에서 확인한다.
+
+## 큰 글자·다크·좁은 폭
+
+| 조건 | 바뀌는 것 |
+| --- | --- |
+| 큰 글자 | 2배 글자에서 제목·행은 내용 높이로 증가. footer·닫기·입력 필드가 겹치지 않는지 확인 |
+| 다크 | semantic 색으로 내용과 표면을 함께 전환; 예제 브랜드 색을 제품 기본값으로 복사하지 않음 |
+| 좁은 폭 | 320px부터 한 열로 읽기 순서 유지. 가상화 본문은 scroll=content, 중첩 스크롤 금지 |
+| 키보드 | Native host가 safe area와 키보드를 한 번 처리; Web은 포커스된 입력과 footer 가림 확인 |
+
+## 함정
+
+- 목록 pane 유지; 상세 실패는 detail.content 안에서 복구.
+- Storybook은 실제 서버·OS 권한·라우터 연동 증거가 아니다. 기본·다크·큰 글자와 실패/복구를 각각 확인한다.

package/docs/usage/screens/flow-editor.md

@@ -0,0 +1,120 @@
+# 작성과 수정
+
+- 단계: 화면
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/기본 흐름/작성과 수정`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/화면/콘텐츠/작성과 수정`
+
+## 목적
+
+EditorScreen을 사용해 작성과 수정 흐름을 구성한다. 제품이 데이터·권한·서버 확정·문구를 공급하며, 예제의 메모리 저장을 운영 저장으로 취급하지 않는다.
+
+## 영역 구조
+
+```text
+host: 남은 높이·safe area·키보드
+└─ 제목·취소 → 입력 → 저장
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | EditorScreen | route 본문 | [API 배치 규칙](../components/editor-screen.md#배치), host 남은 높이 |
+| 내용 | 공개 슬롯 | 제목·취소 → 입력 → 저장 | 화면 recipe의 sectionGap·itemGap; 슬롯 안은 각 지침 토큰 |
+| 상태 | state 또는 해당 API 상태 | 본문 자리·비차단 notice | 입력 중 실패는 본문 높이와 초안을 유지 |
+
+## 버튼과 행동 위치
+
+| 행동 | 컴포넌트·tone | 위치 | 개수·순서 |
+| --- | --- | --- | --- |
+| 작업 | EditorScreen 공개 행동 슬롯 | 취소는 헤더; 저장은 footer; 수정한 채 이탈하면 확인 | 같은 표면에 경쟁하는 primary 하나만 |
+| 복구 | Button·secondary | 오류 근처 | 재시도할 대상과 범위를 표시 |
+
+## 상태
+
+| 상태 | 화면 모습 | 행동 |
+| --- | --- | --- |
+| 기본 | 제목·취소 → 입력 → 저장 | 각 공개 콜백을 제품 상태에 연결 |
+| 로딩 | 최초 조회는 본문 상태, 저장은 해당 행동 pending | 중복 제출 차단; 성공을 먼저 표시하지 않음 |
+| 빈 | 실제 조회 0건 또는 아직 작성하지 않은 상태 안내 | 시작·조건 해제 등 맥락에 맞는 대안 |
+| 오류 | 저장 실패는 입력 유지; 저장 성공 확인 후에만 dirty 해제 | 실패 원인과 재시도 경로 제공 |
+
+## 사용하는 지침
+
+| 지침 | 쓰는 곳 |
+| --- | --- |
+| [EditorScreen](../components/editor-screen.md) | 필수 props·슬롯·플랫폼 차이 |
+| [Button](../components/button.md) | 동작·로딩·보조 행동 |
+| [ScreenLayout](../components/screen-layout.md) | 화면 높이·본문 교체·스크롤 소유 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { EditorScreen } from "@hjmds/react/screen-flows";
+import { Text } from "@hjmds/react/layout";
+import { TextField } from "@hjmds/react/forms";
+
+<EditorScreen
+  title={t("post.edit.title")}
+  dirty={draft !== saved}
+  submit={{ label: t("post.edit.save"), pending: saving, disabled: !draft.trim(), onAction: save }}
+  cancel={{ label: t("post.edit.close"), onAction: close }}
+  discard={{
+    mode: "confirm",
+    title: t("post.discard.title"),
+    description: t("post.discard.description"),
+    confirmLabel: t("post.discard.confirm"),
+    cancelLabel: t("post.discard.keep"),
+    tone: "danger",
+    fallbackErrorMessage: t("common.error"),
+  }}
+  draftStatus={<Text variant="caption" tone="muted">{t("post.edit.draftSaved")}</Text>}
+>
+  <TextField label={t("post.edit.body")} value={draft} onValueChange={setDraft} />
+</EditorScreen>
+```
+
+```tsx
+// Native
+import { EditorScreen } from "@hjmds/react-native/screen-flows";
+import { Text } from "@hjmds/react-native/primitives";
+import { TextField } from "@hjmds/react-native/inputs";
+
+<EditorScreen
+  title={t("post.edit.title")}
+  dirty={draft !== saved}
+  submit={{ label: t("post.edit.save"), pending: saving, disabled: !draft.trim(), onAction: save }}
+  cancel={{ label: t("post.edit.close"), onAction: close }}
+  discard={{
+    mode: "confirm",
+    title: t("post.discard.title"),
+    description: t("post.discard.description"),
+    confirmLabel: t("post.discard.confirm"),
+    cancelLabel: t("post.discard.keep"),
+    tone: "danger",
+    fallbackErrorMessage: t("common.error"),
+  }}
+  draftStatus={<Text variant="caption" tone="muted">{t("post.edit.draftSaved")}</Text>}
+>
+  <TextField label={t("post.edit.body")} value={draft} onValueChange={setDraft} />
+</EditorScreen>
+```
+
+콜백·데이터·지역화 함수는 제품에서 공급한다. Web·Native import와 필수 props는 위 API 지침에서 확인한다.
+
+## 큰 글자·다크·좁은 폭
+
+| 조건 | 바뀌는 것 |
+| --- | --- |
+| 큰 글자 | 2배 글자에서 제목·행은 내용 높이로 증가. footer·닫기·입력 필드가 겹치지 않는지 확인 |
+| 다크 | semantic 색으로 내용과 표면을 함께 전환; 예제 브랜드 색을 제품 기본값으로 복사하지 않음 |
+| 좁은 폭 | 320px부터 한 열로 읽기 순서 유지. 가상화 본문은 scroll=content, 중첩 스크롤 금지 |
+| 키보드 | Native host가 safe area와 키보드를 한 번 처리; Web은 포커스된 입력과 footer 가림 확인 |
+
+## 함정
+
+- 저장 실패는 입력 유지; 저장 성공 확인 후에만 dirty 해제.
+- Storybook은 실제 서버·OS 권한·라우터 연동 증거가 아니다. 기본·다크·큰 글자와 실패/복구를 각각 확인한다.

package/docs/usage/screens/flow-media.md

@@ -0,0 +1,111 @@
+# 사진 선택과 업로드
+
+- 단계: 화면
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/기본 흐름/사진 선택과 업로드`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/화면/콘텐츠/사진 선택과 업로드`
+
+## 목적
+
+MediaSelectionScreen을 사용해 사진 선택과 업로드 흐름을 구성한다. 제품이 데이터·권한·서버 확정·문구를 공급하며, 예제의 메모리 저장을 운영 저장으로 취급하지 않는다.
+
+## 영역 구조
+
+```text
+host: 남은 높이·safe area·키보드
+└─ 추가 → 썸네일 격자 → 선택 요약 → 완료
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | MediaSelectionScreen | route 본문 | [API 배치 규칙](../components/media-selection-screen.md#배치), host 남은 높이 |
+| 내용 | 공개 슬롯(`library`를 주면 기본 격자 대신 그것을 그린다) | 추가(헤더) → 썸네일 격자 → 선택 요약 → 완료(footer) | 기본 격자는 `Grid` 2열, `breakpoint.expanded` 960 이상 3열, 칸 사이 `spacing.md` 16. 칸 안은 미리보기 → UploadItem → 이동·제거 행(`spacing.xs` 8 세로, 버튼 사이 `spacing.xxs` 4) |
+| 상태 | state 또는 해당 API 상태 | 본문 자리·비차단 notice | 입력 중 실패는 본문 높이와 초안을 유지 |
+
+## 버튼과 행동 위치
+
+| 행동 | 컴포넌트·tone | 위치 | 개수·순서 |
+| --- | --- | --- | --- |
+| 작업 | `add` Button·secondary / `done` Button·primary / 항목 행동 Button·ghost·small | 추가는 헤더 actions, 완료는 footer(선택 요약 아래), 위로·아래로·제거는 각 칸 미리보기 아래 | primary는 완료 하나. 칸마다 위로 → 아래로 → 제거, 첫 칸의 위로·마지막 칸의 아래로는 비활성 |
+| 복구 | Button·secondary | 오류 근처 | 재시도할 대상과 범위를 표시 |
+
+## 상태
+
+| 상태 | 화면 모습 | 행동 |
+| --- | --- | --- |
+| 기본 | 추가 → 썸네일 격자 → 선택 요약 → 완료 | 각 공개 콜백을 제품 상태에 연결 |
+| 로딩 | 최초 조회는 본문 상태, 저장은 해당 행동 pending | 중복 제출 차단; 성공을 먼저 표시하지 않음 |
+| 빈 | 실제 조회 0건 또는 아직 작성하지 않은 상태 안내 | 시작·조건 해제 등 맥락에 맞는 대안 |
+| 오류 | 업로드 실패 항목만 재시도, 완료 버튼은 제품 정책으로 제한 | 실패 원인과 재시도 경로 제공 |
+
+## 사용하는 지침
+
+| 지침 | 쓰는 곳 |
+| --- | --- |
+| [MediaSelectionScreen](../components/media-selection-screen.md) | 필수 props·슬롯·플랫폼 차이 |
+| [Button](../components/button.md) | 동작·로딩·보조 행동 |
+| [ScreenLayout](../components/screen-layout.md) | 화면 높이·본문 교체·스크롤 소유 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { MediaSelectionScreen } from "@hjmds/react/screen-flows";
+
+<MediaSelectionScreen
+  title={t("media.title")}
+  items={picked.map((p) => ({ descriptor: { id: p.id, name: p.fileName, state: p.upload },
+    preview: <img src={p.uri} alt="" width={p.width} height={p.height} /> }))}
+  add={{ label: t("media.add"), onAction: openPicker }}
+  done={{ label: t("media.done"), onAction: submit, disabled: uploading }}
+  labels={{ pending: t("upload.pending"), uploading: t("upload.uploading"),
+    success: t("upload.success"), cancel: t("upload.cancel"), retry: t("upload.retry") }}
+  actionLabels={{ remove: t("media.remove"), moveUp: t("media.moveUp"), moveDown: t("media.moveDown") }}
+  removeLabel={(item) => t("media.removeNamed", { name: item.descriptor.name })}
+  moveUpLabel={(item) => t("media.moveUpNamed", { name: item.descriptor.name })}
+  moveDownLabel={(item) => t("media.moveDownNamed", { name: item.descriptor.name })}
+  onRemove={remove} onMove={(id, direction) => move(id, direction)}
+  onRetry={retryUpload} onCancel={cancelUpload}
+/>
+```
+
+```tsx
+// Native
+import { MediaSelectionScreen } from "@hjmds/react-native/screen-flows";
+import { Image } from "react-native";
+
+<MediaSelectionScreen
+  title={t("media.title")}
+  items={picked.map((p) => ({ descriptor: { id: p.id, name: p.fileName, state: p.upload },
+    preview: <Image src={p.uri} width={p.width} height={p.height} /> }))}
+  add={{ label: t("media.add"), onAction: openPicker }}
+  done={{ label: t("media.done"), onAction: submit, disabled: uploading }}
+  labels={{ pending: t("upload.pending"), uploading: t("upload.uploading"),
+    success: t("upload.success"), cancel: t("upload.cancel"), retry: t("upload.retry") }}
+  actionLabels={{ remove: t("media.remove"), moveUp: t("media.moveUp"), moveDown: t("media.moveDown") }}
+  removeLabel={(item) => t("media.removeNamed", { name: item.descriptor.name })}
+  moveUpLabel={(item) => t("media.moveUpNamed", { name: item.descriptor.name })}
+  moveDownLabel={(item) => t("media.moveDownNamed", { name: item.descriptor.name })}
+  onRemove={remove} onMove={(id, direction) => move(id, direction)}
+  onRetry={retryUpload} onCancel={cancelUpload}
+/>
+```
+
+콜백·데이터·지역화 함수는 제품에서 공급한다. Web·Native import와 필수 props는 위 API 지침에서 확인한다. 미리보기 이미지는 제품이 공급한다(Web `img`, Native `Image`).
+
+## 큰 글자·다크·좁은 폭
+
+| 조건 | 바뀌는 것 |
+| --- | --- |
+| 큰 글자 | 2배 글자에서 제목·행은 내용 높이로 증가. footer·닫기·입력 필드가 겹치지 않는지 확인 |
+| 다크 | semantic 색으로 내용과 표면을 함께 전환; 예제 브랜드 색을 제품 기본값으로 복사하지 않음 |
+| 좁은 폭 | 기본 격자는 `minColumnWidth` 없이 `columns={{ compact: 2, expanded: 3 }}`라 320px에서도 2열이다(한 열로 접지 않는다). 960 미만 2열, 이상 3열. 이동·제거 버튼 행은 줄바꿈된다. 한 열이 필요하면 `library` 슬롯으로 제품 격자를 넘긴다 |
+| 키보드 | Native host가 safe area와 키보드를 한 번 처리; Web은 포커스된 입력과 footer 가림 확인 |
+
+## 함정
+
+- 업로드 실패 항목만 재시도, 완료 버튼은 제품 정책으로 제한.
+- Storybook은 실제 서버·OS 권한·라우터 연동 증거가 아니다. 기본·다크·큰 글자와 실패/복구를 각각 확인한다.

package/docs/usage/screens/flow-moderation.md

@@ -0,0 +1,120 @@
+# 신고와 차단
+
+- 단계: 화면
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 조합](../../screen-patterns.md); 공통 API와 실제 Web·Native 예제의 슬롯·상태를 대조해 중복 조립 방지. 2026-10-06 사용자 승인으로 스토리북 배포(이전 `실험/화면/기본 흐름/신고와 차단`, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/화면/소통/신고와 차단`
+
+## 목적
+
+ModerationScreen을 사용해 신고와 차단 흐름을 구성한다. 제품이 데이터·권한·서버 확정·문구를 공급하며, 예제의 메모리 저장을 운영 저장으로 취급하지 않는다.
+
+## 영역 구조
+
+```text
+host: 남은 높이·safe area·키보드
+└─ 사유 선택 → 추가 설명 → 신고·차단
+```
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | ModerationScreen | route 본문 | [API 배치 규칙](../components/moderation-screen.md#배치), host 남은 높이 |
+| 내용 | 공개 슬롯 | 사유 선택 → 추가 설명 → 신고·차단 | 화면 recipe의 sectionGap·itemGap; 슬롯 안은 각 지침 토큰 |
+| 상태 | state 또는 해당 API 상태 | 본문 자리·비차단 notice | 입력 중 실패는 본문 높이와 초안을 유지 |
+
+## 버튼과 행동 위치
+
+| 행동 | 컴포넌트·tone | 위치 | 개수·순서 |
+| --- | --- | --- | --- |
+| 작업 | ModerationScreen 공개 행동 슬롯 | 신고는 footer; 차단은 별도 확인 후 실행 | 같은 표면에 경쟁하는 primary 하나만 |
+| 복구 | Button·secondary | 오류 근처 | 재시도할 대상과 범위를 표시 |
+
+## 상태
+
+| 상태 | 화면 모습 | 행동 |
+| --- | --- | --- |
+| 기본 | 사유 선택 → 추가 설명 → 신고·차단 | 각 공개 콜백을 제품 상태에 연결 |
+| 로딩 | 최초 조회는 본문 상태, 저장은 해당 행동 pending | 중복 제출 차단; 성공을 먼저 표시하지 않음 |
+| 빈 | 실제 조회 0건 또는 아직 작성하지 않은 상태 안내 | 시작·조건 해제 등 맥락에 맞는 대안 |
+| 오류 | 신고 실패에 선택 사유·설명 유지; 차단은 성공 후 확정 | 실패 원인과 재시도 경로 제공 |
+
+## 사용하는 지침
+
+| 지침 | 쓰는 곳 |
+| --- | --- |
+| [ModerationScreen](../components/moderation-screen.md) | 필수 props·슬롯·플랫폼 차이 |
+| [Button](../components/button.md) | 동작·로딩·보조 행동 |
+| [ScreenLayout](../components/screen-layout.md) | 화면 높이·본문 교체·스크롤 소유 |
+
+## 코드 골격
+
+```tsx
+// Web
+import { ModerationScreen } from "@hjmds/react/screen-flows";
+
+<ModerationScreen
+  title={t("report.title")}
+  reasonLabel={t("report.reason")}
+  reasons={[
+    { value: "spam", label: t("report.reason.spam") },
+    { value: "abuse", label: t("report.reason.abuse") },
+  ]}
+  reason={reason}
+  onReasonChange={setReason}
+  submit={{ label: t("report.submit"), onAction: submitReport, pending: reporting }}
+  block={{
+    action: { label: t("report.block"), onAction: () => {} },
+    confirmation: {
+      mode: "confirm", tone: "danger",
+      title: t("block.confirm.title"), description: t("block.confirm.body"),
+      confirmLabel: t("block.confirm"), cancelLabel: t("common.cancel"),
+      onConfirm: blockUser, fallbackErrorMessage: t("block.error"),
+    },
+  }}
+/>
+```
+
+```tsx
+// Native
+import { ModerationScreen } from "@hjmds/react-native/screen-flows";
+
+<ModerationScreen
+  title={t("report.title")}
+  reasonLabel={t("report.reason")}
+  reasons={[
+    { value: "spam", label: t("report.reason.spam") },
+    { value: "abuse", label: t("report.reason.abuse") },
+  ]}
+  reason={reason}
+  onReasonChange={setReason}
+  submit={{ label: t("report.submit"), onAction: submitReport, pending: reporting }}
+  block={{
+    action: { label: t("report.block"), onAction: () => {} },
+    confirmation: {
+      mode: "confirm", tone: "danger",
+      title: t("block.confirm.title"), description: t("block.confirm.body"),
+      confirmLabel: t("block.confirm"), cancelLabel: t("common.cancel"),
+      onConfirm: blockUser, fallbackErrorMessage: t("block.error"),
+    },
+  }}
+/>
+```
+
+콜백·데이터·지역화 함수는 제품에서 공급한다. Web·Native import와 필수 props는 위 API 지침에서 확인한다.
+
+## 큰 글자·다크·좁은 폭
+
+| 조건 | 바뀌는 것 |
+| --- | --- |
+| 큰 글자 | 2배 글자에서 제목·행은 내용 높이로 증가. footer·닫기·입력 필드가 겹치지 않는지 확인 |
+| 다크 | semantic 색으로 내용과 표면을 함께 전환; 예제 브랜드 색을 제품 기본값으로 복사하지 않음 |
+| 좁은 폭 | 320px부터 한 열로 읽기 순서 유지. 가상화 본문은 scroll=content, 중첩 스크롤 금지 |
+| 키보드 | Native host가 safe area와 키보드를 한 번 처리; Web은 포커스된 입력과 footer 가림 확인 |
+
+## 함정
+
+- 신고 실패에 선택 사유·설명 유지; 차단은 성공 후 확정.
+- Storybook은 실제 서버·OS 권한·라우터 연동 증거가 아니다. 기본·다크·큰 글자와 실패/복구를 각각 확인한다.

package/docs/usage/screens/flow-onboarding.md

@@ -0,0 +1,193 @@
+# 온보딩
+
+- 단계: 화면
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 조합](../../screen-patterns.md), Web·Native `src/screen-flows.tsx`(`OnboardingScreen`), 예제 `showcase/*/screen-flow-previews.tsx`(`OnboardingFlowPreview`)·`showcase/shared/onboarding-pattern.ts`(주제·요약). 2026-10-06 사용자 승인으로 실험 `기본 흐름/온보딩`(OnboardingScreen)을 배포하면서 같은 일을 직접 조립하던 배포 `화면/온보딩`을 대체했다(Web id `patterns-onboarding` 보존, [승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정))
+- 스토리북: `배포/화면/소개/온보딩`
+
+## 목적
+
+첫 실행 사용자를 몇 단계(소개 → 관심 주제 → 시작)로 안내하고 마지막 단계에서 완료를 저장하는 화면을 OnboardingScreen 하나로 구성한다.
+단계 제목·설명은 화면 머리, 진행 문구는 머리 아래, 이동 버튼은 footer에 고정하고 단계 본문만 바꾼다. 권한 요청·로그인·가입은
+이 화면에 없다([권한 안내](flow-permission.md), [로그인](common-login.md)).
+스토리는 `기본`(1단계부터 직접 넘기기), `관심 주제 고르기`(2단계를 바로 연 상태), `실패와 복구`(다음 완료 저장 실패 → 다시 시작하기)다.
+2026-10-06 배포 직접 조립 온보딩(Steps·ContentTransition·여러 개 고르는 주제 버튼)을 이 항목으로 합쳤고, 그 고유 상태인
+관심 주제 여러 개 고르기는 OnboardingScreen 2단계의 Chip 다중 선택으로 옮겼다(두 플랫폼 `관심 주제 고르기` 스토리가 같은 화면을 연다).
+단계·주제·문구·저장은 제품이 공급한다.
+
+## 영역 구조
+
+```text
+좁은 폭(Native·모바일 Web) — host가 남은 높이·safe area·키보드를 준다
+┌ OnboardingScreen = ScreenLayout(최대 720, 바깥 padding spacing.md 16) ┐
+│ 머리(고정)                                                          │
+│   단계 제목 (title)                         [건너뛰기] ← skip, ghost │
+│   단계 설명 (description)                                           │
+│ 진행 문구(고정 notice): "2 / 3"  Text caption muted                  │
+├──────────────────────────── 본문 스크롤 ──────────────────────────────┤
+│ 단계 content(제품)                                                  │
+│   1단계: 소개 그림 + 짧은 설명                                        │
+│   2단계: 관심 주제 [일상] [여행] [독서] [아이디어] ← Chip multiple, wrap │
+│   3단계: 고른 주제 요약                                               │
+│          (완료 저장 실패면) Notice danger + 다시 시도                   │
+├──────────────────────────── footer(고정, 위 테두리 1) ─────────────────┤
+│ [          다음 / 시작하기          ]  ← primary, 마지막 단계는 complete │
+│ [               이전                ]  ← ghost, 첫 단계에는 없음        │  사이 spacing.sm 12
+└ 아래 safe area(Web은 footer padding이 늘어난다) ──────────────────────┘
+```
+
+넓은 폭 Web도 한 열이다. ScreenLayout이 `layout.readingMaxWidth` 720으로 폭을 묶고 가운데 둔다.
+
+| 영역 | 컴포넌트 | 위치 | 크기·간격 |
+| --- | --- | --- | --- |
+| 바깥 틀 | OnboardingScreen(내부 ScreenLayout `scroll="screen"`) | route 본문. host가 남은 높이·safe area·키보드를 준다 | 폭 최대 720, 바깥 padding `spacing.md` 16([ScreenLayout 배치](../components/screen-layout.md#배치)). 화면 props는 `layoutStyle`만 받는다 |
+| 머리 | `steps[index].title`·`description` + `skip`(ghost Button) | 맨 위, 고정 | 제목 열 최소 120 × 글자 배율, 모자라면 건너뛰기가 다음 줄로 내려간다 |
+| 진행 문구 | `progressLabel(current, total)` → Text `variant="caption" tone="muted"` | 머리 아래 notice 자리, 고정 | 좌우 16 |
+| 단계 본문 | `steps[index].content` | 진행 문구 아래, 본문 스크롤 | 본문 안 간격은 제품 소유. 예제는 Stack `gap="lg"` 20 |
+| 관심 주제 | Stack `axis="inline" wrap gap="xs"`(Web `role="group"` + 이름) > [Chip](../components/chip.md) `selectionMode="multiple"` | 2단계 content 안 | 칩 높이 `small` 36(Native hitSlop으로 터치 44), 사이 `spacing.xs` 8 |
+| 저장 실패 | [Notice](../components/notice.md) `tone="danger"` + `action` | 마지막 단계 content 맨 아래 | 본문 Stack 간격을 따른다 |
+| footer | Stack `gap="sm"` > Button primary(다음·완료) → Button ghost(이전) | 맨 아래, 고정 | 사이 `spacing.sm` 12, 위 테두리 1 |
+
+## 버튼과 행동 위치
+
+| 행동 | 컴포넌트·tone | 위치 | 개수·순서 |
+| --- | --- | --- | --- |
+| 다음 | `nextLabel` → Button primary | footer 첫째 | 마지막 단계 전까지 1 |
+| 완료(시작하기) | `complete` → Button primary, `pending`이면 `loading`·비활성 | footer 첫째(마지막 단계) | 1. 저장 중 중복 실행을 막는다 |
+| 이전 | `backLabel` → Button ghost | footer 둘째 | 첫 단계에는 없다(숨김) |
+| 건너뛰기 | `skip` → Button ghost | 머리 끝(actions) | 선택. 1 |
+| 관심 주제 고르기 | Chip `selectionMode="multiple"`(checkbox 역할) | 2단계 본문 | 주제 수만큼, 여러 개 선택. 선택 상태는 제품이 든다 |
+| 다시 시도 | 실패 Notice `action` > Button `tone="secondary" size="small"` | 마지막 단계 본문 | 실패일 때만 1. footer의 완료를 다시 눌러도 같다 |
+| 파괴 행동 | — | — | 없음 |
+
+한 단계에 primary는 footer의 다음·완료 하나다. 진행·이동이 footer에 고정돼 단계 본문이 바뀌어도 버튼 자리가 흔들리지 않는다.
+
+2026-10-06 관심 주제를 ghost+`selected` Button에서 Chip `multiple`로 바꿨다. 여러 개 고르는 선택은 checkbox 역할로 읽혀야 하는데
+Button `selected`는 눌림 토글(`aria-pressed`)로 읽히고, 한 줄짜리 주제 선택에 CheckboxGroup은 세로 목록이라 화면을 많이 차지한다.
+
+## 상태
+
+| 상태 | 화면 모습 | 행동 |
+| --- | --- | --- |
+| 기본 | 1단계: 소개 그림·설명, 진행 "1 / 3", footer에 다음만(이전 없음), 머리 끝 건너뛰기 | 다음 · 건너뛰기 |
+| 관심 주제 고르기 | `관심 주제 고르기` 스토리: 2단계. 주제 칩을 눌러 켜고 끈다(여러 개, 처음엔 아무것도 고르지 않음). 고른 것이 없어도 다음으로 갈 수 있다 | 주제 토글 · 다음 · 이전 · 건너뛰기 |
+| 로딩 | 주제 목록을 서버에서 받으면 받는 동안 주제 줄 자리에 [Skeleton](../components/skeleton.md). 완료 저장 중에는 `complete.pending`으로 완료 버튼 `loading` | 기다림 |
+| 빈 | 주제를 하나도 고르지 않고 마지막 단계에 오면 요약 자리에 "관심 주제를 아직 선택하지 않았어요" 안내 | 이전 또는 시작하기 |
+| 오류 | 완료 저장 실패: 마지막 단계에 머물고 고른 주제는 그대로 둔다. 마지막 단계 본문에 Notice `danger`(Native `announcement="assertive"` — 기본 `none`). 다시 실패하면 같은 자리 Notice를 유지한다(쌓지 않는다) | 다시 시도 1 |
+| 실패와 복구 | `실패와 복구` 스토리: 다음 저장 실패를 예약한 뒤 시작하기 → 실패 문구 → 다시 시작하기로 완료 | 같은 완료 행동 |
+| 완료 | 제품이 온보딩을 닫고 홈으로 보낸다. 예제는 "시작할 준비가 됐어요" 화면과 다시 열기 | — |
+
+## 사용하는 지침
+
+| 지침 | 쓰는 곳 |
+| --- | --- |
+| [OnboardingScreen](../components/onboarding-screen.md) | 필수 props·단계 범위·플랫폼 차이 |
+| [ScreenLayout](../components/screen-layout.md) | 머리·notice·footer 고정, 본문 스크롤, 최대 폭 |
+| [Button](../components/button.md) | 다음·완료·이전·건너뛰기, 다시 시도 |
+| [Chip](../components/chip.md) | 관심 주제 여러 개 고르기 |
+| [Notice](../components/notice.md) | 완료 저장 실패 |
+| [Skeleton](../components/skeleton.md) | 주제 목록 로딩 |
+| [Stack](../components/stack.md) | 단계 본문 세로 리듬, 주제 줄 |
+| [Steps](../components/steps.md) | 단계 표시를 본문에 따로 그려야 할 때(OnboardingScreen은 진행 문구만 준다) |
+| [권한 안내](flow-permission.md) | 온보딩 뒤 권한을 묻는 화면 |
+
+## 코드 골격
+
+단계·주제·문구는 제품 소유다. 진행 문구는 보간 키 하나로 만들고 키 문자열을 조립하지 않는다.
+
+```tsx
+// Web
+import { OnboardingScreen } from "@hjmds/react/screen-flows";
+import { Stack } from "@hjmds/react/layout";
+import { Button } from "@hjmds/react/actions";
+import { Chip } from "@hjmds/react/selection";
+import { Notice } from "@hjmds/react/feedback";
+
+const topicPicker = <Stack role="group" aria-label={t("onboarding.topics.label")} axis="inline" wrap gap="xs">
+  {topics.map((topic) => <Chip key={topic.id} label={t(topic.labelKey)} selectionMode="multiple"
+    selected={chosen.includes(topic.id)} onSelectedChange={() => toggleTopic(topic.id)} />)}
+</Stack>;
+
+<OnboardingScreen
+  steps={[
+    { id: "welcome", title: t("onboarding.welcome.title"), description: t("onboarding.welcome.body"), content: welcomeArt },
+    { id: "topics", title: t("onboarding.topics.title"), description: t("onboarding.topics.body"), content: topicPicker },
+    { id: "ready", title: t("onboarding.ready.title"), description: t("onboarding.ready.body"), content: <Stack gap="lg">
+      {summary}
+      {failed ? <Notice tone="danger" title={t("onboarding.error")}
+        action={<Button tone="secondary" size="small" onClick={finish}>{t("common.retry")}</Button>} /> : null}
+    </Stack> },
+  ]}
+  index={index}
+  onIndexChange={setIndex}
+  nextLabel={t("common.next")}
+  backLabel={t("common.back")}
+  complete={{ label: t("onboarding.start"), onAction: finish, pending: saving }}
+  skip={{ label: t("common.skip"), onAction: finish }}
+  progressLabel={(current, total) => t("onboarding.progress", { current, total })}
+/>
+```
+
+```tsx
+// Native
+import { OnboardingScreen } from "@hjmds/react-native/screen-flows";
+import { Stack } from "@hjmds/react-native/primitives";
+import { Button } from "@hjmds/react-native/actions";
+import { Chip } from "@hjmds/react-native/inputs";
+import { Notice } from "@hjmds/react-native/feedback";
+
+const topicPicker = <Stack axis="inline" wrap gap="xs">
+  {topics.map((topic) => <Chip key={topic.id} label={t(topic.labelKey)} selectionMode="multiple"
+    selected={chosen.includes(topic.id)} onPress={() => toggleTopic(topic.id)} />)}
+</Stack>;
+
+<OnboardingScreen
+  steps={[
+    { id: "welcome", title: t("onboarding.welcome.title"), description: t("onboarding.welcome.body"), content: welcomeArt },
+    { id: "topics", title: t("onboarding.topics.title"), description: t("onboarding.topics.body"), content: topicPicker },
+    { id: "ready", title: t("onboarding.ready.title"), description: t("onboarding.ready.body"), content: <Stack gap="lg">
+      {summary}
+      {failed ? <Notice tone="danger" announcement="assertive" title={t("onboarding.error")}
+        action={<Button tone="secondary" size="small" onPress={finish}>{t("common.retry")}</Button>} /> : null}
+    </Stack> },
+  ]}
+  index={index}
+  onIndexChange={setIndex}
+  nextLabel={t("common.next")}
+  backLabel={t("common.back")}
+  complete={{ label: t("onboarding.start"), onAction: finish, pending: saving }}
+  skip={{ label: t("common.skip"), onAction: finish }}
+  progressLabel={(current, total) => t("onboarding.progress", { current, total })}
+/>
+```
+
+`finish`는 고른 주제와 완료 여부를 저장하고 성공하면 온보딩을 닫는다. 실패하면 `failed`를 켜고 `index`는 그대로 둔다.
+
+## 큰 글자·다크·좁은 폭
+
+| 조건 | 바뀌는 것 |
+| --- | --- |
+| 큰 글자(`textScale` 2) | 단계 제목이 줄바꿈되고 건너뛰기가 제목 아래 줄로 내려간다. 주제 줄은 여러 줄로 감긴다. footer는 고정이라 본문만 스크롤된다 |
+| 다크 | semantic token만 쓰므로 따로 처리하지 않는다. 소개 그림·브랜드 이미지는 제품이 다크용을 준비한다 |
+| 좁은 폭 | 320부터 한 열, 바깥 padding 16. footer 버튼은 세로로 쌓인다 |
+| 넓은 폭 Web | 한 열 유지, 최대 720 가운데 |
+| 키보드 | 단계 본문에 입력을 두면 Native host가 safe area와 키보드를 한 번 처리한다. Web은 포커스된 입력이 footer에 가리지 않는지 확인 |
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 이동 | `onClick` | `onPress` |
+| 저장 실패 발표 | Notice `danger`가 `role="alert"`로 읽힌다 | Notice `announcement="assertive"`를 줘야 읽힌다 |
+| 주제 칩 선택 콜백 | `onSelectedChange(next)` | `onPress(next, event)` |
+| 주제 묶음 이름 | Stack `role="group"` + `aria-label` | 칩마다 `label`로 읽힌다(묶음 역할 없음) |
+
+## 함정
+
+- `notice` 자리는 진행 문구가 차지한다. 저장 실패를 띄우려고 OnboardingScreen에 notice를 넘길 수 없으니 마지막 단계 `content`에 둔다.
+- 완료 `pending` 동안에도 이전 버튼은 막히지 않는다. 저장 중 단계 이동이 문제가 되면 `onIndexChange`에서 무시한다.
+- 현재 스토리의 진행 문구는 `` `${index} / ${total}` `` 고정 문자열이다. 제품은 보간 키 하나(`onboarding.progress`)를 쓴다.
+- Storybook은 실제 서버·라우터 연동 증거가 아니다. 기본·어두운 테마·큰 글자와 실패와 복구를 각각 확인한다.