@hjmds/design-contracts 1.26.1 → 1.27.1

package/docs/usage/components/media-transport.md

@@ -0,0 +1,104 @@
+# MediaTransport
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-16
+- 근거: [미디어 재생 제어 계약](../../media-transport.md), `src/media-transport.ts`의 `resolveMediaPlayback`·`mediaTransportPaths`, 양 renderer `src/media-transport.tsx`
+- 스토리북: `배포/구성/직접 조작과 모션/미디어 재생 제어`
+
+## 언제 쓰나
+
+제품의 실제 오디오·영상 엔진에 재생·일시 정지·유한 길이 탐색 제어를 붙일 때 쓴다.
+Lucian 007의 재생/정지 모핑을 실제 관측 상태와 연결하려고 IconButton과 Slider를 합성했다.
+버튼 모양과 위치는 엔진이 보고한 `state`만 따르며, 클릭으로 playing을 미리 바꾸지 않는다. 구성 배치는 [미디어 재생 제어 지침](../compositions/media-transport.md)에 있다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 모달 안 영상 표시 | [영상 미리보기](../compositions/video-dialog.md) 구성 |
+| 단순 아이콘 행동 | `IconButton` |
+| 일반 수치 입력 | `Slider` |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `MediaTransport` | 재생/일시 정지 모핑·시간·탐색 | `@hjmds/react/media-transport` | `@hjmds/react-native/media-transport` |
+
+`MediaPlaybackState`·`resolveMediaPlayback`은 `@hjmds/design-contracts/media-transport`에 있다. Native는 optional peer `react-native-svg`가 필요하다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { MediaTransport } from "@hjmds/react/media-transport";
+
+<MediaTransport state={observed /* video 이벤트에서 갱신 */}
+  onPlay={() => video.play()} onPause={() => video.pause()}
+  onSeek={seconds => seekAndWaitForSeeked(video, seconds)}
+  labels={{ play: t("media.play"), pause: t("media.pause"), seek: t("media.seek"), decrement: t("media.back"),
+    increment: t("media.forward"), unknownDuration: t("media.live"), error: t("media.failed") }}
+  formatTime={formatTime} active={visible} />
+```
+
+```tsx
+// Native
+import { MediaTransport } from "@hjmds/react-native/media-transport";
+
+<MediaTransport state={observed /* player 이벤트에서 갱신 */}
+  onPlay={() => player.play()} onPause={() => player.pause()}
+  onSeek={seconds => { player.currentTime = seconds; }}
+  labels={mediaLabels} formatTime={formatTime} active={isFocused} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| state | `{ playing, position, duration \| null, buffering? }` | 필수 | 엔진 관측값. 음수·비유한 값은 `RangeError` |
+| onPlay / onPause | () => void \| Promise | 필수 | 실제 엔진 호출. 실패는 reject |
+| onSeek | (seconds) => void \| Promise | 필수 | 실제 seek 확인 후 resolve. [0, duration]으로 제한해 호출 |
+| labels | play·pause·seek·decrement·increment·unknownDuration·error | 필수 | 현지화 문구 |
+| formatTime | (seconds) => string | 필수 | 시간 표시와 Slider 값 문구 |
+| disabled | boolean | false | 모든 제어 비활성 |
+| active | boolean | true | false면 제어·모핑 정지, 탐색 초안 폐기 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | IconButton(ghost) 안 글리프 24×24, Slider step 0.1초 | 양 renderer |
+| 간격 | 바깥 세로 md, 제어·시간 행 sm | 양 renderer |
+| 순서·정렬 | [재생/일시 정지 · 현재/전체 시간(caption)] 세로 중앙 → 탐색 Slider(길이를 알 때만) → 오류(가로 중앙) | 양 renderer |
+| 고정·스크롤 | 영상·오디오 host 아래, 바깥 host 소유 | 별도 scroller 없음 |
+| 좁은 폭·큰 글자 | Slider는 본문 폭, 제어 행은 줄바꿈 없음 | 양 renderer |
+
+## 꼭 지킬 것
+
+- `state`는 엔진 이벤트에서만 갱신한다. callback 성공만으로 playing을 바꾸지 않는다.
+- `duration: null`(라이브·미확인)이나 0이면 탐색 Slider가 사라진다. 알려진 양의 길이만 탐색한다.
+- 다른 미디어로 바꿀 때 host `key`를 바꾸고 이전 엔진을 해제한다. 숨길 때는 `active={false}`와 함께 엔진 pause를 제품이 실행한다.
+
+## 상태와 상호작용
+
+| 상태 | 모습 |
+| --- | --- |
+| 기본 | 실제 playing에 맞는 play/pause 모양과 이름, `playing`이면 selected |
+| 버퍼링 | 정지 상태에서만 버튼 로딩. 재생 중이면 일시 정지 가능 |
+| 요청 중 | 버튼 로딩, 탐색 잠금, 중복 요청 차단 |
+| 탐색 | 드래그·키 입력 중 값은 로컬 초안, 놓으면 `onSeek` 한 번. 끝나면 관측 위치로 복귀 |
+| 실패 | 관측 상태 유지, 중앙 오류, 같은 제어로 재시도 |
+
+모핑은 `motion.normal` 동안만 실행하고 reduced motion·비활성·백그라운드에서는 목표 모양으로 즉시 정착한다. 프레임마다 React 렌더를 하지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 글리프 | SVG `currentColor`, requestAnimationFrame으로 path만 변경 | react-native-svg `contentBrand`, Animated.Value listener로 path만 변경(`useNativeDriver: false`) |
+| 정지 조건 | `document.hidden` | `AppState`가 active 아님 |
+| 탐색 단계 문구 | `decrement`·`increment`를 Slider에 전달하지 않음 | Slider `decrementLabel`·`incrementLabel` |
+| 실패 알림 | `role="alert"` | `accessibilityRole="alert"`·assertive |

package/docs/usage/components/message-composer.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.17.1
-- 검토일: 2026-10-07
+- 검토일: 2026-10-17
 - 근거: [반복 화면 조합](../../screen-patterns.md), Web·Native `src/screens.tsx`·`src/screen-flows.tsx`; 기존 개별 지침을 새 규격으로 통합. 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
 - 스토리북: `배포/구성/입력과 작성/메시지 작성`, `배포/구성/입력과 작성/댓글 작성`, `배포/화면/소통/채팅`
 
@@ -106,6 +106,10 @@ import { Image } from "react-native";
 | 크기 | 입력 `composerMinLines` 1 ~ `composerMaxLines` 5줄(넘으면 입력 안에서 스크롤), `shape="large"`; 첨부 썸네일 `attachmentSize` 80(radius `radius.md`); 제거 버튼은 `IconButton size="small"` 36 + 사방 hit 4(실제 타깃 44), 그 안 보이는 원 `attachmentRemoveSize` 24; circle 전송은 `IconButton size="small"` 36 | `screen-patterns.ts`, `icon-button-recipe.ts` `sizes.small`, Web `styles.css`, Native `MessageComposer` |
 | 간격 | 세로 묶음(context·답장 대상·첨부·입력 줄) 사이와 입력–텍스트 전송 버튼 사이 `screenPatternRecipe.itemGap`(`spacing.sm` 12, 두 플랫폼. 2026-10-06까지 Web은 8, 1.13.0 변경); 답장 대상 줄·첨부 사이 `spacing.sm` 12; circle 전송은 입력 글자와 `spacing.sm` 12, 오른쪽 끝 8 | `screenPatternRecipe.itemGap`, Web `.hjm-message-composer`·`__row`(`--hjm-message-composer-gap`), Native `Stack gap="sm"`·`itemGap` |
 | 순서·정렬 | `context` → 답장 대상(작성자·발췌 → 취소) → 첨부 썸네일(→ 첨부 버튼) → 입력·전송 한 줄, 전송은 입력 아래쪽(`flex-end`)에 맞춘다. 입력 줄 안은 `leadingAction` → 글자 → (아이콘 모드) 전송/첨부 | 렌더 순서, Web `forms.tsx` `hjm-field__leading` |
+| 작성자 아바타 | 미게시: `leading`은 입력칸 밖, 입력 줄 시작 쪽에 놓는다(세로 가운데). 이모지 빠른 입력 줄은 그 위에서 작성창 전체 폭을 쓴다. 아바타를 작성창 바깥 Stack으로 감싸지 않는다 | Web `.hjm-message-composer__leading`, Native `MessageComposer` |
+| 이모지 빠른 입력 | 미게시: `quickInserts={ label, items: [{ id, emoji, label }] }`를 주면 입력 줄 위에 44 원형 칸(이모지 26)을 고르게 펼친다. 누르면 초안 끝에 이모지를 붙인다(인스타그램 댓글 시트 실측). 댓글처럼 길게 누르기 반응이 없는 화면에서 쓴다 | `composerQuickInsertRecipe` |
+| 높이 고정 | 미게시: 아이콘 전송 모드에서 전송 버튼 자리를 항상 확보(보이지 않고 보조기술에서도 숨김)해 첫 글자를 입력할 때 입력칸 높이가 바뀌지 않는다 | Web `.hjm-message-composer__trailing`, Native `MessageComposer` |
+| 답장 중 | 미게시: `replyTo`가 있으면 답장 대상(제목 굵게 + 원문 한 줄 말줄임 + 원형 × `IconButton size="small"` secondary)·첨부·입력 줄을 `surface` 배경, radius `radius.xl` 24, 안쪽 `spacing.sm` 12 카드 하나로 감싼다. `replyTo.author`에는 "소희에게 답장"처럼 완성된 문구를 넘긴다 | Web·Native `MessageComposer` |
 | 고정·스크롤 | 자체 고정 없음: 화면 composer 슬롯(footer)에 넣는다; 첨부는 가로 스크롤; 키보드 adapter는 host 하나만 | ChatScreen·CommentThreadScreen `composer` |
 | 좁은 폭·큰 글자 | 입력이 남은 폭을 채우고(`flex: 1`, 최소 폭 0) 전송 버튼은 줄지 않는다; 큰 글자에서도 5줄 상한 뒤 입력 안 스크롤로 기록을 가리지 않는다 | Web `.hjm-message-composer__row`, Native `layoutStyle={{ flex: 1 }}` |
 
@@ -116,7 +120,7 @@ import { Image } from "react-native";
 - 첨부 `id`는 비어 있지 않고 유일해야 하며 `removeLabel`이 필요하다. 첨부가 있으면 `onRemoveAttachment`가 필수다. 어기면 던진다.
 - 사진 권한·선택기·업로드·개수 제한은 제품 소유다. 출처 선택 UI는 [PhotoSourceSheet](photo-source-sheet.md)를 쓴다.
 - Enter는 기본 줄바꿈이다. 데스크톱 채팅만 `submitMode="send"`로 선택할 수 있고 Shift+Enter·IME 조합·Safari keyCode 229는 전송하지 않는다. Native는 별도로 선택하지 않으면 줄바꿈을 유지한다.
-- 2026-10-07 번뚝 채택에서 기존 blur/IME/검증 연결이 누락되어 이 공개 축을 추가했다. 제품이 내부 TextArea를 따로 조립하는 대안 대신 기존 MessageComposer 엔진을 확장한다.
+- 입력 연결(blur/IME/검증)이 더 필요하면 제품이 내부 TextArea를 따로 조립하지 않고 기존 MessageComposer 엔진의 공개 축을 확장한다.
 - 로컬 준비 사진은 `attachments`로 표시하며 UploadItem의 서버 업로드 완료로 가장하지 않는다. 준비 중 해당 항목의 `disabled`와 attachmentAction.disabled를 연결해 편집 가능한 본문과 사진 제거를 분리한다. 서버 성공 전 초안을 지우지 않는다.
 - Web 배치는 `layoutStyle`로 한다. Native는 스타일 통로가 없어 감싸는 레이아웃에서 배치한다.
 
@@ -132,4 +136,10 @@ import { Image } from "react-native";
 
 ### 고정 아이콘과 큰 글자
 
-2026-10-06 최근 검색 삭제 기호가 큰 글자에서 잘린 재현에 따라 Native 내장 삭제·메뉴 기호는 고정 아이콘 틀의 크기를 유지한다. 주변 제목·라벨은 계속 확대한다. Chip의 체크와 Toast 닫기는 기존 비확대 경로를 유지하며 회귀 검사에 포함한다. 제품이 전달한 아이콘 슬롯은 제품이 같은 조건을 검증한다.
+Native 내장 삭제·메뉴 기호는 고정 아이콘 틀의 크기를 유지한다. 주변 제목·라벨은 계속 확대한다. Chip의 체크와 Toast 닫기는 기존 비확대 경로를 유지하며 회귀 검사에 포함한다. 제품이 전달한 아이콘 슬롯은 제품이 같은 조건을 검증한다.
+
+## 근거
+
+- 답장 중 카드 배치: 2026-10-16 카카오톡 실측.
+- `submitMode` 등 입력 공개 축: 2026-10-07 번뚝 채택에서 기존 blur/IME/검증 연결이 누락됐다.
+- Native 내장 기호 고정 크기: 2026-10-06 최근 검색 삭제 기호가 큰 글자에서 잘리는 것을 재현했다.

package/docs/usage/components/moderation-screen.md

@@ -37,6 +37,7 @@ import { ModerationScreen } from "@hjmds/react/screen-flows";
 
 <ModerationScreen
   title={t("report.title")}
+  exit={{ kind: "close", label: t("common.close"), onClick: closeReport }}
   reasonLabel={t("report.reason")}
   reasons={[
     { value: "spam", label: t("report.reason.spam") },
@@ -63,6 +64,7 @@ import { ModerationScreen } from "@hjmds/react-native/screen-flows";
 
 <ModerationScreen
   title={t("report.title")}
+  exit={{ kind: "close", label: t("common.close"), onPress: closeReport }}
   reasonLabel={t("report.reason")}
   reasons={[
     { value: "spam", label: t("report.reason.spam") },
@@ -93,14 +95,14 @@ import { ModerationScreen } from "@hjmds/react-native/screen-flows";
 | `children` | 상세 설명 입력 등 추가 내용 |
 | `submit` | 신고 행동 `{ label, onAction, disabled?, pending? }` |
 | `block` | 차단 버튼 행동과 `AlertDialog` 확인 요청(`mode: "confirm"`) |
-| ScreenLayout props | `title`, `description`, `header`, `leading`, `actions`, `notice`, `state`, `stateAction` 등(`footer` 제외) |
+| ScreenLayout props | `title`, `description`, `exit`(push·모달로 여는 신고 화면의 닫기/뒤로, 헤더 시작 끝), `header`, `actions`, `notice`, `state`, `stateAction` 등(`footer` 제외) |
 
 ## 배치
 
 | 항목 | 값 | 근거 |
 | --- | --- | --- |
 | 크기 | ScreenLayout 폭(최대 720); 사유는 세로 `RadioGroup`, 신고·차단은 `Button` 기본 크기 | `ModerationScreen`, `screen-flows.tsx` `Action` |
-| 간격 | 화면 padding `spacing.md` 16; 본문 사유 선택–`children` `spacing.lg` 20; footer 신고–차단 `spacing.sm` 12 | Web·Native `ModerationScreen` `Stack gap="lg"`·`gap="sm"` |
+| 간격 | 화면 padding `spacing.md` 16; 본문 사유 선택–`children` `spacing.lg` 20; footer 신고–차단 `spacing.xs` 8(세로로 쌓은 버튼, `actionGroupRecipe.stackedGap`) | Web·Native `ModerationScreen` `Stack gap="lg"`·`gap="xs"` |
 | 순서·정렬 | 헤더(제목) → 본문(사유 → 추가 설명 `children`) → footer(신고 primary → 차단 ghost) | 렌더 순서 |
 | 고정·스크롤 | 헤더·footer 고정, 본문 화면 스크롤; 차단 확인은 AlertDialog 오버레이 | `ScreenLayout`, `AlertDialog` |
 | 좁은 폭·큰 글자 | 사유 문구는 줄바꿈되고 항목이 세로로 늘어난다; footer 버튼은 세로로 쌓여 좁은 폭에서도 나란히 줄지 않는다 | `RadioGroup orientation="vertical"`, `Stack` |
@@ -110,5 +112,6 @@ import { ModerationScreen } from "@hjmds/react-native/screen-flows";
 - 신고 버튼은 `reason`이 `reasons` 안의 값이 아니거나 `state`가 `ready`가 아니면 자동으로 막힌다. `reasonPicker`를 쓸 때도 `reasons`에 유효한 값을 넣어야 버튼이 열린다.
 - 차단 버튼의 `block.action.onAction`은 호출되지 않는다. 버튼은 확인 대화상자만 열고, 실제 차단은 `confirmation.onConfirm`에서 한다.
 - 서버 신고·권한·차단 mutation, 완료 후 이동은 제품 소유다. 사유 목록과 정책 문구도 제품이 정한다.
+- 신고 화면은 push·모달로 열리므로 `exit`로 나갈 길을 준다. 2026-10-17 화면 검토(S5)에서 exit 없는 예제가 나갈 수 없는 화면으로 렌더링됐다.
 - 확인 대화상자의 성공 후 닫힘·실패 문구는 [AlertDialog](alert-dialog.md) 계약을 따른다.
 - `block`을 제거하면 열린 확인 세션도 종료한다. 나중에 차단 행동을 다시 공급해도 사용자가 버튼을 새로 눌러야 확인창이 열린다. 2026-10-13 사라진 행동의 확인 상태가 부활하던 경로를 수정했다. 대상이 바뀌는 제품은 대상 id를 화면 key/초안·요청 수명에 함께 연결한다.

package/docs/usage/components/notification-inbox-screen.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.17.1
-- 검토일: 2026-10-06
+- 검토일: 2026-10-17
 - 근거: [반복 화면 조합](../../screen-patterns.md), Web·Native `src/screens.tsx`·`src/screen-flows.tsx`; 기존 개별 지침을 새 규격으로 통합. 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
 - 스토리북: `배포/화면/소통/알림함`
 
@@ -70,7 +70,7 @@ import { NotificationInboxScreen } from "@hjmds/react-native/screens";
 | `state` | `ready` · `loading` · `empty` · `error` · `restricted`. ready 외에는 지역화 `title` 필수 |
 | `stateAction` | 재시도·로그인 같은 실제 행동 |
 | `children` | 알림 목록(데이터·페이지 합치기·더 보기는 제품) |
-| `header`, `leading`, `actions` | 기존 내비게이션 헤더, 뒤로 가기, “모두 읽음” 같은 행동 |
+| `header`, `exit`, `actions` | 기존 내비게이션 헤더, 뒤로 가기 아이콘, “모두 읽음” 같은 행동 |
 
 ## 배치
 
@@ -78,7 +78,7 @@ import { NotificationInboxScreen } from "@hjmds/react-native/screens";
 | --- | --- | --- |
 | 크기 | ScreenLayout 폭(최대 720) 안에서 알림 행이 폭을 채운다 | `ScreenLayout`, `NotificationItem`(ListRow) |
 | 간격 | 화면 padding `spacing.md` 16(notice 영역은 좌우만); `notice`–`filters` `spacing.sm` 12; 행 사이 간격은 목록(제품) 소유 | Web·Native `NotificationInboxScreen` `Stack gap="sm"` |
-| 순서·정렬 | 헤더(`leading` → 제목 → `actions`) → `notice` → `filters` → 알림 목록 | 렌더 순서 |
+| 순서·정렬 | 헤더(`exit` → 제목 → `actions`) → `notice` → `filters` → 알림 목록 | 렌더 순서 |
 | 고정·스크롤 | `notice`·`filters`는 헤더 아래 고정되고 상태 교체 중에도 남는다; 목록은 기본 화면 스크롤(`scroll="screen"`), 가상화 목록이면 `scroll="content"` | `ScreenLayout` `notice`·`scroll` |
 | 좁은 폭·큰 글자 | 제목 열 최소 폭 120 × 글자 배율, 모자라면 `actions`(모두 읽음 등)가 다음 줄로 내려간다; 필터 줄바꿈·가로 스크롤은 `filters` 소유 | `screenPatternRecipe.headerMinWidth` |
 

package/docs/usage/components/notification-row.md

@@ -1,27 +1,83 @@
 # NotificationRow
 
-- 단계: 구성
-- 상태: 후보
+- 단계: 컴포넌트
+- 상태: 실험
 - 지원: Web · Native
-- 근거: [알림 화면](../screens/common-inbox.md)
+- 적용: 1.26.0
+- 검토일: 2026-10-16
+- 근거: [알림 화면](../screens/common-inbox.md), `src/screen-patterns.ts`의 `notificationRowRecipe`, 양 renderer `src/screens.tsx`
+- 스토리북: 별도 예제 미등록
 
 ## 언제 쓰나
+
 알림 목록에서 아바타, 유형 배지, 미리보기, 시간, 읽지 않음 표시, 선택적 썸네일을 나란히 배치한다. 2026-10-15 소비 앱이 같은 알림 배치를 각각 복제한 원인을 공통 구현에서 해결했다.
 
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 대화 목록 미리보기 | [ConversationRow](conversation-row.md) |
+| 일반 설정·목록 행 | [ListRow](list-row.md) |
+| 알림 화면 전체 틀 | [NotificationInboxScreen](notification-inbox-screen.md) |
+
 ## 공개 이름과 import
-Web은 `@hjmds/react/screens`, Native는 `@hjmds/react-native/screens`의 `NotificationRow`를 사용한다.
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `NotificationRow` | 알림 한 행 표시 | `@hjmds/react/screens` | `@hjmds/react-native/screens` |
 
 ## 최소 사용 예
+
 ```tsx
 // Web
 import { NotificationRow } from '@hjmds/react/screens';
-<NotificationRow avatar={avatar} preview={message} metadata={timeLabel} unread={unread} />
+<Link href={destination} aria-label={accessibleSummary}>
+  <NotificationRow avatar={avatar} preview={message} metadata={timeLabel} unread={unread} />
+</Link>
 ```
+
 ```tsx
 // Native
 import { NotificationRow } from '@hjmds/react-native/screens';
-<NotificationRow avatar={avatar} preview={message} metadata={timeLabel} unread={unread} />
+<Pressable accessibilityRole="link" accessibilityLabel={accessibleSummary} onPress={openNotification}>
+  <NotificationRow avatar={avatar} preview={message} metadata={timeLabel} unread={unread} />
+</Pressable>
 ```
 
-## 배치와 소유권
-HJM이 44px 아바타·썸네일, 20px 유형 배지, 2줄 미리보기와 간격을 소유한다. `avatarBadge`·`thumbnail`은 선택 슬롯이다. 제품은 바깥 링크/Pressable 하나에서 이동, disabled, 전체 접근성 이름을 연결한다. 내부는 장식 표현이므로 별도 클릭 대상을 넣지 않는다. `preview`는 인라인 텍스트 콘텐츠다.
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| avatar | ReactNode | 필수 | 행위자 아바타(원형으로 잘림) |
+| preview | ReactNode | 필수 | 인라인 텍스트 콘텐츠. 상호작용 요소를 넣지 않는다 |
+| metadata | string | 필수 | 현지화된 시간 |
+| avatarBadge | ReactNode | 없음 | 아바타 오른쪽 아래 유형 배지 |
+| thumbnail | ReactNode | 없음 | 대상 썸네일 |
+| unread | boolean | false | 시간 옆 읽지 않음 점 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 아바타·썸네일 44, 유형 배지 20, 읽지 않음 점 6 | `notificationRowRecipe` |
+| 간격 | 가로 gap 12, 내용 gap 4, 안쪽 여백 세로 12 · 가로 16 | 같은 recipe |
+| 순서·정렬 | 아바타(+배지) → 미리보기 / 시간·읽지 않음 점 → 썸네일, 세로 가운데 | 양 renderer |
+| 고정·스크롤 | 바깥 목록 host 소유 | 별도 scroller 없음 |
+| 좁은 폭·큰 글자 | 미리보기 최대 2줄 말줄임, 아바타·썸네일은 줄지 않는다 | `previewLines: 2`, `flexShrink: 0` |
+
+HJM이 44px 아바타·썸네일, 20px 유형 배지, 2줄 미리보기와 간격을 소유한다. `avatarBadge`·`thumbnail`은 선택 슬롯이다. 앱은 별도 행 padding을 넣지 않는다.
+
+## 꼭 지킬 것
+
+제품은 바깥 링크/Pressable 하나에서 이동, disabled, 전체 접근성 이름을 연결한다. 내부는 장식 표현이므로 별도 클릭 대상을 넣지 않는다. `preview`는 인라인 텍스트 콘텐츠다. HJM 내부 색·간격을 제품 CSS로 덮지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 낭독 숨김 | 루트 `aria-hidden="true"` | `accessibilityElementsHidden`, `importantForAccessibility="no-hide-descendants"` |
+| 미리보기 줄 수 | `-webkit-line-clamp: 2` | `numberOfLines={2}` |
+
+## 관련 지침
+
+[알림 화면](../screens/common-inbox.md), [ConversationRow](conversation-row.md), [ListRow](list-row.md).

package/docs/usage/components/onboarding-screen.md

@@ -93,7 +93,7 @@ import { OnboardingScreen } from "@hjmds/react-native/screen-flows";
 | 항목 | 값 | 근거 |
 | --- | --- | --- |
 | 크기 | ScreenLayout의 기본 최대 폭 720; 다음·완료·이전은 `Button` 기본 크기 | `screenPatternRecipe.maxWidth` |
-| 간격 | 기본 화면 padding `spacing.md` 16; footer 다음/완료–이전 `spacing.sm` 12; Native 본문 제목·설명·진행·건너뛰기·content 사이 `spacing.md` 16. 단계 content 내부 간격은 제품 소유 | ScreenLayout·양 renderer OnboardingScreen |
+| 간격 | 기본 화면 padding `spacing.md` 16; footer 다음/완료–이전 `spacing.xs` 8(세로로 쌓은 버튼, `actionGroupRecipe.stackedGap`); Native 본문 제목·설명·진행·건너뛰기·content 사이 `spacing.md` 16. 단계 content 내부 간격은 제품 소유 | ScreenLayout·양 renderer OnboardingScreen |
 | 순서·정렬 | Web: 헤더(제목·설명 → 건너뛰기) → 진행 문구 → content. Native: 본문(제목 → 설명 → 진행 문구 → 건너뛰기 → content). 둘 다 footer는 다음 또는 완료 → 이전, 첫 단계는 이전 없음 | 실제 렌더 순서 |
 | 고정·스크롤 | Web은 헤더·진행 문구·footer가 본문 스크롤 밖. Native는 제목·설명·진행·건너뛰기·content가 함께 스크롤하고 footer만 고정 | Native의 빈 header·기본 scroll="screen" |
 | 좁은 폭·큰 글자 | Web 헤더 제목 열은 최소 폭 120 × 글자 배율이며 actions가 줄바꿈한다. Native는 본문 세로 Stack을 사용한다. 둘 다 footer 버튼은 세로로 쌓인다 | ScreenLayout·OnboardingScreen |

package/docs/usage/components/overview-screen.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.15.0
-- 검토일: 2026-10-08
+- 검토일: 2026-10-17
 - 근거: [디자인 프로필](../../design-profile.md), 양 renderer `src/design-profile.tsx`; 기존 ScreenLayout·Grid·Collapsible의 상태 엔진을 재사용한다.
 - 스토리북: `배포/컴포넌트/레이아웃/목록 화면 골격`
 
@@ -63,13 +63,19 @@ import { OverviewScreen } from "@hjmds/react-native/design-profile";
 | 항목 | 값 | 근거 |
 | --- | --- | --- |
 | 크기 | editorial은 `layout.readingMaxWidth` 720, dashboard·landscape는 `layout.contentMaxWidth` 1200, host가 높이를 제공한다 | `resolveDesignProfileScreen`, ScreenLayout |
-| 간격 | 도구–목록 `spacing.xl` 24, rows `spacing.sm` 12, cards/grid `spacing.lg` 20, 카드 내부 rows `spacing.md` 16 / 나머지 `spacing.xl` 24 | OverviewScreen·공유 collection resolver |
+| 본문 폭 | 도구와 목록이 한 열: 최대 `layout.readingMaxWidth` 720, header 제목·BottomCTA 내용과 같은 가운데 축(`overviewContentLayout`). 카드 끝과 입력 끝이 같은 선에 놓인다 | `@hjmds/design-contracts/design-profile-layout` |
+| 간격·항목 | 도구–목록 `spacing.xl` 24. rows는 테두리 없는 항목을 규칙선(Divider, `border`)으로 나누고 선 위아래 `spacing.md` 16, 안쪽 여백 0. cards/grid는 테두리·raised 카드, 간격 `spacing.lg` 20, 안쪽 `spacing.xl` 24 | `resolveDesignProfileCollection`·`resolveDesignProfileCollectionItem` |
 | 순서·정렬 | 헤더 → notice → 도구 → 목록 → footer. leading은 뒤로, actions는 화면 도구, footer는 주 행동 | ScreenLayout 슬롯 |
 | 고정·스크롤 | 헤더·notice·footer 고정, 본문 스크롤. 가상 목록은 별도 ScreenLayout + `scroll="content"` | ScreenLayout 상태·스크롤 엔진 |
-| 좁은 폭·큰 글자 | rows 1/1/1, cards 1/2/2, grid 1/2/3(compact/medium/expanded). 최소 열 폭 240이며 실제 컨테이너·글자 배율로 열 수를 줄인다 | `resolveDesignProfileCollection`·Grid |
+| 좁은 폭·큰 글자 | rows 1/1/1, cards 1/2/2, grid 1/2/3(compact/medium/expanded). 최소 열 폭 226(720 열에 grid 3열과 간격 2개가 들어가는 값)이며 실제 컨테이너·글자 배율로 열 수를 줄인다 | `resolveDesignProfileCollection`·Grid |
 
 `collection`, `toolbarPresentation`, `presentation` 명시값이 프로필을 이긴다. 작은 화면의 열 수는 늘리지 않는다. virtual list는 이 정적 items 목록 대신 기존 ScreenLayout의 `scroll="content"`와 제품 list를 쓴다.
 
 ## 꼭 지킬 것
 
 ScreenLayout의 ready/loading/empty/error와 stateAction을 그대로 사용한다. 초기 조회 오류만 본문을 교체하고 저장 실패는 notice로 알린다. stable id가 중복되거나 비어 있으면 거부한다. 도구를 닫으면 입력 상태는 유지하되 접근성·포커스 대상에서 제외한다. 제품이 서버 확정·재시도·동시 저장 방지를 소유한다. 프로필은 같은 아이템의 입력 subtree를 갈아 끼우지 않는다.
+
+## 근거
+
+- 2026-10-17 구성 리뷰: dashboard 표현에서 도구만 왼쪽 반폭에 붙어 가운데 header·footer와 정렬 축이 섞였다.
+- 2026-10-17 사용자 검토: 도구만 읽기 폭이고 목록은 화면 폭이라 카드 행이 입력보다 넓어 좌우 끝이 어긋났다(1024px에서 카드 48–976, 입력 152–872). 도구와 목록을 한 열로 묶고, 그 열에서 grid 3열이 실제로 나오도록 최소 열 폭을 열 폭에서 유도했다. rows는 작은 테두리 상자를 쌓아 cards와 구분되지 않았고 에디토리얼의 규칙선을 표현할 수 없어 규칙선 목록으로 바꿨다. 항목 host(Surface)는 모든 구성에서 같아 테마를 바꿔도 항목 내용이 다시 마운트되지 않는다.

package/docs/usage/components/pagination.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web · Native
 - 적용: 1.12.1
-- 검토일: 2026-10-15
+- 검토일: 2026-10-16
 - 근거: [Pagination](../../pagination.md), `src/pagination.ts`(`paginationRecipe`)
 - 스토리북: `배포/컴포넌트/탐색/페이지 이동`
 
@@ -46,9 +46,24 @@ import { Pagination } from "@hjmds/react/pagination";
 />
 ```
 
-Native는 같은 props로 `@hjmds/react-native/pagination`에서 가져온다. 조회 중에는 `disabled`로 이전·번호·다음 행동을 함께 잠근다. `testID`는 탐색 묶음에 붙는다.
+```tsx
+// Native
+import { Pagination } from "@hjmds/react-native/pagination";
+
+<Pagination
+  label={t("records.pagination")}
+  descriptor={{ currentPage: page, totalCount: total, pageSize: 20 }}
+  labels={{ previous: t("pagination.previous"), next: t("pagination.next") }}
+  composeAccessibleName={({ page, totalPages, current }) =>
+    t(current ? "pagination.current" : "pagination.goTo", { page, totalPages })}
+  onPageChange={(next) => setPage(next)}
+  disabled={isFetching}
+/>
+```
+
+Native는 같은 props를 받는다. 조회 중에는 `disabled`로 이전·번호·다음 행동을 함께 잠근다. `testID`는 탐색 묶음에 붙는다.
 
-2026-10-15 다에리의 유한 편지 목록에서 페이지 번호가 이미 제품 기능이었으나 renderer 부재로 공통 배치를 복제한 원인을 수정했다. Native renderer는 다음 게시본부터 제공하며 현재 후보 상태다.
+2026-10-15 다에리의 유한 편지 목록에서 페이지 번호가 이미 제품 기능이었으나 renderer 부재로 공통 배치를 복제한 원인을 수정했다. Native renderer는 1.26.0부터 게시본에 포함된다.
 
 ## 축과 기본값
 

package/docs/usage/components/password-rules-field.md

@@ -0,0 +1,90 @@
+# PasswordRulesField
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-16
+- 근거: [작업 선택 계약](../../task-controls.md), `src/task-controls.ts`의 `resolvePasswordRules`, 양 renderer `src/task-controls.tsx`
+- 스토리북: `배포/구성/입력과 작성/비밀번호 규칙 확인`
+
+## 언제 쓰나
+
+새 비밀번호 입력 아래에 제품이 정한 규칙의 충족 개수와 규칙별 상태를 함께 보여 줄 때 쓴다.
+[PasswordField](password-field.md)에 진행 막대와 규칙 목록을 붙인 구성이며, 충족 개수만 센다.
+비밀번호 보안 강도(entropy)는 추정하지 않는다. 묶음 사용 기준은 [선택과 실제 실행](../compositions/task-controls.md)이다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 로그인처럼 규칙 표시가 없는 비밀번호 입력 | [PasswordField](password-field.md) |
+| 일반 텍스트 입력 | `TextField`([Field](field.md)) |
+| 보안 강도 점수 표시 | 제품 전용 구성(HJM은 강도를 계산하지 않는다) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `PasswordRulesField` | 비밀번호 입력 + 규칙 충족 막대·목록 | `@hjmds/react/task-controls` | `@hjmds/react-native/task-controls` |
+
+루트 barrel에는 없다. 규칙 타입 `PasswordRule`과 `resolvePasswordRules`는 `@hjmds/design-contracts/task-controls`에 있다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { PasswordRulesField } from "@hjmds/react/task-controls";
+
+<PasswordRulesField label={t("password.new")} value={password} onValueChange={setPassword}
+  autofillHint="new" revealLabel={t("password.reveal")} concealLabel={t("password.conceal")}
+  progressLabel={t("password.rules")}
+  summaryLabel={(satisfied, total) => t("password.summary", { satisfied, total })}
+  ruleLabel={rule => t(rule.satisfied ? "password.met" : "password.unmet", { rule: rule.label })}
+  rules={[{ id: "length", label: t("password.length"), test: v => v.length >= 8 }]} />
+```
+
+```tsx
+// Native
+import { PasswordRulesField } from "@hjmds/react-native/task-controls";
+
+<PasswordRulesField label={t("password.new")} value={password} onValueChange={setPassword}
+  autofillHint="new" revealLabel={t("password.reveal")} concealLabel={t("password.conceal")}
+  progressLabel={t("password.rules")}
+  summaryLabel={(satisfied, total) => t("password.summary", { satisfied, total })}
+  ruleLabel={rule => t(rule.satisfied ? "password.met" : "password.unmet", { rule: rule.label })}
+  rules={rules} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | `string` | 필수 | 입력 이름 |
+| `value` / `onValueChange` | `string` / `(value) => void` | 필수 | controlled 전용. `defaultValue`는 받지 않는다 |
+| `rules` | `{ id, label, test(value) }[]` | 필수 | 비어 있거나 id가 겹치면 `TypeError`(`resolvePasswordRules`) |
+| `progressLabel` | `string` | 필수 | 진행 막대 이름 |
+| `summaryLabel` | `(satisfied, total) => string` | 필수 | 막대의 값 문구(`valueText`) |
+| `ruleLabel` | `(rule: { id, label, satisfied }) => string` | 필수 | 규칙 한 줄 문구. 충족 여부를 글자로 포함한다 |
+| 나머지 | `PasswordFieldProps` | — | `autofillHint`·`revealLabel`·`concealLabel`·`description`·`error` 등은 [PasswordField](password-field.md)로 그대로 전달 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 입력은 PasswordField 기본, 막대는 Progress 기본(`max`=규칙 수) | 양 renderer `PasswordRulesField` |
+| 간격 | 입력·막대·규칙 줄 사이 `Stack gap="sm"`(12) | 같은 구현, `foundations.ts` space.sm |
+| 순서·정렬 | 비밀번호 입력 → 충족 막대 → 규칙별 caption(`rules` 순서) | 렌더 순서 |
+| 고정·스크롤 | 자체 고정·스크롤 없음, 바깥 폼 host 소유 | 별도 scroller 없음 |
+| 좁은 폭·큰 글자 | 규칙 문구는 caption Text로 줄바꿈된다 | 양 renderer `Text variant="caption"` |
+
+## 꼭 지킬 것
+
+- 충족 개수를 "보안 강도"라고 부르지 않는다. 규칙 `test`는 순수 함수이고 예외를 던지지 않게 만든다.
+- 충족 여부는 색(`primary`/`muted`)만으로 구분하지 않는다. `ruleLabel`이 "충족/미충족"을 글자로 말해야 한다.
+- 제출 가능 여부·서버 검증은 제품이 결정한다. 이 구성은 제출을 막지 않는다.
+
+## 상태와 상호작용
+
+입력이 바뀔 때마다 `resolvePasswordRules(value, rules)`로 다시 센다. 충족한 규칙은 `tone="primary"`, 미충족은 `tone="muted"`로 표시한다.
+보이기/숨기기와 자동 채움은 PasswordField 계약을 따른다.

package/docs/usage/components/permission-screen.md

@@ -94,7 +94,7 @@ import { Linking } from "react-native";
 | 항목 | 값 | 근거 |
 | --- | --- | --- |
 | 크기 | ScreenLayout 폭(최대 720); 그림 크기는 `illustration`(제품) 소유; 행동은 `Button` 기본 크기 | `PermissionScreen` |
-| 간격 | 화면 padding `spacing.md` 16; 본문 그림–설명 `spacing.xl` 24(가운데 정렬); footer 주 행동–나중에 `spacing.sm` 12 | Web·Native `PermissionScreen` `Stack gap="xl" align="center"`·`gap="sm"` |
+| 간격 | 화면 padding `spacing.md` 16; 본문 그림–설명 `spacing.xl` 24(가운데 정렬); footer 주 행동–나중에 `spacing.xs` 8(세로로 쌓은 버튼, `actionGroupRecipe.stackedGap`) | Web·Native `PermissionScreen` `Stack gap="xl" align="center"`·`gap="xs"` |
 | 순서·정렬 | 헤더(제목) → 본문(그림 → 설명, 가운데) → footer(상태별 주 행동 primary → 나중에 ghost) | 렌더 순서, `resolvePermissionAction` |
 | 고정·스크롤 | 헤더·footer 고정, 본문 화면 스크롤; OS 권한 창은 제품이 `request.onAction`에서 호출 | `ScreenLayout` |
 | 좁은 폭·큰 글자 | 설명은 줄바꿈되고 본문이 스크롤된다; footer 버튼은 세로로 쌓인다; `unavailable`이면 주 행동 없이 `skip`만 남는다 | `PermissionScreen` |

package/docs/usage/components/photo-source-sheet.md

@@ -94,7 +94,7 @@ import { PhotoSourceSheet } from "@hjmds/react-native/screen-flows";
 | 항목 | 값 | 근거 |
 | --- | --- | --- |
 | 크기 | Sheet 기본 `placement="bottom"`·`size="auto"`(내용 높이, 화면 높이 0.9 상한), Web 최대 폭 640; 선택 버튼은 `tone="secondary"` `Button` 두 개 | `sheetRecipe`, `screen-flows.tsx` |
-| 간격 | 시트 안 여백은 Sheet 소유(두 플랫폼 좌우 `spacing.lg` 20 · 위아래 `spacing.sm` 12 + 하단 safe area); 두 버튼 사이 `spacing.sm` 12; 바깥에 padding을 더하지 않는다 | Web `.hjm-sheet__body`, Native `sheetRecipe.content`, `Stack gap="sm"` |
+| 간격 | 시트 안 여백은 Sheet 소유(두 플랫폼 좌우 `spacing.lg` 20 · 위아래 `spacing.sm` 12 + 하단 safe area); 두 버튼 사이 `spacing.xs` 8(세로로 쌓은 버튼, `actionGroupRecipe.stackedGap`); 바깥에 padding을 더하지 않는다 | Web `.hjm-sheet__body`, Native `sheetRecipe.content`, `Stack gap="xs"` |
 | 순서·정렬 | Sheet 제목·닫기 → 앨범 → 촬영(`cameraAvailable`일 때만) | Web `screen-flows.tsx` 59–60행, Native 50–51행 |
 | 고정·스크롤 | 화면 하단에 뜨는 오버레이(배경 막) — 선택 뒤 picker 호출 시점은 플랫폼 차이 참고 | `Sheet` |
 | 좁은 폭·큰 글자 | 버튼 문구는 줄바꿈되고 Sheet 높이가 늘어난다(0.9 상한을 넘으면 본문 스크롤); 카메라가 없으면 버튼 하나만 남는다 | `sheetRecipe.content.maxHeightRatio` |

package/docs/usage/components/popover.md

@@ -4,7 +4,7 @@
 - 상태: 배포
 - 지원: Web
 - 적용: 1.12.1
-- 검토일: 2026-10-07
+- 검토일: 2026-10-17
 - 근거: [Popover](../../popover.md), [ConfirmPopover 조합](../../confirm-popover.md), `src/popover.ts`(`popoverRecipe`)
 - 스토리북: `배포/컴포넌트/오버레이/팝오버`
 
@@ -33,13 +33,15 @@
 
 ```tsx
 // Web
-import { Button } from "@hjmds/react/actions";
+import { IconButton } from "@hjmds/react/actions";
+import { Icon } from "@hjmds/react/display";
 import { Popover } from "@hjmds/react/popover";
 
 <Popover
-  trigger={<Button tone="secondary">{t("filter.open")}</Button>}
+  trigger={<IconButton label={t("filter.open")} tone="secondary"><Icon name="filter" /></IconButton>}
   title={t("filter.title")}
   closeLabel={t("common.close")}
+  closeIcon={<Icon name="close" />}
   descriptor={{ placement: "bottom", align: "start" }}
 >
   {({ close }) => <FilterForm onApply={() => { apply(); close(); }} />}
@@ -54,6 +56,7 @@ Native 예는 없다(renderer 없음).
 | --- | --- | --- | --- |
 | `trigger` | 요소 하나 | 필수 | 여는 버튼. Popover가 ref·aria 속성을 붙인다 |
 | `title` · `closeLabel` | 문자열 | 필수 | 비면 던진다 |
+| `closeIcon` | `ReactNode` | — | 주면 머리 닫기를 ghost `IconButton`(이름 `closeLabel`)으로 그린다. 도구성 행동은 아이콘으로 둔다([IconButton](icon-button.md)). 없으면 기존 글자 버튼 |
 | `description` | 문자열 | — | 제목 아래 설명 |
 | `children` | 노드 또는 `(actions: { close(): void }) => ReactNode` | — | 콘텐츠 안에서 닫을 때 함수형을 쓴다 |
 | `openOn` | `press` · `hover` | `press` | `hover`는 지연된 포인터 진입(열기 300ms·닫기 150ms)을 **더할** 뿐이고 click/Enter/Space 경로는 그대로다 |

package/docs/usage/components/pricing-choice.md

@@ -0,0 +1,85 @@
+# PricingChoice
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.21.0
+- 검토일: 2026-10-16
+- 근거: [작업 선택 계약](../../task-controls.md), `src/task-controls.ts`의 `resolvePriceOption`, 양 renderer `src/task-controls.tsx`
+- 스토리북: `배포/구성/선택과 필터/요금 주기 선택`
+
+## 언제 쓰나
+
+요금제·결제 주기 중 하나를 고르고, 선택한 실제 가격과 혜택을 확인한 뒤 [계속]으로 제품 결제 흐름을 시작할 때 쓴다.
+선택은 controlled callback만 호출하고, 실제 요청은 계속 버튼에서만 시작한다. 실패하면 선택을 유지하고 같은 버튼으로 다시 시도한다.
+묶음 사용 기준은 [선택과 실제 실행](../compositions/task-controls.md)이다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 비동기 실행 없는 단순 선택 | [RadioGroup](radio-group.md) `presentation="card"` |
+| 결제·약관·상품 검증 자체 | 제품 결제 흐름(onContinue 뒤) |
+| 실행 방식 선택 + 즉시 실행 | `SplitAction`([선택과 실제 실행](../compositions/task-controls.md)) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `PricingChoice` | 요금 선택 카드·가격·혜택·계속 | `@hjmds/react/task-controls` | `@hjmds/react-native/task-controls` |
+
+루트 barrel에는 없다. `PriceOption` 타입과 `resolvePriceOption`은 `@hjmds/design-contracts/task-controls`에 있다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { PricingChoice } from "@hjmds/react/task-controls";
+
+<PricingChoice label={t("plan.title")} options={prices} selectedId={selectedId}
+  onSelectionChange={setSelectedId} formatPrice={formatConfirmedPrice}
+  continueLabel={t("plan.continue")} errorLabel={t("plan.failed")}
+  onContinue={option => startCheckout(option.id)} />
+```
+
+```tsx
+// Native
+import { PricingChoice } from "@hjmds/react-native/task-controls";
+
+<PricingChoice label={t("plan.title")} options={prices} selectedId={selectedId}
+  onSelectionChange={setSelectedId} formatPrice={formatConfirmedPrice}
+  continueLabel={t("plan.continue")} errorLabel={t("plan.failed")}
+  onContinue={option => startCheckout(option.id)} />
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | `string` | 필수 | Card 제목이자 RadioGroup 접근성 이름 |
+| `options` | `PriceOption[]` | 필수 | `{ id, label, description?, disabled?, amountMinor, currency, interval: "month" \| "year", intervalCount, benefits }`. `amountMinor`는 0 이상 안전 정수, `currency`는 대문자 3자, `intervalCount`는 1 이상 정수가 아니면 `RangeError` |
+| `selectedId` / `onSelectionChange` | `string` / `(id) => void` | 필수 | controlled. 목록에 없는 id·중복 id는 `TypeError` |
+| `formatPrice` | `(option) => string` | 필수 | 라디오 설명과 선택 가격 줄에 같이 쓴다 |
+| `continueLabel` / `errorLabel` | `string` | 필수 | 계속 버튼·실패 문구 |
+| `onContinue` | `(option) => void \| Promise<void>` | 필수 | 선택 옵션의 고정된(frozen) 사본을 받는다. reject하면 실패 표시 |
+| `disabled` | `boolean` | `false` | 선택과 계속을 모두 잠근다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | Card 하나 안에 RadioGroup `presentation="card"`, 계속 Button 기본 크기 | 양 renderer `PricingChoice` |
+| 간격 | Card 안 `Stack gap="md"`(16) | 같은 구현, `foundations.ts` space.md |
+| 순서·정렬 | Card 제목 → 주기별 라디오 카드 → 선택한 가격(strong) → 혜택 줄 → [계속] → 실패 문구(가운데 정렬) | 렌더 순서 |
+| 고정·스크롤 | 자체 고정·스크롤 없음 | 별도 scroller 없음 |
+| 좁은 폭·큰 글자 | 라디오 카드·혜택 Text는 줄바꿈되고 버튼은 Card 폭 안에 머문다 | 양 renderer |
+
+## 꼭 지킬 것
+
+- `formatPrice`는 실제 `amountMinor`·`currency`·`interval`·`intervalCount`와 일치해야 한다. 할인율·월 환산액을 추정해 넣지 않는다.
+- 옵션 선택으로 결제를 시작하지 않는다. 결제·약관·상품 검증은 `onContinue` 뒤 제품 흐름 책임이다.
+- 선택 옵션이 `disabled`이면 계속 버튼도 비활성이다. 비활성 옵션은 선택 callback을 호출하지 않는다.
+
+## 상태와 상호작용
+
+진행 중에는 계속 버튼이 로딩이 되고 라디오 선택이 잠긴다(중복 요청 차단). 실패하면 선택을 유지하고 Card 안에 오류 문구를 가운데 정렬로 표시한다(Web `role="alert"`).