@hjmds/design-contracts 1.12.1 → 1.13.1

package/docs/usage/components/radio-group.md

@@ -0,0 +1,124 @@
+# RadioGroup
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [cross-platform core](../../cross-platform-core-normalization.md), `src/component-recipes.ts`(`selectionGroupRecipe`·`selectionControlRecipe`)
+- 스토리북: `배포/컴포넌트/입력/라디오 버튼 그룹`
+
+## 언제 쓰나
+
+한 화면에 펼쳐 둔 선택지 중 정확히 하나를 고를 때 쓴다. 선택지마다 설명이 붙거나,
+사용자가 모든 보기를 한눈에 비교해야 할 때(배송 방법, 알림 빈도, 신고 사유) 맞다.
+대략 2~6개, 각 항목이 한 행을 차지해도 되는 경우다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 2~4개의 짧은 라벨로 보기·필터를 즉시 전환 | [SegmentedControl](segmented-control.md) |
+| 선택지가 많거나(대략 7개 이상) 공간이 좁음, 폼 한 칸 | [Select](select.md) |
+| 여러 개를 동시에 고름 | [CheckboxGroup](checkbox-group.md) |
+| 켜고 끄는 설정 한 줄 | [Switch](switch.md) |
+| 선택지 사이에 다른 콘텐츠가 끼어 직접 배치해야 함 | [Radio](radio.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `RadioGroup` | 기본 | `@hjmds/react`, `/selection` | `@hjmds/react-native`, `/inputs` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { RadioGroup } from "@hjmds/react/selection";
+
+<RadioGroup
+  label={t("settings.frequency.label")}
+  items={[
+    { value: "daily", label: t("settings.frequency.daily") },
+    { value: "weekly", label: t("settings.frequency.weekly"), description: t("settings.frequency.weeklyHint") },
+  ]}
+  value={frequency}
+  onValueChange={setFrequency}
+/>
+```
+
+```tsx
+// Native
+import { RadioGroup } from "@hjmds/react-native/inputs";
+
+<RadioGroup
+  label={t("settings.frequency.label")}
+  items={[
+    { value: "daily", label: t("settings.frequency.daily") },
+    { value: "weekly", label: t("settings.frequency.weekly") },
+  ]}
+  value={frequency}
+  onValueChange={(next) => next && setFrequency(next)}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `items` | Web `readonly { value: string; label: ReactNode; description?; disabled? }[]` · Native `readonly { value: Value; label: string; description?; disabled?; accessibilityHint?; leading? }[]` | 필수 | 비거나 값이 중복되면 `TypeError` |
+| `value` · `defaultValue` | 항목 값 · `null` | `null` | 선택 없음 허용. items에 없는 값이면 `RangeError` |
+| `onValueChange` | Web `(value: string) => void` · Native `(value: Value \| null) => void` | — | 고를 때 호출 |
+| `orientation` | `vertical` · `horizontal` | `vertical` | Native는 글자 크기 160% 이상이면 가로를 세로로 쌓는다 |
+| `presentation` | `plain` · `card` · `grouped` | `card` | `grouped`는 한 카드 안에 행이 붙는다 |
+| `size` | `small` · `medium` | `medium` | — |
+| `required` | `boolean` | `false` | 켜면 초기 선택을 보정한다 |
+| `description` · `error` | Web `ReactNode` · Native `string` | — | 그룹 설명·오류 문구 |
+| `disabled` · `readOnly` | `boolean` | `false` | — |
+| `renderLeading` | `(item, appearance) => ReactNode` — appearance Web `{ selected, color: "currentColor", size }`, Native `{ checked, selected, disabled, readOnly, color, size }` | — | 항목 앞 제품 아이콘 |
+| `label` / `accessibilityLabel` | 문자열(Web `label`은 `ReactNode`) | — | 둘 중 하나 필수. 보이는 제목이 없으면 `accessibilityLabel` |
+| `layoutStyle` | 배치 전용 style 객체 | — | 그룹 프레임 배치 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 행 최소 높이 `medium` 56 · `small` 44. 행 안쪽은 [Radio](radio.md#배치)와 같다. `grouped`는 그룹이 테두리 1·모서리 `radius.lg` 16을 갖는다 | `layout.rowHeight.singleLine`, `control.minTouchTarget`, `.hjm-radio-group[data-presentation="grouped"]` |
+| 간격 | 항목 사이 세로 `plain` `spacing.xxs` 4 · `card` `spacing.xs` 8 · `grouped` 0, 가로 `plain` `spacing.sm` 12 · `card` `spacing.md` 16 · `grouped` 0. 제목·항목·설명·오류 사이 `spacing.xs` 8 | `selectionGroupRecipe.orientations`·`supportGap` |
+| 순서·정렬 | 제목 맨 위. 설명은 항목 **위**(`selectionGroupRecipe.slots` 순서, 두 플랫폼). 오류는 항목 아래이며 있으면 설명을 대신한다. 폼 저장 버튼은 그룹 아래 | `selection.tsx`(RadioGroup), Native `inputs.tsx` |
+| 고정·스크롤 | 고정되지 않는다. 폼·화면 본문 스크롤 안에 둔다 | — |
+| 좁은 폭·큰 글자 | Web 가로 배치는 넘치면 다음 줄로 감긴다(`flex-wrap`). Native 가로 배치는 감지 않고 글자 크기 160% 이상에서 세로로 바뀐다. 가로 배치는 짧은 선택지 2~3개에만 쓴다 | `.hjm-radio-group[data-orientation="horizontal"]`, `largeTextThreshold` 1.6 |
+
+```text
+card(vertical)                 grouped(vertical)
+알림 받기                       알림 받기
+ └ gap spacing.xs 8
+┌─────────────────────┐       ┌─────────────────────┐
+│ ◉ 모두              │ 56    │ ◉ 모두              │
+└─────────────────────┘       │ ○ 멘션만            │
+   gap spacing.xs 8           │ ○ 받지 않음         │
+┌─────────────────────┐       └─────────────────────┘  radius.lg 16
+│ ○ 멘션만            │
+└─────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- `items`가 비었거나 항목 `value`·문자열 `label`이 비었거나 `value`가 중복되면 렌더 중 `TypeError`,
+  `value`/`defaultValue`가 items에 없으면 `RangeError`를 던진다. 서버 목록은 정리한 뒤 넘긴다.
+- 옛 Native `options` prop은 1.11에서 제거됐다. 넘기면 `TypeError`다([이관표](../../migration-native-legacy-removal.md)).
+- 오류 문구는 `error`로 넘긴다. 그룹 아래에 별도 Text로 직접 그리지 않는다.
+- 배치는 `layoutStyle`로 한다. Native의 `style`과 slot style(`controlStyle`·`indicatorStyle`·`labelStyle` 등)은 deprecated
+  (개발 모드 경고, 다음 major 제거)다([소비 정책 §3.1](../../consumer-policy.md)). 외형은 `presentation`·`size`·`renderIndicator`로 바꾼다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `onValueChange` 값 | `string` | `Value \| null`(제네릭) |
+| `label`·항목 `label` 타입 | `ReactNode` | `string` |
+| 항목 `leading`·`accessibilityHint` | 없음 | 있음 |
+| indicator 숨김·교체 | 없음 | `indicator="none"`, `renderIndicator` |
+| 낭독 문구 `requiredLabel`·`readOnlyLabel`·`invalidLabel`, `invalid` | 없음 | 있음 |
+| `name` | 있음(기본 자동 생성) | 없음 |
+| 루트 요소 | `<fieldset>` + `<legend>` | `View` `accessibilityRole="radiogroup"` |

package/docs/usage/components/radio.md

@@ -0,0 +1,104 @@
+# Radio
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: `src/component-recipes.ts`(`selectionControlRecipe`). 별도 계약 문서는 없다
+- 스토리북: `배포/컴포넌트/입력/라디오 버튼`
+
+## 언제 쓰나
+
+라디오 한 개를 제품이 직접 배치해야 할 때만 쓴다. 예: 선택지 사이에 다른 콘텐츠가 끼어 있어
+한 묶음 목록으로 그릴 수 없는 경우. 선택 상태는 제품이 들고 `checked`로 내려 준다.
+선택지가 한 곳에 모여 있으면 거의 항상 [RadioGroup](radio-group.md)이 맞다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 모여 있는 2개 이상 선택지 중 하나(그룹 상태·키보드 이동 포함) | [RadioGroup](radio-group.md) |
+| 2~4개의 짧은 보기 전환(어떤 목록을 볼지) | [SegmentedControl](segmented-control.md) |
+| 선택지가 많거나 화면 공간이 좁음 | [Select](select.md) |
+| 켜고 끄기 | [Switch](switch.md), [Checkbox](checkbox.md) |
+| 여러 개를 동시에 고름 | [CheckboxGroup](checkbox-group.md), [ToggleGroup](toggle-group.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Radio` | 기본 | `@hjmds/react`, `/selection` | `@hjmds/react-native`, `/inputs` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+// 같은 묶음은 name을 같게 둔다
+import { Radio } from "@hjmds/react/selection";
+
+<Radio
+  name="delivery"
+  value="pickup"
+  label={t("order.delivery.pickup")}
+  checked={method === "pickup"}
+  onCheckedChange={() => setMethod("pickup")}
+/>
+```
+
+```tsx
+// Native
+import { Radio } from "@hjmds/react-native/inputs";
+
+<Radio
+  label={t("order.delivery.pickup")}
+  checked={method === "pickup"}
+  onCheckedChange={() => setMethod("pickup")}
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` | Web `ReactNode` · Native `string` | 필수 | 현지화 |
+| `presentation` | `plain` · `card` · `grouped` | `card` | — |
+| `size` | `small` · `medium` | `medium` | — |
+| `checked` · `defaultChecked` | `boolean` | `false` | Web은 제어하면 `onCheckedChange` 필수 |
+| `onCheckedChange` | `(checked: true) => void` | — | 라디오는 스스로 해제되지 않아 항상 `true`로만 불린다. 해제는 제품이 다른 항목을 선택해 `checked`를 내려서 한다 |
+| `onChange`(Web) | `(event: ChangeEvent<HTMLInputElement>) => void` | — | 원시 input 이벤트 |
+| `renderLeading` | Web `(appearance: { selected, color: "currentColor", size }) => ReactNode` · Native `(props: { checked, selected, disabled, readOnly, color, size }) => ReactNode` | — | 앞 제품 아이콘 |
+| `renderIndicator`(Native) | `(props) => ReactNode`(위 Native 모양) | 기본 dot | `indicator="none"`이면 숨긴다 |
+| `description`, `readOnly`, `disabled` | — | `readOnly` `false` | 두 renderer에 있다 |
+| `layoutStyle` | 배치 전용 style 객체 | — | 행 배치. Web `style`은 안쪽 input에 붙는다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 행 최소 높이 `medium` 56 · `small` 44. 표시 원 `medium` 24 · `small` 20. `plain`은 Native hitSlop `medium` 10 · `small` 12로 터치 영역을 넓힌다 | `selectionControlRecipe.sizes`, `control.selectionIndicator` |
+| 간격 | 원과 글자 사이 `medium` `spacing.sm` 12 · `small` `spacing.xs` 8. `card`·`grouped` 안쪽 여백 `medium` 세로 `spacing.sm` 12·가로 `spacing.md` 16, `small` 세로 `spacing.xs` 8·가로 `spacing.sm` 12. `card` 모서리 `radius.md` 12, 테두리 1. `plain`은 여백·테두리 없음. 글자와 설명 사이 `spacing.xxs` 4 | `selectionControlRecipe.sizes`·`presentations`, `.hjm-choice`, `.hjm-choice__copy` |
+| 순서·정렬 | 표시 원이 시작 쪽(LTR 왼쪽), 글자가 그 뒤, 설명은 글자 아래. RTL은 좌우가 바뀐다. 여러 개는 단독으로 늘어놓지 말고 [RadioGroup](radio-group.md)에 넣는다 | `.hjm-choice`, Native `inputs.tsx` |
+| 고정·스크롤 | 고정되지 않는다. 폼·본문 스크롤 안에 둔다 | — |
+| 좁은 폭·큰 글자 | Native는 부모 폭을 채운다(`alignSelf: "stretch"`). Web 단독 Radio는 내용 폭(`inline-flex`)이고 RadioGroup 세로 목록 안에서만 꽉 찬다. 글자가 커지면 행 높이가 늘어난다(최소 높이만 고정) | Native `inputs.tsx`, `.hjm-choice` |
+
+## 꼭 지킬 것
+
+- `label`은 i18n 문구로 넣는다. Native는 `string`만 받는다.
+- 묶음의 접근성 이름(fieldset/radiogroup)은 Radio가 만들지 않는다. 단독 Radio 여러 개로 묶음을
+  흉내 내지 말고 RadioGroup을 쓴다.
+- 선택 표시는 indicator(dot)가 맡는다. 색만으로 선택을 알리도록 바꾸지 않는다.
+- 배치는 `layoutStyle`로 한다. Native의 `style`·`controlStyle`·`labelStyle` 등 slot style은 deprecated(개발 모드 경고,
+  다음 major 제거)다. 색·글자·radius·높이를 덮지 않는다([소비 정책 §3.1](../../consumer-policy.md)).
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| `label`·`description` 타입 | `ReactNode` | `string` |
+| 묶음 연결 | `name`(HTML input 속성) | 없음, 제품이 상태로 묶음 |
+| `required`·`invalid`와 낭독 문구(`requiredLabel`·`invalidLabel`·`readOnlyLabel`) | `required`만 HTML 속성 | 있음 |
+| indicator 숨김·교체 | 없음 | `indicator="none"`, `renderIndicator` |
+| 앞 아이콘 | `renderLeading` | `leading`, `renderLeading` |
+| 이벤트 | `onCheckedChange`, 원시 `onChange` | `onCheckedChange` |
+| 배치 | `layoutStyle`(루트 `<label>`), `style`은 안쪽 input | `layoutStyle`(행) |

package/docs/usage/components/result.md

@@ -0,0 +1,116 @@
+# Result
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 1.12.1
+- 검토일: 2026-10-06
+- 근거: [Result](../../result.md), `src/result.ts`(`resultRecipe`)
+- 스토리북: `배포/컴포넌트/상태와 알림/결과 안내`
+
+## 언제 쓰나
+
+사용자 행동 뒤 흐름이 **끝난** 화면에 쓴다. 결제·제출 성공, 제출 실패, 존재하지 않는 페이지처럼
+상태 하나와 최대 두 개의 다음 행동(다른 곳으로 이동, 다시 시도)을 보여 준다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 목록·검색 결과가 비었고 조건이 바뀌면 채워짐 | [EmptyState](empty-state.md) |
+| 화면 일부 구역 실패, 나머지는 정상 | [Notice](notice.md) + 재시도 |
+| 최초 로딩 | [Skeleton](skeleton.md) |
+| 잠깐 알리고 사라지는 결과 | [Toast](toast.md) |
+| 확인이 필요한 결정 | [AlertDialog](alert-dialog.md) |
+
+상태 화면 조합 전체는 [1.4 제품 채택 가이드 · 상태 화면](../../product-adoption-1.4.md#상태-화면)을 따른다.
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `Result` | 기본 | `@hjmds/react`, `/feedback` | `@hjmds/react-native`, `/feedback` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { Result } from "@hjmds/react/feedback";
+
+<Result
+  status="success"
+  title={t("checkout.done.title")}
+  description={t("checkout.done.body")}
+  actions={[
+    { label: t("checkout.done.viewOrder"), onAction: openOrder },
+    { label: t("common.goHome"), onAction: goHome },
+  ]}
+/>
+```
+
+```tsx
+// Native
+import { Result } from "@hjmds/react-native/feedback";
+
+<Result
+  status="failure"
+  title={t("upload.failed.title")}
+  description={t("upload.failed.body")}
+  actions={[{ label: t("common.retry"), onAction: retry }]}
+  renderIcon={({ color }) => <AlertGlyph color={color} size={28} />} // 제품 소유 glyph
+/>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `status` | `success` · `failure` · `info` | 필수 | 403/404/500 같은 HTTP 의미는 제품이 `failure`와 자기 문구로 번역한다 |
+| `title` | `string` | 필수 | 현지화 |
+| `description` | `string` | — | — |
+| `actions` | 0~2개 `readonly { label: string; onAction(): void; accessibilityLabel?: string }[]` | — | 첫째가 primary Button, 둘째가 secondary Button. `accessibilityLabel` 생략 시 `label`. 3개 이상이면 `RangeError` |
+| `icon`(Web) | `ReactNode` | — | 제품 glyph. 의미는 title·status가 이미 전한다 |
+| `renderIcon`(Native) | `(props: { status, color: string, backgroundColor: string }) => ReactNode` | — | 받은 `color`로 그린다 |
+| `headingLevel`(Web) | `1` · `2` | `2` | 화면 전체가 Result면 `1` |
+| `layoutStyle` | 배치 전용 style 객체 | — | 바깥 여백·폭만 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 아이콘 원 56×56(Web `3.5rem`), `radius.full`. Web 설명 최대 폭 `40rem` | `.hjm-result__icon`, `.hjm-result__description`, Native `feedback.tsx` |
+| 간격 | 안쪽 여백 위아래 `spacing.xxxl` 40, 좌우 `spacing.xl` 24. 요소 사이 `spacing.sm` 12. 행동 줄은 `spacing.xs` 8을 더 띄우고 버튼 사이 `spacing.sm` 12. 목록·카드 사이에 넣을 때는 앞뒤 `layout.sectionGap` 24 | `resultRecipe.paddingVertical`·`paddingHorizontal`·`gap`·`actionsGap`, `.hjm-result__actions` |
+| 순서·정렬 | 가운데 정렬 세로 묶음: 아이콘 → 제목 → 설명 → 행동. 행동은 [Button](button.md#배치) 규칙대로 **secondary(둘째) → primary(첫째)** 순서로 그린다(두 표면 동일. 1.12.1까지는 primary가 먼저였다) | `feedback.tsx`(Web·Native Result) |
+| 고정·스크롤 | 고정되지 않는다. 화면 전체를 채울 때는 Result를 세로 가운데에 두고 하단 고정 CTA를 따로 붙이지 않는다(행동은 `actions`) | — |
+| 좁은 폭·큰 글자 | 행동 줄은 가운데 정렬로 넘치면 다음 줄로 감긴다. 제목·설명은 줄바꿈된다(`overflow-wrap: anywhere`) | `.hjm-result__actions`(flex-wrap), Native `flexWrap: "wrap"` |
+
+```text
+┌──────────────────────────────┐
+│          (padding 40)        │
+│             ( ✓ )  56        │
+│          gap 12              │
+│        결제를 마쳤어요         │  titleLarge
+│      영수증을 메일로 보냈어요    │  body, max 40rem(Web)
+│        gap 12 + 8            │
+│   [ 홈으로 ] [ 주문 보기 ]    │  secondary → primary, gap 12
+│          (padding 40)        │
+└──────────────────────────────┘
+```
+
+## 꼭 지킬 것
+
+- 행동이 3개 이상이면 `RangeError`를 던진다. 잘리지 않으니 흐름을 다시 설계한다.
+- 행동 버튼을 children으로 직접 조립하지 않는다(`children` prop이 없다). `actions`로 넘긴다.
+- 아이콘은 제품 소유 glyph다. Web은 `icon`, Native는 `renderIcon`이 주는 `color`를 그대로 쓴다.
+  아이콘 배경·tone 색은 HJM(`resultRecipe.tones`) 소유다.
+- `failure`는 Web `role="alert"`, Native live region·iOS 낭독으로 바로 알린다. 같은 실패를 Toast로
+  한 번 더 알리지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 아이콘 | `icon`(ReactNode) | `renderIcon({ status, color, backgroundColor })` |
+| 제목 heading 수준 | `headingLevel` | `accessibilityRole="header"` 고정 |
+| 실패 알림 | `role="alert"`(그 외 `status`) | assertive live region, iOS는 `announceForAccessibility` |
+| 바깥 배치 | `className`, `layoutStyle`(HTML `style`도 받음) | `layoutStyle`(`style`은 deprecated — 개발 모드 경고, 다음 major 제거) |

package/docs/usage/components/saved-items-screen.md

@@ -0,0 +1,126 @@
+# SavedItemsScreen
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 계약](../../screen-patterns.md); 저장한 항목을 Instagram의 컬렉션 탐색 방식으로 바꾸라는 사용자 요청. 기존 ListDetailScreen·Grid를 합성하며 별도 저장 엔진은 만들지 않는다. 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/화면/콘텐츠/저장한 항목`
+
+## 언제 쓰나
+
+저장한 이미지·게시물을 컬렉션 표지 → 사진 격자 → 상세 순서로 탐색할 때 쓴다.
+공통 규격은 컬렉션 2열과 게시물 3열, 뒤로가기, 빈 컬렉션이다. 저장·해제·Undo·권한·라우팅은 제품 상태를 콜백으로 연결한다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 텍스트 중심의 즐겨찾기 목록 | ListDetailScreen + ListRow |
+| 검색·조건 변경이 주 행동 | SearchScreen |
+| 상품 구매·결제가 주 행동 | 제품 화면 + ScreenLayout |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `SavedItemsScreen` | 컬렉션·격자·상세 화면 | `@hjmds/react/saved-items` | `@hjmds/react-native/saved-items` |
+| `SavedItem` · `SavedCollection` · `SavedItemsLabels` | 데이터·문구 타입 | 같은 subpath의 타입 | 같은 subpath의 타입 |
+
+루트 barrel에는 추가하지 않는다. 전용 화면이 불필요한 앱에 화면 의존성을 강제하지 않기 위해 별도 진입점을 쓴다.
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { SavedItemsScreen } from "@hjmds/react/saved-items";
+
+<SavedItemsScreen title={t("saved.title")} items={items} collections={collections}
+  {...(collectionId !== undefined ? {collectionId} : {})}
+  selectedItemId={selectedItemId}
+  labels={{allItems:t("saved.all"),privateNotice:t("saved.private"),back:t("common.back"),empty:t("saved.empty"),createCollection:t("saved.create")}}
+  onOpenCollection={openCollection} onOpenItem={openItem} onBack={goBack}
+  onCreateCollection={openCreateSheet}
+  renderThumbnail={renderThumbnail} renderDetail={renderDetail}/>
+```
+
+```tsx
+// Native — 저장 해제는 renderDetail 머리의 ghost IconButton
+import { Image } from "react-native";
+import { IconButton } from "@hjmds/react-native/actions";
+import { Stack, Text } from "@hjmds/react-native/primitives";
+import { SavedItemsScreen } from "@hjmds/react-native/saved-items";
+
+<SavedItemsScreen title={t("saved.title")} items={items} collections={collections}
+  {...(collectionId !== undefined ? { collectionId } : {})}
+  selectedItemId={selectedItemId}
+  labels={{ allItems: t("saved.all"), privateNotice: t("saved.private"), back: t("common.back"),
+    empty: t("saved.empty"), createCollection: t("saved.create") }}
+  onOpenCollection={openCollection} onOpenItem={openItem} onBack={goBack}
+  onCreateCollection={openCreateSheet}
+  renderThumbnail={(post) => <Image source={{ uri: post.imageUrl }} resizeMode="cover" style={{ width: "100%", height: "100%" }} />}
+  renderDetail={(post) => <Stack gap="md">
+    <Stack axis="inline" align="center" justify="between">
+      <Text emphasis="strong">{post.title}</Text>
+      <IconButton label={t("saved.unsave", { title: post.title })} tone="ghost" onPress={() => unsave(post.id)}>
+        <BookmarkIcon />
+      </IconButton>
+    </Stack>
+    <PostDetail post={post} />
+  </Stack>} />
+```
+
+썸네일은 해당 플랫폼 이미지로 슬롯 전체 크기를 `cover`로 채운다.
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| items | `readonly {id,title,...}[]`, 필수 | — | 현재 저장된 항목. 해제된 항목은 이 배열에서 제거 |
+| collections | `readonly {id,title,itemIds:readonly string[]}[]`, 필수 | — | 제품이 관리하는 컬렉션과 멤버십 |
+| collectionId | `string` 또는 `null` | `undefined` | 생략하면 컬렉션 홈, `null`이면 모든 게시물, 문자열이면 해당 컬렉션 |
+| selectedItemId | `string` 또는 `null`, 생략 시 상세 없음 | — | 현재 컬렉션에 존재하는 항목만 상세로 표시 |
+| labels | SavedItemsLabels, 필수 | — | 모든 공개 문구를 지역화하여 공급 |
+| onOpenCollection · onOpenItem · onCreateCollection | 콜백, 필수 | — | 제품 상태/라우터 변경 요청 |
+| onBack | `() => void`, 필수 | — | 한 단계만 올라간다. 상세가 열려 있으면 제품이 `selectedItemId`를 비우고, 아니면 `collectionId`를 생략해 컬렉션 홈으로 간다. 화면은 제품 history를 모른다 |
+| actions · leading | ScreenLayout 상속 | 없음 | 홈에서는 제품 `actions` 대신 컬렉션 만들기 버튼이 그 자리를 쓰고 제품 `leading`은 유지된다. 컬렉션·상세에서는 `leading`이 뒤로 버튼이 되고 제품 `actions`가 보인다 |
+| renderThumbnail · renderDetail | `(item) => ReactNode`, 필수 | — | 사진·상세 슬롯, API·자산은 제품 소유 |
+| state · notice | ScreenLayout 상속 | ready · 없음 | 조회 상태, 저장 해제/복구 안내 |
+| layoutStyle | `HjmCompositionStyleProp` | 없음 | Web·Native 모두 목록·상세를 담는 ListDetailScreen 바깥 틀에 적용한다(컬렉션·격자·상세 전환과 상관없이 같은 루트). 미게시(1.12.1 이후) |
+| className(Web) | `string` | 없음 | 안쪽 목록 ScreenLayout에 붙는다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | host의 남은 높이 100%, ScreenLayout 폭(최대 720); 컬렉션 표지·게시물 썸네일 1:1, 표지 radius `radius.md` | `ListDetailScreen`, Web `.hjm-saved-*`, Native `saved-items.tsx` |
+| 간격 | 화면 padding `spacing.md` 16; 개인 저장 안내–격자 `spacing.md` 16; 컬렉션 2열 간격 `spacing.md` 16; 표지 4장 사이·게시물 3열 간격 `spacing.xxs` 4; 표지–컬렉션 제목 `spacing.sm` 12 | `Stack gap="md"`, `Grid gap`, Web `.hjm-saved-collection`, Native `gap: spacing.sm` |
+| 순서·정렬 | 홈: 헤더(제목 → 새 컬렉션) → 개인 저장 안내 → 모든 게시물 → 사용자 컬렉션; 컬렉션: 헤더(뒤로 → 컬렉션 제목) → 사진 격자 또는 빈 안내; 상세: 헤더(뒤로 → 항목 제목) → `renderDetail` | `SavedItemsScreen` 렌더 순서 |
+| 고정·스크롤 | 헤더 고정, 본문 스크롤; 상세 동안 격자 mount 유지 | ListDetailScreen·ScreenLayout |
+| 좁은 폭·큰 글자 | 좁은 폭(320 창, 본문 288)에서도 컬렉션 2열·사진 3열을 유지한다. 열 수는 사용 가능 폭이 컬렉션 176 미만(최소 열 폭 80), 사진 140 미만(최소 열 폭 44)일 때만 줄어든다; 컬렉션 제목은 줄바꿈; 사진 속 글자를 유일한 이름으로 쓰지 않는다(버튼 접근성 이름은 `title`) | `Grid minColumnWidth`, `grid.ts` 열 계산 |
+
+### 행동 위치
+
+| 행동 | 컴포넌트·tone | 위치 | 개수·순서 |
+| --- | --- | --- | --- |
+| 새 컬렉션 | `Button` ghost(`labels.createCollection`) → `onCreateCollection` | 홈 헤더 `actions` 자리(홈에 넘긴 제품 `actions`는 그리지 않는다). 생성 Sheet와 그 footer 확정 버튼은 제품이 그린다 | 홈에서만 1개. 컬렉션·상세에서는 제품 `actions`로 바뀐다 |
+| 뒤로 | `Button` ghost(`labels.back`) → `onBack` | 컬렉션·상세 헤더 `leading` | 1개. 상세 → 격자 → 홈으로 한 단계씩, 단계는 제품이 상태를 비워 정한다 |
+| 컬렉션·게시물 열기 | 표지·썸네일 전체가 버튼 → `onOpenCollection` · `onOpenItem` | 격자 각 칸 | 항목마다 1개 |
+| 저장 해제 | `IconButton` ghost(제품) | `renderDetail` 머리 줄 끝(제목과 같은 줄) | 상세마다 1개. 실행 취소는 `notice` |
+
+## 꼭 지킬 것
+
+- 컬렉션 홈으로 돌아갈 때 `collectionId` prop을 생략한다. `null`은 모든 게시물을 뜻한다.
+- 저장 해제의 서버 실패/Undo는 앱이 관리한다. 예제의 메모리 저장을 서버 저장으로 주장하지 않는다.
+- 항목·컬렉션 ID와 제목은 비지 않고 ID는 고유해야 한다. 삭제된 컬렉션은 홈으로 복귀하고 없는 멤버는 렌더에서 제외한다.
+- 상세가 열리면 제목·뒤로·상세만 표시한다. 생성 시트의 확정 행동은 footer 한 곳에 둔다.
+- 제품이 목록을 필터링하거나 정렬하여 공급한다. 사진 권한·서버 페이지네이션은 이 화면이 수행하지 않는다.
+
+## 함정
+
+- 홈 화면에 보여야 할 제품 행동을 `actions`로 넘기면 그려지지 않는다(홈에서는 컬렉션 만들기가 그 자리를 쓴다). Web·Native가 같은 규칙이라 바꾸려면 두 renderer의 API 결정이다.
+- `onBack`에서 `collectionId`와 `selectedItemId`를 한꺼번에 비우면 상세에서 바로 홈으로 건너뛴다.
+
+- 비공개 안내는 권한 구현이 아니다. 서버에서 소유자 접근을 검사한다.
+- HTML/WebView나 Instagram 자산을 복사하는 구현이 아니다. 제품 사진·테마·문구를 슬롯으로 전달한다.

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

@@ -0,0 +1,119 @@
+# ScreenLayout
+
+- 단계: 컴포넌트
+- 상태: 배포
+- 지원: Web · Native
+- 적용: 미게시(1.12.1 이후)
+- 검토일: 2026-10-06
+- 근거: [반복 화면 조합](../../screen-patterns.md), Web·Native `src/screens.tsx`·`src/screen-flows.tsx`; 기존 개별 지침을 새 규격으로 통합. 예제 스토리는 2026-10-06 사용자 승인으로 스토리북 배포([승인 기록](../../../../../docs/STORYBOOK_NAVIGATION.md#21-2026-10-06-전체-승격과-규격-확정)). 스토리북 배포는 API 게시가 아니다(`적용` 참고)
+- 스토리북: `배포/화면/화면 틀과 도구/화면 골격과 상태`
+
+## 언제 쓰나
+
+한 라우트 화면의 뼈대가 필요할 때 쓴다. 제목·뒤로 가기 슬롯·도구, 안내(notice), 본문,
+하단 행동을 한 화면으로 배치하고, 화면 전체의 로딩·빈 상태·오류·접근 제한을 본문 자리에서 교체한다.
+데이터 조회·권한 판단·라우팅은 제품 소유다.
+
+## 쓰지 않을 때
+
+| 상황 | 대신 쓸 것 |
+| --- | --- |
+| 앱 전체 navigation·sidebar 셸 | [Layout](layout.md) |
+| 상단 제목 막대만 필요 | [TopBar](top-bar.md) |
+| 하단 고정 주 행동만 필요 | [BottomCTA](bottom-cta.md) |
+| 설정·검색·알림·채팅 화면 | [SettingsScreen](settings-screen.md), [SearchScreen](search-screen.md), [NotificationInboxScreen](notification-inbox-screen.md), [ChatScreen](chat-screen.md) |
+| 로그인 화면 | [AuthScreenLayout](auth-screen-layout.md) |
+| 흐름이 끝난 결과 화면 | 본문에 [Result](result.md) |
+
+## 공개 이름과 import
+
+| 이름 | 역할 | Web | Native |
+| --- | --- | --- | --- |
+| `ScreenLayout` | supplemental. root에서는 내보내지 않는다 | `/screens` | `/screens` |
+
+## 최소 사용 예
+
+```tsx
+// Web
+import { IconButton } from "@hjmds/react/actions";
+import { BottomCTA } from "@hjmds/react/bottom-cta";
+import { ScreenLayout } from "@hjmds/react/screens";
+
+<ScreenLayout
+  title={t("saved.title")}
+  leading={<IconButton label={t("common.back")} onClick={goBack}><BackGlyph /></IconButton>}
+  state={isLoading ? { kind: "loading", title: t("saved.loading") } : { kind: "ready" }}
+  footer={<BottomCTA primaryAction={{ label: t("saved.add"), onClick: add }} />}
+>
+  <SavedList items={items} />
+</ScreenLayout>
+```
+
+```tsx
+// Native — FlatList 본문은 scroll="content"
+import { FlatList } from "react-native";
+import { Button } from "@hjmds/react-native/actions";
+import { ScreenLayout } from "@hjmds/react-native/screens";
+
+<ScreenLayout
+  title={t("saved.title")}
+  scroll="content"
+  state={error ? { kind: "error", title: t("saved.error") } : { kind: "ready" }}
+  stateAction={<Button onPress={refetch}>{t("common.retry")}</Button>}
+>
+  <FlatList data={items} renderItem={renderItem} />
+</ScreenLayout>
+```
+
+## 축과 기본값
+
+| prop | 값 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `title` | `string` | 필수 | 화면 제목. `header`를 주면 접근성 이름으로만 쓴다 |
+| `header` | `ReactNode` | 없음 | 기존 navigator 헤더 유지용. 주면 기본 헤더(`leading`·제목·`description`·`actions`)를 그리지 않는다 |
+| `description` | `string` | 없음 | 제목 아래 muted 설명 |
+| `leading` · `actions` | `ReactNode` | 없음 | 제목 앞(뒤로 가기)·뒤(도구) 슬롯 |
+| `notice` | `ReactNode` | 없음 | 헤더 아래 비차단 안내. 상태 교체 중에도 남는다 |
+| `footer` | `ReactNode` | 없음 | 하단 고정 행동 |
+| `state` | `{ kind: "ready" }` · `{ kind: "loading" \| "empty" \| "error" \| "restricted"; title; description? }` | `{ kind: "ready" }` | ready가 아니면 children을 그리지 않고 상태와 `stateAction`을 가운데에 놓는다. 로딩은 Spinner 하나만 보이고 `title`·`description`은 Spinner의 접근성 이름이 된다 |
+| `stateAction` | `ReactNode` | 없음 | 상태 안내 아래 행동(재시도 등) |
+| `scroll` | `"screen"` · `"content"` | `"screen"` | `content`는 본문 자식(가상화 목록)이 스크롤을 소유한다. 상태 교체 중에는 `screen`으로 돌아간다 |
+| `contentInset` | `"default"` · `"none"` | `"default"` | `none`은 헤더·notice·본문·footer padding을 0으로(Native는 footer 위 테두리도 뺀다) |
+| `as` (Web) | `"main"` · `"section"` | `"main"` | 제품 셸에 이미 `<main>`이 있으면 `section` |
+| `layoutStyle` | `HjmCompositionStyleProp` | 없음 | 화면 루트 배치 전용(예: 분할 화면의 `flex`·`width`). ScreenLayout 위에 만든 화면은 모두 이 prop을 루트까지 넘긴다 |
+| `className` (Web) | `string` | 없음 | 식별·배치 보조. 색·여백을 덮지 않는다 |
+| `testID` · `scrollRef` · `scrollProps` (Native) | `string` · `Ref<ScrollView>` · `refreshControl`·`keyboardDismissMode`·스크롤 막대 표시 | 없음 | ScrollView가 있을 때(`scroll="screen"` 또는 상태 교체 중)만 `scrollRef`·`scrollProps`가 연결된다 |
+
+## 배치
+
+| 항목 | 값 | 근거 |
+| --- | --- | --- |
+| 크기 | 폭 100%, 최대 `screenPatternRecipe.maxWidth`(`layout.readingMaxWidth` 720), 가운데 정렬; 높이는 host가 준 남은 높이(Web `block-size: 100%`, Native `flex: 1`) | Web `.hjm-screen`, Native `ScreenLayout` |
+| 간격 | 바깥 padding `screenPatternRecipe.padding`(`spacing.md` 16)을 헤더 사방·notice 좌우·본문 사방·footer 사방에 준다(`contentInset="none"`이면 0); 헤더 안 `leading`·제목·`actions` 간격 `itemGap`(`spacing.sm`) 12(두 플랫폼, `contentInset="none"`이어도 유지); 상태 안내는 위아래 `sectionGap`(`spacing.xl`) 24, 안내–`stateAction` `stateGap`(`spacing.md`) 16 | Web `src/screens.tsx`(`--hjm-screen-item-gap`·`--hjm-screen-state-gap`)·`.hjm-screen__*`, Native `ScreenLayout` |
+| 순서·정렬 | 헤더(`leading` → 제목·설명 → `actions`) → notice → 본문 → footer; 상태 안내는 본문 세로 가운데 | 렌더 순서 |
+| 고정·스크롤 | 헤더·notice·footer 고정, `scroll="screen"`은 본문이 스크롤, `"content"`는 자식이 스크롤; footer 위 테두리 1, Web은 하단 safe area만큼 padding을 늘린다 | Web `data-scroll`·`.hjm-screen__footer`, Native `ScrollView` |
+| 좁은 폭·큰 글자 | 제목 열 최소 폭 `headerMinWidth` 120 × 글자 배율, 모자라면 `actions`가 다음 줄로 내려간다; 제목은 줄바꿈(`overflow-wrap: anywhere`)되고 자르지 않는다; Native safe area·탭바 inset은 host | `screenPatternRecipe.headerMinWidth`, Web `.hjm-screen__heading` |
+
+## 꼭 지킬 것
+
+- Web의 화면 스크롤 본문은 Tab으로 진입할 수 있다. `scroll="content"`의 정상 본문은 자식이 키보드 스크롤을 소유하지만, 오류·빈 상태 등 대체 안내는 화면 스크롤로 바뀌며 Tab 진입도 함께 복원된다.
+- 가상화 목록(FlatList, VirtualList)을 넣으면 `scroll="content"`로 둔다. 스크롤을 이중으로 중첩하지 않는다.
+- 새로고침 실패·저장 오류는 `state`를 바꾸지 말고 `ready` + `notice`로 알린다. `loading`으로 바꾸면 본문이
+  unmount되어 입력 초안이 사라진다.
+- `state.title`·문구는 i18n 키로 넣는다. ready 외 상태의 빈 `title`은 `TypeError`다.
+- Web host는 실제 남은 높이(`height:100%` 등)를, Native host는 safe area·탭바 inset을 먼저 처리한다.
+  HJM은 기종별 높이를 추측하지 않는다.
+- 배치는 Web·Native 모두 `layoutStyle`로 한다(Web은 `className`도 있다). 색·여백을 덮지 않는다.
+
+## 플랫폼 차이
+
+| 항목 | Web | Native |
+| --- | --- | --- |
+| 루트 | `<main>`(`as="section"` 가능), 제목과 연결 | `View`, 제목 `accessibilityRole="header"` |
+| 상태 알림 | error는 `role="alert"`, 그 외 `status` | `accessibilityLiveRegion`(error assertive) |
+| 스크롤 | CSS(`data-scroll`) | `ScrollView`(`keyboardShouldPersistTaps="handled"`) |
+| 배치·식별 | `layoutStyle`, `className` | `layoutStyle`, `testID` |
+
+## 함정
+
+- 이미 `<main>`이 있는 제품 셸 안에서는 `as="section"`을 준다. 중첩 main이 생긴다.